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

No annotations are provided, so the description carries the full behavioral burden. It discloses key traits: the session is not killed, the conversation is preserved, and the escalation sequence (Escape, then Ctrl-C). It omits what happens to in-flight output and failure behavior for an unknown session, but the core safety profile 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?

Three tight sentences, front-loaded with the action and mechanism, followed by the preservation guarantee and the routing alternative. 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 action tool with no output schema, the description supplies the mechanism, safety guarantee, and sibling routing. Missing only edge-case behavior (invalid session, already-idle agent), which is minor at this complexity.

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 50%: the 'hard' boolean is documented in the schema and the description adds sequencing context ('then Ctrl-C if asked'). The required 'session' parameter has no description in either place, so the agent must infer its format (session name/id). Adequate but with a clear gap.

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 (stop/interrupt) and resource (a tmux-hosted agent mid-generation) with the exact mechanism (Escape, then Ctrl-C). It explicitly distinguishes itself from the sibling agent_stop by declaring the non-destructive nature of the operation.

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 names the alternative ('Use agent_stop to end the session instead') and the condition that selects it. Implicitly covers when-not (when you want to end the session, use agent_stop), leaving nothing 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, the description carries the full disclosure burden. It usefully reveals that the tool surfaces shadowing installs and version resolution, which is real behavioral context, but it never states that the operation is read-only/side-effect free or what permissions or environment it requires. Adequate but incomplete for an unannotated 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?

Two sentences, both load-bearing: the first enumerates the payload, the second states the when-to-use. The key content (what you get) is front-loaded 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?

With no output schema and no parameters, the description must convey the return shape itself, and it does so by listing the four result categories. It is nearly complete for a zero-arg inspection tool; only the exact structure/format of the returned inventory is left unspecified.

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 takes zero parameters, so per the rubric the baseline is 4. There are no arguments whose meaning could be lost, and the description correctly does not fabricate any.

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 resource (agent CLIs on this machine) and enumerates exactly what the result contains: resolved binary path, version, shadowing installs, and agy MCP servers. It reads clearly as an inspection/introspection tool. It does not, however, explicitly differentiate itself from the similarly named sibling agent_list, leaving that distinction to inference.

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?

"Use before spawning so you know which build you are driving" gives a concrete trigger condition tied to the sibling agent_spawn. There is no explicit when-not guidance and no named alternative (e.g., agent_list) for comparison, so it falls short of the 5 level.

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 and does useful work: it discloses that the check reads the live pane instead of a counter and explains why (banners are UI-rendered and never exposed via API). It omits failure modes (e.g., what happens if no pane/session exists) and cost/latency implications of a pane read.

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 outcome, and the second sentence earns its place by justifying the unusual implementation. 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?

With no output schema and no annotations, the description adequately conveys what is returned (limited status plus reset time). Minor gap: no mention of what is returned for sessions with no limit or what happens on read failure.

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 single optional parameter is already documented in the schema, so the baseline is 3. The description adds only indirect context ('a session', 'if so'), not format or scope detail 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?

States a specific verb+resource: reports whether a session is rate- or usage-limited and, if so, the reset time. That is concrete and clearly distinct from siblings like agent_read or agent_status, though it never names an alternative tool to sharpen the boundary.

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?

Usage is implied rather than stated: the agent can infer you call this when you suspect a limit banner, and the schema carries the 'omit to check every tmux session' scope. There is no explicit when-to-use vs agent_read/agent_transcript guidance or precondition.

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?

There are no annotations, so the description carries the full behavioral burden. It discloses the return payload (harness, state, cwd, screen preview) and implies a read-only enumeration, but says nothing about permissions, cost, truncation of the screen previews, or large-result behavior for a machine-wide scan.

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 verb and resource, and the second sentence supplies the highest-value routing advice. The first sentence is somewhat clause-heavy, but no sentence is wasted.

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?

With no output schema, the description responsibly names the returned fields, and all three optional parameters are documented in the schema. What is missing is only marginal: the effect of the json flag and any note on the size or sensitivity of screen previews.

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% with descriptions and enums on kind and harness, so the schema already does the work; baseline 3 applies. The description adds no filter semantics and in fact mentions 'harness' only as a returned field, which arguably blurs rather than clarifies the harness filter parameter.

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 with scope ('List every agent session on this machine in one view') and enumerates what is returned (harness, state, cwd, screen preview). It is clear on its own, but it never differentiates itself from the similarly named sibling agent_inventory, which an agent could easily mistake for the same job.

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?

