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

With no annotations provided, the description carries the full burden. It transparently discloses that it cancels the in-flight turn, drops queued messages, and preserves session resumability. This goes beyond a simple action and gives clear behavioral context, though it omits potential side effects like partial results or error conditions.

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 front-loads the core action and then adds the key behavioral nuance about session persistence. Every word contributes value, and it is appropriately sized for a one-parameter tool.

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 tool with one parameter and no output schema or annotations, the description covers the essential behavior: what it cancels, what it drops, and the post-condition of resumability. It is sufficient for an agent to use correctly, though it could mention edge cases like interrupting an idle subagent.

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 input schema already documents the parameter fully (subagent handle returned by spawn) with 100% coverage. The description adds no additional semantic information about the parameter, 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 clearly states the tool cancels an in-flight turn and drops queued messages, with the session remaining alive and resumable. It is specific about the action and resource, though it does not explicitly name sibling alternatives, it implies a distinction from stop (which likely terminates).

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 to use this tool by noting the session stays alive and resumable, suggesting it is for temporary pauses. However, it does not explicitly compare with siblings like stop or resume, nor state when not to use it. Guidance 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.

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

With no annotations, the description carries the burden of behavioral disclosure. It adds useful context by specifying the session categories and that status is included, but it does not mention return shape, ordering, pagination, or whether it is read-only. 'List' implies a non-mutating operation, but little else is disclosed.

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 wastes no words. The key action and object appear immediately, and every phrase adds meaningful scope ('live, persisted, agent-side', 'with status').

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 zero-parameter list tool, the description is adequately complete: it identifies what is listed and the included status field. There is no output schema to reference, but the basic calling context is simple enough that the description does not leave a critical ambiguity.

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 tool has zero parameters and the schema coverage is 100%, so there is nothing for the description to add about parameter meanings. The description's mention of session categories and status is enough given the absence of parameters.

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 clearly states the verb ('List'), the resource ('live, persisted, and agent-side sessions'), and that status is included. It distinguishes itself from the action-oriented sibling tools (spawn, send, interrupt, etc.), though it doesn't explicitly name a sibling to differentiate from.

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 usage is implied: if you need to see existing sessions and their status, call this tool. However, there is no explicit guidance about when to use it versus other session-related operations, nor are alternatives or exclusions mentioned.

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 no annotations provided, the description carries the full behavioral burden. It discloses that the tool reports current/advertised values rather than modifying them, explains both parameter branches, and notes the null state until the first session exists. It stops short of explicitly stating side-effect-freedom, but 'report' and the conditional output semantics make the read-only nature reasonably clear.

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 compact: two sentences plus a short example line. Every sentence earns its place, and the conditional behavior is front-loaded with the 'name' parameter case first. No filler or redundant restatement of the tool name.

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?

Given one optional parameter and no output schema, the description covers both invocation branches, the null edge case, and example model ids. It does not detail the exact structure of the returned lists, but for a reporting tool with simple inputs, the essential usage information is present.

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 baseline is 3. The description adds value by explaining what happens with and without 'name', tying the parameter to the session's model/mode versus bridge-level defaults. This goes beyond the schema's simple 'Subagent handle returned by spawn' description.

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 states a precise verb-resource pairing: reporting the current model/mode and advertised lists. It clearly distinguishes two invocation modes (with and without 'name'), and the examples of Devin model ids add concrete specificity. This separates it from siblings like set_model and set_mode, which are change operations rather than reporting operations.

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 context for when to include the optional 'name' parameter versus omitting it, including the null-before-first-session behavior. It does not explicitly name sibling alternatives or state when not to use this tool, but the conditional usage guidance is concrete and actionable.

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?

No annotations are provided, so the description carries the full burden. It discloses the core behavior (pass optionId to approve, omit to deny) but does not explain side effects, error conditions, or what happens if the request is already resolved. For a simple permission response this is adequate, but not exhaustive.

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 is concise and front-loaded. It states the purpose and the key action immediately, with no filler.

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?

