WHAT it does / WHEN to use / WHAT to call NEXT) so the model gets useful guidance without you spelling each call out.
Discovery
The first thing a new chat does is load the pleyor-workflows skill frompleyor://skills/workflows. The skill teaches the patterns; the tools execute them.
| Tool | Scope | Use it when |
|---|---|---|
search | agents:read | Find an agent, app, model, node, asset, or run by name fragment. |
who_am_i | none | Confirm which org the connector is bound to. |
suggest_model | agents:read | Pick a model variant for a kind (image_generation, etc.) + use_case. |
get_effective_ports | agents:read | Resolve the actual port list for a node type given its config (some nodes have dynamic-arity ports). |
get_run_inputs_schema | agents:read | Discover what inputs an agent expects before trigger_run. |
estimate_run_cost | agents:read | Preview credit cost before kicking off a run. |
Building & editing graphs
| Tool | Scope | Use it when |
|---|---|---|
view_agent | agents:read | Show an agent’s current graph. Returns structured nodes/edges AND renders the canvas inline. |
create_agent | agents:write | Build a new agent from a GraphSpec. Auto-layouts, validates, saves. |
replace_graph | agents:write | Replace an existing agent’s graph with a new GraphSpec. The only mutation tool — no add_node / update_node; design the whole graph and replace. |
validate_graph | agents:read | Validate a spec before saving. Returns typed errors with next_action hints. |
update_agent | agents:write | Update agent metadata (name, description, etc.). |
clone_agent | agents:write | Duplicate an existing agent. |
delete_agent | agents:write | Soft-delete an agent. |
restore_version | agents:write | Roll back to a saved version. |
Running & monitoring
| Tool | Scope | Use it when |
|---|---|---|
trigger_run | runs:execute | Run an agent with optional inputs. Returns the new run_id. |
trigger_app | apps:execute | Run a published app with the values its input schema expects. |
wait_for_run | runs:read | Block until a run reaches completed / failed / cancelled / paused. Pass timeout_ms up to 110000 to bound the wait. Almost always preferable to polling pleyor://runs/{id}. |
cancel_run | runs:execute | Cancel an in-progress run. |
list_runs | runs:read | List recent runs, filtered by agent_id / status. |
Publishing & sharing
| Tool | Scope | Use it when |
|---|---|---|
publish_app | apps:execute | Turn an agent into a public app with a defined inputSchema. |
share_agent / unshare_agent | agents:write | Generate or revoke a read-only share link. |
submit_review | apps:execute | Submit an app for review (when reviews are enabled). |
upload_asset | assets:write | Upload an image / video / audio / file as a Pleyor asset that downstream nodes can reference. |
Workflow skill
The server’s top-levelinstructions field directs new agents to read pleyor://skills/workflows — a markdown playbook covering:
- The mental model (agents, nodes, ports, runs, apps, versions, assets)
- 6 canonical workflow patterns (text→image, image→video, brand-aware multimodal, branching, fan-out, human-in-the-loop)
- Build / edit / run / reuse / wait / iterate playbooks
- An error-recovery playbook keyed on the typed
error.codereturned from failed tools - Cost-aware patterns and anti-patterns
See also
Resources
The
pleyor:// reads your assistant should make before designing.Errors
The error codes, what they mean, and how to recover.