'Call this first — every other tool takes an id or name from here' gives explicit workflow context and explains why an agent would invoke it before others. It stops short of any exclusion or comparison, so it does not say when agent_inventory or the filtered siblings would be preferred instead.

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 full burden, and it does disclose a meaningful behavioral trait: the CLI accepts any id, so these values are advisory rather than enforced. Nothing is said about staleness or sandbox-specific availability, but the key behavioral caveat is present.

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, front-loaded with the return content, followed by the caveat that changes how the output should be treated. 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?

With no output schema, the description must convey the return shape, and it does: model ids, effort levels per harness, and manual-config paths. It is self-contained for a zero-parameter info lookup, though it could note whether results are host-specific.

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?

There are zero parameters, so the baseline is 4. The description adds no parameter detail, and none is needed.

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 resource — known model ids, effort levels per harness, and config paths — which is a clear read-only informational purpose that contrasts implicitly with the mutating sibling agent_set_model. It does not name that sibling, so the differentiation is inferential rather than explicit.

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?

Usage is implied (consult this before choosing a model) but no alternative is named and no trigger condition is given. The 'Guidance, not a whitelist' caveat is a useful consumption instruction, but it is not a when-to-use versus agent_set_model or agent_limits statement.

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 full behavioral burden and does a fair job: it explains what content is returned for each session type and that wait_idle blocks, which reaches beyond the schema's terse 'wait for output to stop changing'. It omits anything about permissions, failure modes, or the interaction between wait_idle here and the separate agent_wait_idle 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?

Three tight sentences, front-loaded with the core action, followed by per-session-type content and then the wait behavior. No filler sentences.

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 read tool with no output schema and no annotations, the description covers the essential unknowns: what the returned content actually is per session type and what blocking does. It stops short of explaining return shape/pagination or how this differs from agent_transcript and agent_wait_idle.

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 lines, session, wait_idle and idle_timeout_ms. The description's explanation of wait_idle largely restates the schema's own text, adding tone but little new semantic detail, 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?

Names a specific verb and resource (read recent output of a session) and even disambiguates what 'output' means per session type: tmux screen minus TUI chrome vs a Claude background session's log. It does not explicitly contrast with the overlapping sibling agent_transcript, so sibling differentiation is implied rather than stated.

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 tells the agent when to set wait_idle: true (to block until output stops), and a separate agent_wait_idle sibling exists that is never mentioned, nor is agent_transcript for full history. Usage context is implied rather than spelled out as when-to-use / when-not-to-use.

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 behavioral burden. It explains the effect (picks up the current binary because a running process keeps its booted model list), which is genuinely useful. But it never says whether the session's conversation state is preserved or lost on restart, nor any permission/auth requirements, which matters for a process-restarting 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?

Two tight sentences, front-loaded with the action and scope, followed by the trigger rationale. Every clause earns its place and nothing is padded.

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 two-parameter, zero-required tool with no output schema, the description covers what it does, when to use it, and roughly how scope is selected. The remaining gap is state-preservation semantics, which an agent would want before restarting a live session.

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 50%: the 'session' parameter is documented in the schema but 'all' is not, and there are no required parameters. The description's parenthetical '(or all of them)' hints at the `all` parameter's role, partially compensating, but it adds no format or interaction detail (e.g., what happens if both are supplied) beyond what the schema already conveys.

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 ('Restart') and resource ('Claude background session'), and immediately clarifies scope via '(or all of them)'. The rationale clause ('so it picks up the CURRENT Claude binary') separates it cleanly from siblings like agent_resume, agent_stop, and agent_spawn, which an agent can distinguish without opening any 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?

Gives explicit trigger conditions: 'Use after `claude update`, or when a session was started by an older build.' This is strong when-to-use guidance. It does not, however, name alternative tools (e.g., when agent_resume is preferable instead) or state when-not to use it, so it stops 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?

With no annotations, the description carries the full burden. It usefully discloses that the session restarts in the background under the same id, preserving identity, but says nothing about behavior if the session is already running, state loss, auth/permission needs, 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?

Two tight sentences with zero filler, and the core action plus its background/same-id traits are front-loaded.

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 resume tool with no output schema, the description covers the essential state transition and identity preservation. Minor gaps around failure modes and coexistence with a running session keep it just short of complete.

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 both parameters are already documented. The description adds only that the message is optional and delivered 'on resume', which is marginal beyond the schema's own descriptions. 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?

The description states a specific verb ('bring a stopped ... back') and resource ('Claude background session') with a clear-state precondition. It does not, however, distinguish itself from adjacent siblings like agent_respawn, whose name suggests a very similar restart operation.

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 when to use it ('stopped ... session') and notes the optional message path, but names no alternatives and gives no exclusions. An agent cannot tell from the text alone when to choose agent_resume over agent_respawn or agent_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?

