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

Annotations already declare destructiveHint=true, so the destructive nature is covered structurally. The description adds a useful nuance—that calling it on an idle session is safe—which goes beyond the annotation. However, it does not disclose whether aborting is irreversible, whether a running computation is killed, or what happens to partial results.

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

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

Two short sentences, no filler, and the core action is stated first. The safety note is useful and earns its place.

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

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

For a one-parameter destructive action with no output schema, the description is nearly complete: it states purpose and a safe-call condition. It could be slightly richer by explaining the post-abort state of the session, but an agent can invoke this tool correctly with what is provided.

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

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

Schema description coverage is 100%, and the single parameter session_id is already fully documented as the session id returned by create_session. The tool description adds no further parameter guidance, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('Stop') with a clear resource ('a long-running or unwanted delegated task'), and the title names the action and object. It is immediately distinguishable from siblings like create_session and get_session.

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

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

The description gives clear signals about when to use it: for long-running or unwanted delegated tasks. It also provides a useful safety condition ('Safe to call when the session is already idle'). It does not explicitly name alternatives or describe when not to use it, but the context is sufficient for most selection decisions.

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

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

Annotations only carry openWorldHint=true, so the description must carry behavioral load. It does disclose the central trait — the session is persistent and preserves context across calls — which is genuinely useful. But it says nothing about what the create returns, whether sessions expire, or the effect of the allow_bash/allow_edits permission grants beyond the schema's own wording.

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

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

Two sentences, zero filler, with the core purpose and the deferred-execution caveat front-loaded. Nothing could be cut without losing meaning.

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

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

For a create-only tool with no output schema and rich 100%-covered params, the description plus schema give an agent enough to invoke it correctly, including the follow-up pattern with send_message. It could be more complete by noting what happens to the session on subsequent calls or how sessions are terminated (abort_session), but nothing critical is missing.

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

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

Schema description coverage is 100%, so every parameter (cwd, agent, model, title, allow_bash, allow_edits) is already documented in the schema. The description adds no syntax, format, or default information beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource (create a persistent delegation session) and immediately scopes it with 'without running a task yet', which is the key distinction from the delegate_task sibling. An agent can tell from the description alone what this tool does and does not do.

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

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

Explicitly prescribes the follow-up workflow: 'Follow up with send_message to keep the agent's context between calls.' This routes the agent to the right sibling and explains the reason (context retention). It does not state the inverse case (use delegate_task when you want to run a task immediately), so it stops short of full when/when-not coverage.

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

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

With only openWorldHint in annotations, the description carries the burden well: it discloses that the agent explores the repo itself, that grants are per-call, that the bridge security policy still applies (sensitive-file protection for edits, no git history changes for shell), and it names the exact return shape. This is rich behavioral context beyond the structured fields.

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

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

Three dense sentences, front-loaded with the core purpose before permissions and return shape. Efficient, though the return-shape enumeration at the end adds a little bulk that an output schema would otherwise carry.

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

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

For a tool with 8 parameters, no output schema, and only an openWorldHint annotation, the description covers purpose, permission model, and return fields adequately. Minor gaps remain around timeout behavior and how findings are scoped, but nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents all 8 parameters, setting a baseline of 3. The description adds real value beyond it by explaining the security semantics of allow_edits/allow_bash (grants are constrained, omission falls back to agent defaults), which the schema alone does not convey.

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

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

States a specific verb (delegate) and resource (a software-engineering task to an OpenCode agent), plus the runtime model and workspace scope. It is clearly distinguishable from session-oriented siblings like create_session/send_message, which manage a conversation rather than running a full delegated task.

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

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

It implies usage by naming the task type (software-engineering) and pointing to list_agents for agent selection, and explains allow_edits/allow_bash per-call granting. However, it never says when to prefer this over send_message/create_session, or what conditions make this the wrong choice, leaving alternative routing to inference.

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

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

Annotations already provide readOnlyHint=true, and the description adds meaningful behavioral context by explaining the fallback from OpenCode's session diff to a git diff against the baseline. This goes beyond the annotation's safety signal, though it doesn't mention what happens when no diff exists.

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

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

A single, front-loaded sentence that states the primary action first and then details the fallback. No filler or redundant information.

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

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

For a one-parameter, read-only tool with no output schema, the description adequately explains what is returned and how the diff is sourced. Minor omissions, such as behavior when no diff is available, are acceptable given the tool's simplicity.

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

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