The tool is simple with only two parameters and no output schema. The description covers the essential usage: how to approve/deny and the context of when it applies. It does not specify the response format, but that is not critical for a permission action.

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 description adds important semantics: it explains that omitting optionId means deny, which is not in the schema. This clarifies the optional parameter's role beyond the schema description.

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 clearly states the action (grant or deny) and the resource (a pending tool-permission request), and it explicitly distinguishes this from sibling tools by tying it to the poll flow and the operator permission mode. It is specific and unambiguous.

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 explains that this tool is used when permission=operator and the calling agent decides, and mentions it is surfaced by poll. This gives clear context, though it does not explicitly say when NOT to use it (e.g., if permission is not operator). Still, the intended usage is clear.

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 no annotations provided, the description carries the full behavioral burden, and it delivers extensively: snapshot independence from reads and buffer eviction, merged tool calls by id with elapsed ms, lifecycle fields, last-activity/last-content ages, an implicit read cursor with nextCursor/hasMore continuation, droppedEvents counting buffer-evicted events, and mode-dependent since semantics. These are non-obvious behaviors an agent could not infer from the schema alone.

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 dense rather than concise, but every clause earns its place given the dual-mode, cursor-based, blocking complexity. It is front-loaded with the mode dichotomy and uses quoted parameter names as anchors. It loses a point only because the run-on, semicolon-heavy prose is harder to parse than shorter, sentence-per-concept structure would be.

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 5-parameter, dual-mode tool with no output schema and no annotations, the description is remarkably complete: return contents for both modes are enumerated, paging and cursor semantics are specified, and blocking behavior is bounded. Residual gaps are minor — end-of-life behavior of the inspect snapshot (does it persist after the subagent finishes?) and what an agent should do with a 'pending permission' field (pairing with the permission sibling) are not addressed.

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 baseline is 3; the description then adds substantial meaning beyond the schema: the detailed contents of the inspect snapshot (lifecycle fields, pending permission, turn timing/duration, last output, active tool calls, plan step, latest text/error, ages), the 'implicit read cursor' model, droppedEvents semantics, and the distinction between inspect's snapshot cursor and logs' replay cursor. This meaningfully exceeds what the property descriptions provide.

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-resource pair ('poll' a subagent, with two observation modes: 'inspect' snapshot and 'logs' event log), and the title reinforces the purpose. Against the sibling set (spawn, send, wait, interrupt, stop, resume, list, permission, models), it is unmistakably the observation/read tool, and the two modes are explicitly delineated from the opening sentence.

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 strong contextual guidance: it states the default mode, explains that inspect is independent of log reads and buffer eviction, clarifies that limit only applies to logs, and specifies the blocking semantics of wait_ms ('blocks briefly while a turn can still produce events'). However, it never explicitly contrasts with siblings — e.g., it doesn't say 'use wait for full turn completion instead of long wait_ms blocks' — so exclusion guidance versus the wait/list tools is left 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?