No annotations exist, so the description carries the full burden, and it does disclose the single most important trait: this call blocks until the agent answers unless wait:false. It also reveals harness-dependent mechanics (resumed background turn vs. tmux keystrokes). It stops short of timeout/error behavior and side effects such as transcript writes.

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 filler. The blocking behavior is front-loaded in the first clause, and the harness abstraction is a single compact second sentence that 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 4-parameter tool with no output schema, the description covers the blocking semantics and per-harness mechanism well. The remaining gap is the return payload — it implies the reply comes back but never says what is actually returned or what a timeout yields.

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 75% (only the bare 'message' string lacks a description). The description reinforces the wait semantics beyond the schema's own note, but adds nothing about timeout_ms units/behavior or how 'session' resolves a name vs. id. Baseline 3 is appropriate since the schema does the heavy lifting.

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 ('Send a message to an existing session') and immediately adds the two behavioral facts that matter. 'Existing session' implicitly separates it from agent_spawn/agent_respawn, and the harness note explains what the single tool abstracts over.

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 the default call shape ('unless wait:false, wait for it to finish answering'), which is real usage guidance for the wait parameter. But it never says when to prefer this over agent_read, agent_interrupt, agent_wait_idle, or bridge_send, nor when not to use it.

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 full burden and does disclose a non-obvious behavioral trait: for a live tmux session it types /model and confirms the switch, while a background session applies on the next turn. That timing/mechanism detail is genuinely useful. It omits permissions, failure/confirmation behavior, and effect on in-flight work, so not a 5.

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 tight sentences, front-loaded with the core action, then the two context-specific behaviors. Every sentence adds information and none is 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 mutation tool with no annotations and no output schema, the description covers the change semantics and timing but leaves gaps: it does not say what a success/failure looks like, whether the switch affects an active turn, or where valid model ids come from. Adequate but incomplete given the lack of structured context.

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 only 33% — 'model' is described simply as 'Model id', while 'session' and the 'effort' enum (low/medium/high/max) have no descriptions at all. The description text adds no meaning about any parameter, so it fails to compensate for the coverage gap.

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 ('Change the model a session runs on'), which is clearly distinct from listing tools like agent_models or spawning tools like agent_spawn. It does not explicitly name a sibling to steer the agent away from, so it stops short of a 5.

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 the mechanism in two contexts (running tmux vs background session), which implies usage, but never states when to reach for this tool versus alternatives like re-spawning a session or picking a model at spawn time. 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 and does disclose non-obvious behavioral facts not present in the schema: claude sessions are true background sessions with an id and log, agy sessions are tmux-hosted because agy lacks a background mode, and mode=tmux forces interactivity. It omits what the call returns (session id/handle) and whether spawning is blocking or resource-intensive.

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 compact sentences, front-loaded with the core action, then the harness tradeoff, then the mode override. Every clause carries decision-relevant 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 an 11-parameter process-spawning tool with no annotations and no output schema, the description covers the harness/mode axis well but says nothing about the session lifecycle (how to check readiness, read output, or stop the spawned agent) or about what the call yields. Adequate but with clear gaps.

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 91%, so the baseline is 3; the description goes beyond the schema by explaining the semantics and interaction of harness and mode (including the auto mapping) rather than just restating enum values. Other parameters (agent, mcp_config, permission_mode) are left entirely to 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 uses a specific verb+resource ('Start a new agent session') and immediately disambiguates its two harness variants, so an agent knows exactly what is being created. It does not, however, distinguish itself from close siblings such as agent_spawn_many or agent_resume, which also create/continue 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?

It gives real selection guidance: harness=claude is stated as preferred (real id, real log), harness=agy is explained as necessary because agy has no background mode, and mode=tmux is named as the forced-interactive override. It stops short of routing against siblings (e.g. when to prefer agent_spawn_many for batches).

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 full burden. It does disclose valuable behavior beyond the schema: partial fan-out returns both created ids and failures instead of failing silently. However it omits concurrency/rate limits, whether a failure aborts the remaining starts, and whether calls block until sessions are live.

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 compact sentences, front-loaded with what the tool does, followed by the return contract. Every clause earns its place; nothing is restated from the schema.

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?

No output schema exists, and the description usefully covers the return shape (ids plus failures), which is the most important gap. But for a 9-parameter mutation tool with no annotations, the failure semantics, limits, and six undocumented parameters leave it short of complete.

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 44%, below the 50% threshold, so the description should compensate more than it does. It clarifies the tricky prompts-vs-count/prompt relationship, but cwd, model, effort, harness, stagger_ms, and name_prefix remain undocumented in both schema and 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?

