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

Annotations already convey destructiveness, and the description adds meaningful context: scope='agent' stops the agent, closes its pane, reports the two results separately, and the pane close is guarded exactly like scope='surface'. It does not, however, disclose what closing a workspace does to contained surfaces or agents, which is a notable gap for a destructive 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 sentences with no filler. The core purpose is front-loaded, and each subsequent sentence adds a distinct behavioral edge case or guard rule that an agent needs to invoke the tool correctly.

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?

Surface and agent scopes are well covered, including guard behavior and partial-failure reporting, and the output schema covers return shape. The workspace scope is only named without explaining whether closing cascades to contained surfaces/agents or how the live-agent guard applies, which is important for a destructive operation.

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 80%, so most parameters are already documented. The description adds real value by explaining the otherwise-undocumented scope enum, the force/guard interaction, and the split agent_stopped/surface_closed reporting.

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 sentence states a specific verb ('Close') and explicit object types ('surface, managed agent, or workspace') plus the operative guard. This is unambiguous and easily distinguished from sibling tools like list_surfaces, update_surface, and spawn_agent.

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 conditional usage for scope='agent' versus scope='surface' and explains when force:true is or isn't needed. It does not explicitly name alternatives or say 'use this instead of X', but no sibling performs closing, so the intended use 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds the mode distinction (terse vs full) but doesn't elaborate on exact behavior or response shape; output schema accounts for that.

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?

One sentence with zero wasted words; default behavior is front-loaded, alternative follows.

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 only one optional param, output schema present, and annotations covering safety, the description is adequately complete. No missing prerequisites or side effects.

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 has 0% description coverage, so the description must compensate. It explains that detail=full is for diagnostics, which gives semantic meaning to the enum value, but doesn't explain what 'terse' vs 'full' includes. Still, for a single parameter, it partially fills the 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 ('Report') and resource ('control-path health'), with explicit default and alternative modes. Distinct from siblings that handle waiting, surfaces, agents, and messaging.

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?

Provides clear context for using the default terse mode and when to request full diagnostics. Doesn't name alternative tools, but the context is specific enough that an agent can infer when a health check is needed.

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

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

The description discloses important non-obvious behavior beyond the annotations: default summary hides close tombstones and failed spawns, and full detail adds provenance, health diagnostics, the registry record, and up to 20 receipts. Annotations are all false and provide no safety profile, so this carries most of the burden; side effects and auth are not mentioned, but nothing indicates they are needed for this list operation.

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 three dense, front-loaded sentences, each earning its place: what is listed, how filtering works, and what full detail includes. There is no filler or redundant restatement of schema fields.

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 9 optional parameters and an output schema, the description covers the non-obvious semantics—live-derived state, hidden tombstones/failed spawns, detail levels, and receipt counts—while the schema covers parameter mechanics. The definition is complete enough for an agent to select and invoke this tool correctly.

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 every parameter; the description adds value by connecting mine/parent_agent_id to child filtering, blocked_on_prompt to live prompt blockers, and by explaining how state/detail interact with hidden items. This goes beyond simple schema repetition.

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?