With no annotations provided, the description carries the behavioral burden. It discloses persistence across bridge restarts and idempotent no-op behavior, which are important and non-obvious. It does not mention error behavior for unknown names, but the core invocation behavior is well covered.

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 focused sentence with no filler. The core purpose is front-loaded, and the two caveats about persistence and no-op behavior are concise and high-value.

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 tool with a complete schema, the description covers the essential invocation context. Minor gaps include lack of detail about return values or behavior when the named subagent does not exist, but these are not critical for basic correct use.

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 single required parameter is already fully documented. The description adds no additional parameter semantics, and none are needed beyond what the schema provides.

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 states a clear verb, 'Re-activate', and a specific resource, 'stopped/dead/persisted Devin session'. It also distinguishes itself from lifecycle siblings by noting it survives bridge restarts and is a no-op on running subagents.

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 it: for sessions that are stopped, dead, or persisted. It also provides an explicit when-not condition by stating it is a safe no-op on already-running subagents, though it does not name alternative tools like spawn.

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 no annotations provided, the description carries the burden of behavioral disclosure. It discloses queueing behavior, FIFO ordering, strict serialization, and the need to resume stopped/dead subagents, which goes well beyond the schema. It does not cover return values or failure behavior, but the core semantics are transparent.

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, front-loaded with the purpose, followed by behavioral details and a prerequisite. Every sentence earns its place and there is no filler.

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 two-parameter tool with no output schema and no annotations, the description covers the essential operational context: what it does, when messages are queued, serialization, and the resume prerequisite. It does not explicitly tell the agent to poll or wait for the result, but that is reasonable to infer from sibling tools.

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 both parameters. The description adds useful context about the name parameter (subagent handle validity and resume requirement), but does not add substantial new semantics for either parameter beyond what the schema provides.

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 clearly states the tool sends a follow-up prompt to a subagent, using a specific verb and resource. It distinguishes itself from spawning by saying 'follow-up', but it does not explicitly name sibling tools like interrupt or resume, so differentiation relies on context.

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 provides clear usage context: messages queue in FIFO order and are serialized per session, and stopped/dead subagents must be resumed first. It does not explicitly mention alternatives or when-not-to-use, but the queueing and prerequisite guidance is strong.

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 no annotations provided, the description carries the burden of disclosing behavior. It mentions validation against availableModes, which is useful. However, it does not disclose the effects of mode change, side effects, or reversibility, which are important for a mutation tool.

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 concise and front-loaded with the core purpose. It is one sentence that efficiently communicates action and validation, with no unnecessary 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?

Given the tool is a mutation with no annotations and no output schema, the description is reasonably complete for basic usage, but lacks detail on side effects and error conditions. It covers the essentials but leaves room for improvement.

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 parameters are well-documented in the schema. The description adds context by mentioning 'name' as a subagent handle and 'mode' as a mode id, but the schema already provides this. Baseline 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 clearly states the tool's purpose: switching the session's mode, with examples of modes. It is distinct from siblings like set_model, as it focuses on permission mode. However, it doesn't explicitly differentiate from the 'permission' sibling, leaving some ambiguity.

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 usage through the context of session modes and validation, but does not explicitly state when to use this tool versus alternatives. It lists example modes and validation against availableModes, but lacks clear when-to-use 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?