States a specific verb and resource ("Start several sessions at once") and immediately scopes the two operating modes, one-per-prompt vs N clones. Read against sibling agent_spawn, the plural/batch nature is unmistakable without opening 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?

The description implies the usage context (fan-out when you need many sessions at once) but never states when to prefer this over repeatedly calling agent_spawn, nor any preconditions. Usage is inferable from the mode description rather than stated as 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, the description carries the full burden and does well: it discloses that Claude background sessions retain their conversation and are resumable, that a tmux session is actually destroyed, that the on-disk transcript survives, and that the tool reports which outcome occurred. Missing are permission/auth requirements and any error behavior when the named session does not exist.

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 tight sentences, front-loaded with the action, then the type-dependent consequence, then the reporting behavior. No filler; every sentence adds information an agent needs.

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 3-parameter mutation tool with no annotations and no output schema, the description covers reversibility, destruction, and outcome reporting well. The remaining hole is the 'session' identifier format and how 'all'/'remove' interact with the stop, which the description never ties together.

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 67% and the required 'session' parameter has no schema description at all; the description implies that session values are 'Claude background' vs 'tmux' types but never states the accepted identifier format. The type-dependent semantics are useful context, but the most critical parameter remains ambiguous, keeping this at the baseline.

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?

Names a specific verb and resource ('Stop a session') and immediately splits the behavior by session type (Claude background vs tmux), which is the key distinction an agent needs. It does not explicitly name the sibling it is NOT (e.g. agent_interrupt vs agent_stop, or agent_resume as the inverse), so it falls short of full sibling differentiation.

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?

Usage is implied rather than stated: an agent can infer that resumable Claude sessions and destructive tmux stops behave differently, but there is no explicit 'use this instead of agent_interrupt' or when-not-to-stop guidance. The mention that Claude sessions 'can be resumed' hints at the alternative without naming it.

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 full burden, and it does disclose a non-obvious behavior: it "resolves the config-dir indirection rather than guessing a path." That is genuinely useful context. But it says nothing about the return shape (a path string vs. a file list), whether the path is guaranteed to exist, or what happens on an unknown session.

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 that front-load the core purpose (disk location) before the mechanics (config-dir resolution). No padding, though the second sentence's value depends on the ambiguous return semantics.

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?

No annotations, no output schema, and only 50% parameter coverage. For a tool whose entire value is telling the caller where to look, the description omits the return format and the meaning of `limit`, leaving an agent unable to use the result confidently.

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 only 50% — `session` has no description and `limit` is documented only as "Max files to list." The description alludes to "a session's conversation," loosely covering `session`, but says nothing about `limit` and even conflicts semantically with a single stored path. It does not compensate for the coverage gap.

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 says the tool resolves where a session's conversation is stored on disk, but the schema's `limit: Max files to list` suggests it lists files, creating ambiguity about whether it returns one path or many. It does not distinguish itself from siblings like agent_read or agent_list, which likely consume this path. The purpose is only partially pinned down.

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?

"So a caller can read the raw history itself" implies the intended workflow (resolve path, then read it yourself), which hints at why you'd pick this over a reading tool. However, no sibling is named and no explicit when/when-not condition is stated, leaving the agent to infer the boundary against agent_read.

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 full burden. It usefully discloses blocking behavior, the motion-based detection approach, and the return condition ('screen stable for a few seconds'). However it does not state what happens on timeout (return vs error), whether any state is mutated, or what the return payload conveys.

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, front-loaded with the core action and immediately justified by the mechanism. 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 parameterless-of-annotations, no-output-schema blocking tool, the definition covers intent and mechanism but omits timeout semantics and return content, which an agent needs to handle the blocking call safely. Adequate but with clear gaps.

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 67%: stable_ms and timeout_ms are documented with defaults, but 'session' has no schema description and none is supplied here. The description's mention of the screen being 'stable for a few seconds' loosely ties to stable_ms but adds no format or constraint detail 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?

States a specific verb+resource ('Block until a tmux-hosted agent stops producing output') and clarifies the detection mechanism ('Movement-based, not marker-based'). It implicitly differentiates from agent_read/agent_transcript by describing wait semantics, though it doesn't name a sibling explicitly.

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?

'Block until... stops producing output' implies the use case, and 'works for any harness' hints at generality, but there is no explicit when-to-use versus agent_read, agent_transcript, or polling alternatives. The agent must infer that this is the waiting primitive rather than a read.

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 behavioral burden, yet it only says messages are 'waiting' and the inbox defaults to the caller. It doesn't state whether reading consumes/deletes messages, the ordering, or that mark_read is what mutates read state — a notable gap for a tool with a write-mode parameter.

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 the core behavior front-loaded and the default scope immediately after. Efficient, though very terse given the tool's parameter set.

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?