Description opens with a specific verb and resource: 'List live-derived agents' and immediately adds distinguishing scope such as registry-persisted prompt blockage, pause state, and child/blocked filtering. This makes it clearly distinct from sibling tools like list_surfaces or spawn_agent.

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 retrieval guidance: default summary hides tombstones and failed spawns, while requesting a terminal state or detail=full includes them. It does not explicitly name alternative tools or state when not to use this tool, but the context for correct invocation is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral context by noting the condensed default and that verbose=true adds raw cmux fields, which is meaningful beyond the annotations.

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 the core purpose front-loaded and no filler. 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 read-only topology listing tool with a complete input schema, rich annotations, and an output schema, the description is nearly sufficient. It could be improved by explicitly routing the agent to this tool versus its siblings, but nothing critical is missing for invocation.

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 baseline is 3. The description reinforces the verbose behavior but does not add substantial meaning beyond what the schema already provides for the other 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 uses a specific verb ('List') with a clear resource ('workspace, pane, and surface topology'). This distinguishes it from siblings like list_agents, read_screen, and the surface mutation tools.

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 tool is for inspecting surface topology but does not explicitly state when to choose it over alternatives like read_screen or list_agents. It does give useful guidance on the verbose flag, but not on tool selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the tool returns two kinds of content (terminal text and parsed harness status), and the mode selects which one the caller gets, which matters for how an agent consumes the result.

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, zero filler. The purpose is front-loaded first, followed immediately by the only mode-selection guidance an agent needs. 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 read-only tool with full schema coverage on all 7 parameters, an output schema, and safety annotations covering the behavioral risk, the description is nearly complete. The only minor gap is that it does not describe the shape of the 'parsed harness status' fields, but the output schema presumably covers that, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents all 7 parameters. The description's mention of raw=true and parsed_only=true merely restates the schema's own detailed explanations ('full untrimmed terminal content' vs 'return only parsed fields') without adding new semantic value, matching the baseline of 3.

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 and resource ('Read a terminal screen and parsed harness status'), and the dual-output mention (raw text vs parsed status) distinguishes it from sibling reads like list_surfaces or list_agents. It is clear, though it does not explicitly name any sibling it is not.

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 line 'Use raw=true for full text or parsed_only=true for monitoring' gives explicit context for choosing between the two output modes. However, it provides no when-not-to-use guidance or comparison against sibling tools such as wait_for or list_agents, leaving tool-selection mostly to inference.

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

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

Annotations already establish non-read-only and non-destructive behavior, and the description adds durable append to the parent's inbox, active delivery of the pointer, fallback alert to the nearest reachable ancestor with fallback provenance, and refusal for collab_path workers. These behavioral details go well beyond the schema and annotations.

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 dense paragraph, but every sentence carries distinct information—purpose, parent selection, persistence, fallback, root edge case, and collab_path exclusion. It is front-loaded with the action and then details constraints in a logical order.

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 one parameter fully documented in the schema, an output schema present, and annotations covering safety, the description supplies the behavioral details needed to call the tool correctly, including fallback behavior and error cases. No critical operational information is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description reinforces that the blocker is a short pointer and adds delivery semantics ('durably appended', 'actively delivered'). This adds meaningful context beyond the schema's own 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 specific verb and resource: 'Raise a short blocker to this managed agent's registry parent.' It also clarifies scope by saying cmuxlayer chooses the parent and callers cannot address arbitrary agents, which distinguishes it from arbitrary messaging siblings like send_to.

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 explicit context: root agents receive an error, and workers with collab_path must append there to reach their parent lead because 'this tool refuses that upward route.' It clearly implies this is for parent-directed blockers, but it does not explicitly name alternatives such as send_to, so some routing inference remains.

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?

Discloses detailed behavior beyond annotations: it explains what a 'clean verified success' returns, how degraded transport or deduplication adds fields, and that verbose=true yields the full legacy receipt. It also notes that non-success automatically keeps full diagnostics. The annotations (readOnlyHint=false, destructiveHint=false) are not contradicted; the description adds rich behavioral context about receipts and edge cases without conflicting.

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?

While the description is long, it is dense with necessary information and front-loads the primary purpose and key usage rules. Each sentence contributes value: safety constraints, mode behavior, receipt structure, and edge-case exclusions. There is no fluff or tautology; the length is justified by the tool's complexity and 16 parameters.

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 16 parameters, nested objects, and multiple modes, this description is remarkably complete. It covers target types, mode-specific return fields, failure behavior, the verbose flag, and the collab_path restriction. It also mentions unknown callers and allowed push sources. Nothing critical an agent needs to call this correctly appears missing.

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

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

With schema description coverage at only 31%, the description compensates significantly. It clarifies the 'target' parameter by stating targets may be 'one agent, structured agent targeting, or a raw surface in surface/command/key mode,' and explains mode-specific receipts (text/command vs key). It also interprets the 'verbose' parameter by describing the full legacy receipt. This adds substantial meaning to otherwise undocumented 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 opens with a clear verb+resource: 'Send text or a key through the shared delivery engine.' It immediately establishes the tool's core function and distinguishes it from alternatives by explicitly stating that send_to submits messages rather than the agent sending Return itself, which clarifies its unique role among siblings like wait_for or read_screen.

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?