Schema description coverage is 100%, and the schema already explains session_id as 'Session id returned by delegate_task/create_session.' The description does not add any further parameter semantics, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('Return'), names the resource ('file changes associated with a delegated session'), and specifies the diff-source fallback logic. This clearly distinguishes it from siblings like get_session, which deals with session metadata rather than file changes.

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

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

The description clearly implies when to use the tool: to inspect file changes for a delegated session. The sibling list makes alternative purposes evident, but the description does not explicitly state exclusions or alternative tool names, so it falls short of a 5.

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

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

The readOnlyHint annotation already covers the safety profile, and the description adds useful behavioral nuance: the stored session state is always returned, while live OpenCode status is only included when a server is running. This conditional behavior is valuable context beyond the annotation.

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

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

Two short sentences with no filler. The main purpose is front-loaded, and the sibling reference to get_diff earns its place by clarifying tool boundaries.

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

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

For a simple read-only tool with one well-documented parameter, the description provides sufficient invocation context. It could name the fields contained in 'stored state' or describe the no-server behavior more explicitly, but those are minor gaps given the schema and readOnlyHint.

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

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

Schema coverage is 100% and the session_id parameter is already well-described as the ID returned by delegate_task/create_session. The description itself adds no further parameter meaning, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Return') and names the exact resource: the stored state of a delegated session plus live OpenCode status. It also distinguishes itself from get_diff by telling the agent to use get_diff for file changes, which prevents confusion among siblings.

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

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

It gives clear context for what get_session returns and points to get_diff as the alternative when inspecting file changes. It does not explicitly enumerate when not to use get_session, but the comparison to get_diff provides enough routing guidance.

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

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

The readOnlyHint annotation already covers the key safety behavior Photon, so the description does not need to restate that. It adds useful context by mentioning project-local agent discovery from .claude-opencode/agents and the role of cwd. It does not describe output format or failure behavior, but no contradiction exists and the annotation lowers the burden.

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

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

The description is a single sentence that leads with the core action and resource, then adds the most important scoping detail about project-local agents. Every part earns its place; there is no filler or redundancy.

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

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

This is a simple, read-only listing tool with no required parameters and no complex schema. The description plus the cwd parameter documentation is sufficient for an agent to know what the tool does and when to call it. The absence of an output schema is acceptable given the straightforward 'list' semantics.

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

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

The only parameter, cwd, is already fully described in the schema with 'Workspace used to discover project-local agents (optional).' The description adds a small amount of context by linking cwd to the .claude-opencode/agents discovery mechanism, but schema coverage is 100%, so the baseline applies.

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

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

The description names a specific verb ('List') and resource ('agents that delegate_task and create_session can use'), making the tool's purpose immediately clear. It also distinguishes this listing tool from the action-oriented siblings like delegate_task and create_session. The inclusion of project-local agents adds useful scope.

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

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

The description implies when this tool is useful: before delegating or creating a session, to discover available agent names. It names the consumer tools explicitly and clarifies the optional cwd behavior for project-local discovery, but it does not state formal exclusions or contrast directly with sibling listing tools.

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

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

With only openWorldHint in annotations, the description carries the behavioral burden and does add real value: it discloses that the agent retains prior context and permission level, and that allow_edits/allow_bash mutate that level persisting into later messages. It does not describe errors on invalid/expired sessions or what the call returns.

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

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

Two tight sentences, zero waste, and the core action (continue an existing session) is front-loaded before the permission-state detail.

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

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

For a 4-param stateful tool with no output schema and only an openWorldHint annotation, the description covers continuation semantics, context retention, and permission persistence adequately. Minor gaps remain around failure modes and return value, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, including the 'from this message onward' semantics of the allow_* flags. The description largely restates that, adding only the framing that the level change persists across messages – the baseline 3 for fully covered schema.

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

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

States a specific verb (continue/send) and resource (existing delegated session), and the phrasing 'Continue an existing delegated session' contrasts cleanly with the sibling delegate_task, which starts a new one. An agent can distinguish it from create_session and delegate_task without reading schemas.

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

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

'Continue an existing delegated session with another message' establishes the context of use, and the session_id schema note ties it to delegate_task/create_session. It never explicitly says when NOT to use it (e.g. for a new task use delegate_task), so it falls short of full routing guidance.

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