With no annotations provided, the description carries the full disclosure burden and exceeds it: it discloses the underlying call (session/set_config_option), the verification behavior (confirms the echoed value), the failure conditions (rejected while not idle), and input validation (checked against the advertised model list). This is exemplary coverage for a tool with zero annotation support.

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 sentences, zero filler, with information front-loaded: action+mechanism+verification first, then failure conditions, then validation. Every sentence earns its place and no idea is repeated.

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 2-parameter config tool with no output schema and no annotations, the description covers purpose, preconditions, mechanism, verification, and validation — all core call decisions. The remaining gaps are minor: no explicit statement of the success/failure return shape beyond echoing the value, and no mention of whether the change persists or requires session restarts.

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 both parameters are already well-documented ('Subagent handle returned by spawn' and 'Model id from the session's advertised list'), so the baseline is 3. The description adds only marginal value — the worked example 'swe-2-high' and the validation behavior — rather than clarifying parameter meaning beyond the 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?

The description states a specific verb-resource pair ('Switch an idle session's model') plus the implementation mechanism ('via session/set_config_option') and a concrete example echo value ('swe-2-high'). This clearly distinguishes it from siblings like set_mode (mode changes), models (listing), and the lifecycle tools (interrupt/stop/resume).

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 explicit preconditions ('idle' session), explicit rejection states ('starting/running/stopped/dead'), and a concrete remedy ('resume or wait for idle first'). It stops short of naming sibling tools as alternatives — notably the models tool that would provide the advertised list — which is the only gap.

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 no annotations provided, the description carries the full burden. It discloses the key behavioral traits: non-blocking (returns immediately), background execution, and parallel support. It does not mention failure modes or permissions, but for a spawn operation this is acceptable and provides useful context beyond the schema.

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 two concise sentences that front-load the core purpose and immediately clarify the asynchronous nature and progress tracking. Every word serves a purpose, with no 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?

For a tool with five parameters and no output schema, the description provides sufficient context: what it does, that it is non-blocking, and how to monitor progress. It does not specify the return value format, but since no output schema exists and the name parameter serves as a handle, this is a minor gap.

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 schema already documents all five parameters with descriptions (coverage 100%), so the description adds no additional meaning to them. It does not elaborate on parameter interactions or constraints, so a baseline of 3 is appropriate given the schema's thoroughness.

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 clearly states the action: 'Create a new Devin session and start it on a task in the background.' It identifies the resource (a Devin subagent) and the key behavior (asynchronous, parallel-capable), distinguishing it from sibling tools like poll and wait which are for monitoring or managing existing sessions.

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 practical guidance by noting it 'returns immediately; use poll to watch progress' and that 'multiple subagents can run in parallel.' This implies when to use it (to launch a new task) and how to follow up, though it does not explicitly name exclusions or alternatives beyond poll.

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?

No annotations are provided, so the description carries the full burden. It discloses all key side effects: interrupts running turn, drops queued messages, marks stopped, and preserves the session. This is transparent about both destructive and reversible aspects, leaving nothing ambiguous.

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, no fluff. The core action is front-loaded ('Interrupt any running turn...') and the session-retention detail is appended naturally. Every word 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 single-parameter command with no output schema, the description is fully sufficient. It explains what happens, what persists, and how to resume. An agent can call it correctly with just this text and the schema.

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 input schema has 100% coverage: the only parameter 'name' is described as 'Subagent handle returned by spawn, e.g. coder-auth'. The description adds no extra parameter nuance, but none is needed; the baseline of 3 applies because the schema already handles it.

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 states a specific verb ('Interrupt'), the resource ('subagent'), and the concrete effects: drop queued messages, mark stopped, keep session. It clearly distinguishes from the sibling 'interrupt' by adding the drop-and-mark behavior, so an agent can tell them apart without reading either schema.

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 explains that the session is kept and can be resumed later, giving a clear reason to choose 'stop' over a more permanent or lighter alternative. It does not explicitly name 'interrupt' as a when-not-to-use case, but the behavioral distinction is implicit and sufficient for basic routing.

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?

No annotations are provided, so the description carries the full burden — and it delivers richly: five wake modes (done/permission/report/stopped/dead/timeout), report-once delivery even if arrived before the call, background-task vs. blocking execution depending on host MCP-task support, and timeout returning a live-state snapshot. This goes well beyond annotation-level disclosure.

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 core purpose is front-loaded in the first sentence, and the remaining three sentences pack in essential behavioral detail with no filler. It is dense — the em-dash clauses are heavy — but every clause earns its place for a blocking tool whose wake semantics are the entire contract.

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 complex tool with no output schema and no annotations, the description covers wake modes, timeout behavior, report-delivery semantics, host-dependent execution, and the permission-tool routing. The only gap is that it never specifies the exact returned payload shape for each wake mode, which an agent would need since there is no output schema to fall back on.

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 baseline is 3; both name and timeout_ms are already documented with defaults and bounds. The description adds some value beyond the schema by explaining what a timeout produces ('snapshot shows live state') and what a permission wake means, but it does not materially extend the parameter semantics.

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 opening clause 'Block until the subagent needs you, then return what happened' names a specific verb ('block'), resource (the subagent), and outcome. It differentiates from the sibling 'poll' by emphasizing blocking semantics and the immediate-return behavior for already-attention states, so an agent can tell them apart without opening the schema.

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 behavioral context: it enumerates when to use it (blocking for attention) and states that already-attention states return immediately 'so it doubles as is it done?'. It also routes permission wake-ups to the permission tool. However, it never explicitly names poll as the non-blocking alternative or states when not to use wait, leaving that contrast implicit.

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