Agents-Core

Overview Schema Source Related Servers Discussions Admin

Run a flow

run_flow

Start a user-requested flow in the caller's repository, resolve its source, and return the workflow instructions and metadata for client-side execution.

Instructions

Start a user-requested flow in the CALLER's repository.

flow: a bare ID, ID.md, flows/ID.md, or builtin:/user:/repo:<id>. A bare ID
resolves repo:, then user:, then builtin:. request carries the user's scope,
PR/MR URL and constraints such as no-merge. repo_path defaults to the caller
workspace; an override must be an existing directory within it.
HTTP requires X-Agents-Workspace. Stdio uses AGENTS_CLIENT_REPO_ROOT, else
workspace when it lies inside the client's MCP roots, else the project
inferred from CLAUDE_PROJECT_DIR or cwd. A filesystem root, the home directory
or a system or program directory (also as the override) is refused with
workspace_unsafe, and a cwd without .git or CLAUDE.md with workspace_required.

Returns needs_execution with flow metadata, content, repo_path, workspace_id,
request and instruction. Continue executing that content using client tools.
When the flow names a persona (flow.persona), persona_activation is a protocol 2
response for it: pass current_persona and apply it as a switch before executing.
This tool only reads instructions: it does not run commands, edit files,
create a background task, sample a model or claim the workflow is complete.
Returns status=error for an invalid source or unavailable caller workspace; over
stdio a workspace error adds pid, workspace_inputs and, when the Claude desktop
app started this server, hint.

Input Schema

TableJSON Schema

Name	Required	Description
`flow`	Yes	Flow id, ID.md, flows/ID.md, or builtin:/user:/repo:<id>.
`request`	No	The user's scope, PR/MR URL and constraints.
`repo_path`	No	Optional directory within the caller workspace; defaults to the workspace.
`workspace`	No	Absolute path of your working directory, the project this session works in. Pass it whenever you have one: one server can serve several sessions.
`current_persona`	No	The `persona` object of the last SUCCESS/NO_CHANGE, copied verbatim; omit or null on first activation. All 7 keys: agent, activation_id, bundle_revision (64 hex characters), scope, skills_loaded, implants_loaded, rules_loaded.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv26.10.14+1807Oct 15, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes far beyond the annotations by disclosing the workspace resolution chain (X-Agents-Workspace over HTTP; AGENTS_CLIENT_REPO_ROOT / MCP roots / CLAUDE_PROJECT_DIR / cwd over stdio), the specific refusal codes (workspace_unsafe, workspace_required, status=error) and the extra diagnostic fields they carry. It also explicitly enumerates what the tool does NOT do (run commands, edit files, create background tasks, sample a model) and explains the persona_activation protocol, which is exactly the kind of side-effect/state disclosure that annotations alone cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action before the dense operational detail, and almost every sentence carries needed information about resolution, errors, or persona handling. It is heavy as a single wall of text and could be broken up, but given the complexity of the resolution logic that length is largely earned.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter tool with a nested persona object and an output schema, the description covers the full operational picture: workspace resolution, failure modes, the needs_execution contract, and robustness errors. Even though the output schema exists, the added explanation of the response and persona protocol leaves nothing an agent needs missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning on top: the multi-level resolution order for a bare flow ID (repo:, then user:, then builtin:), the contents expected in request, and the constraint that a repo_path override must be an existing directory inside the caller workspace. It stops short of documenting the nested current_persona keys, which the schema covers itself.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with an explicit scope ('Start a user-requested flow in the CALLER's repository'), which an agent can readily distinguish from read/list siblings like get_flow and list_flows. The follow-on sentence clarifies what the tool actually produces (needs_execution instructions), so the action and its boundary are unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear invocation context (a user-requested flow, scoped to the caller's repo) and the resolution order for a bare flow ID plus how to proceed after the response ('Continue executing that content using client tools'). It does not, however, name alternatives or state when NOT to use this tool versus get_flow or list_flows, so the routing is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server