With no annotations and no output schema, the description should explain the return shape, ordering, and read-state side effects. It covers only the inbox default, leaving the agent to guess how the messages come back and what mark_read does.

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 75% (limit is undocumented). The description adds real value by explaining the default value of the 'for' parameter (calling agent's own inbox), partially compensating for the uncovered parameter.

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 (read) and resource (messages waiting on the bridge) and clarifies the default scope (calling agent's own inbox). It is distinguishable from bridge_send, though it doesn't explicitly name the sibling it complements.

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?

Usage is implied (poll for pending messages) and the default inbox removes the need to specify 'for'. However, there is no explicit when-to-use versus bridge_status or agent_read, and no guidance on polling cadence or when not to use it.

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 must carry the whole behavioral burden. It usefully discloses the file-backed transport and that 'a watcher wakes the other side' (an asynchronous side effect), but says nothing about delivery guarantees, what happens if the recipient is not running, or how priority/reply_to affect delivery. Partial disclosure, so a middling score.

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 action and channel, with the explanatory parenthetical earning its place by clarifying reachability. 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?

There is no output schema and no annotations, so the description is the only source of behavioral context. It covers the transport and the wake-up mechanism but omits error/offline behavior, priority semantics, and what a caller can expect after sending — meaningful gaps for a handoff tool whose success is not self-evident.

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 50%, and the description adds no parameter meaning whatsoever — it never mentions content, subject, priority levels, or reply threading. The `to` enum, `from` default, and `reply_to` are documented in the schema, but `content`, `subject`, and `priority` semantics are left entirely to the caller, which is exactly the gap the description should fill.

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 and resource ('Send a message to another agent') and names the concrete channel ('the file-backed bridge'), then explains why the channel matters: Claude Code and agy cannot call each other directly. That rationale separates it from the agent_* siblings an agent might otherwise pick.

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 usage context — 'this is how you hand off or ask for help' — which tells the agent this is the cross-agent handoff path. It stops short of explicitly naming an alternative (e.g. agent_send) or stating when NOT to use the bridge, so the agent still has to infer the boundary between this and agent_send.

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 full behavioral burden, and it does disclose the observational content it returns. However, it never states that it is read-only, whether auth/permissions are needed, or that history_with can dump substantial history data — notable behavioral gaps for a tool with zero annotation coverage.

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, return contents front-loaded before the usage hint, with zero filler. Nothing is wasted.

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 no-output-schema read tool with no annotations, the description usefully explains what comes back and one use case. But it leaves limit unexplained and omits any behavioral/error context, so an agent can call it only approximately.

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 only 50% (history_with is documented in the schema, limit is a bare number with no description). The description adds no meaning for either parameter and never addresses what limit controls, so it fails to compensate for the undocumented half.

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 the concrete outputs (bridge file location, size, active agent pairs), so an agent knows this is a status/diagnostic read against the bridge. It is clear on its own but never differentiates itself from bridge_send or bridge_inbox by name, which a 5 would require.

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 an explicit triggering condition: 'check a channel exists before relying on it.' That tells the agent when to reach for it, but offers no exclusions or named alternatives for the adjacent bridge send/inbox 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 no annotations, the description carries the full behavioral burden and does well: it discloses operation ordering (new terminal opens first, old process retired seconds later), the refusal guard when the replacement command is not on PATH, and the irrecoverability of killing with no replacement. It does not say what happens to in-flight agent sessions or whether the call returns before the restart completes.

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, front-loaded with the action, then the trigger, then the safety caveat. No filler; every sentence carries distinct 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?

No output schema and no annotations, so the description must stand alone, and it covers sequencing, timing, the PATH refusal path, and irrecoverability — enough to call the tool safely. Remaining gaps (effect on other sessions, return behavior) are modest for a self-restart primitive.

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 all four parameters including dry_run are already documented in the schema. The description only obliquely references the replacement command and the delay ('a few seconds later'), adding no format or default detail beyond the schema, 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 — 'Restart the agent host that is running this tool' — and self-scopes to the current host, which cleanly separates it from the sibling lifecycle tools (agent_respawn, agent_spawn, agent_stop) that act on other agents.

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?

Explicit trigger condition: 'Use after changing config, plugins or MCP servers that only take effect on restart.' The self-scoping phrase 'the host that is running this tool' implicitly excludes alternatives, but no sibling (e.g. agent_respawn) is named as a counter-option, so it falls short of a full when/when-not/alternatives statement.

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