Provides explicit when-to-use and when-not-to-use guidance: 'Never send a Return yourself for a message; send_to submits messages. Key-Return is for pickers, menus, and permission prompts.' It also gives a concrete alternative for workers with collab_path: 'append to that collab file instead.' These are direct, actionable routing instructions that leave no inference.

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

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

Annotations declare it is a non-read-only, non-destructive mutation. The description adds real value beyond them: deterministic placement, the timeout bounding placement, 'evidence-backed receipts', lean-by-default successful output with verbose=true restoring detail, and failures always retaining full detail. This is genuine return/behavior 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?

Four dense sentences, front-loaded with the core capability and then behavioral/return traits. Every sentence contributes, though the receipt/verbose sentences are terse and pack multiple ideas.

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 29-param spawn tool with an output schema and fully documented parameters, the description supplies the behavioral layer (placement determinism, receipt lean/verbose behavior) the annotations and schema don't. It is largely sufficient, with only minor usage-routing gaps left to 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?

Schema description coverage is 100%, so the schema already documents all 29 parameters richly. The description only gestures at boot_prompt_timeout_ms and verbose, adding little beyond what the schema already states; 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 specific verbs and resources: 'Spawn a managed agent or terminal, or resume a captured agent on a fresh surface while preserving its ID.' This clearly distinguishes it from siblings like list_agents, send_to, and close_surface, which are about inspecting/messaging/terminating rather than creating.

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?

Implies two modes (new spawn vs resume) but gives no explicit when-to-use/when-not guidance or naming of alternatives beyond the resume clause. The heavier routing guidance (resume_agent_id as 'THE way to revive', mutual exclusions) lives in the schema, not the description.

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

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

The description only names the operations without disclosing side effects, reversibility, focus behavior, or interaction with other surfaces. Annotations are all false and provide no positive info, so the description carries the burden but fails to add behavioral detail.

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, direct sentence with no fluff, front-loaded and easy to parse. However, brevity comes at the cost of essential information, which is captured in other dimensions.

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 10 parameters, 0% schema description coverage, and only a vague operation summary, the description is drastically under-sized. The output schema does not compensate for missing input semantics, leaving the agent with insufficient context to invoke the tool correctly.

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 0% and the description does not mention any of the 10 parameters. The agent receives no explanation of 'surface', 'action', 'before', 'after', 'index', 'preserve_prefix', etc., making correct parameter construction impossible.

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: move or rename one terminal surface. Clearly distinguishes from siblings like close_surface (close) and list_surfaces (list), 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?

Provides no guidance on when to use move versus rename, or when this tool should be preferred over close_surface, send_to, or possibly wait_for. No exclusions or alternative routing is 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?

Annotations declare non-read-only, non-idempotent, non-destructive, closed-world, which is an unusual profile for a wait tool and the description doesn't reconcile it. The description does add real behavioral value by disclosing that the call blocks and defaults to waiting for `done`, plus that it returns health. However, the timeout default, the refusal conditions for `report_path`, and the exclusive watch alternatives are only in the schema, so the description adds modest context beyond structured fields.

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

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

Two sentences, zero filler, with the core blocking semantics and the default condition front-loaded. Nothing is repeated and nothing needs trimming.

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?

An output schema exists and the description correctly says it returns health, so return values need no further explanation. The description covers the primary single-agent and multi-agent wait paths that constitute the tool's main use, and it does so without re-documenting parameters that the schema already fully specifies.

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 baseline is 3. The description restates the `agent_id`/`ids` targeting and the `done` default for the target state, which is redundant with the schema. It adds no meaning for the other eight parameters, including the nested `watch` object and the `condition`/`target_state` alias relationship.

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: it blocks until an agent (single `agent_id` or a set in `ids`) reaches a target registry state, then returns health. That clearly separates it from read-only siblings like `list_agents` or `read_screen`, which observe without blocking. It stops short of 5 because the tool's other major wait modes (watch specs, `delivery_id`, file-backed done) are invisible at this level.

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?

There is no explicit when-to-use guidance or named alternative; the agent must infer that this is the blocking counterpart to polling `read_screen`/`control_health`. The only steer is the default-state note (`done`), which is a parameter default rather than usage routing. No prerequisites, no mention of when not to block.

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