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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description reinforces rather than contradicts them by spelling out what is NOT destroyed (no detach, no target kill, no shell restoration claim) — genuinely useful context beyond the annotation booleans. It stops short of describing failure behavior for an unknown or already-closed bridge_id, which is the one remaining disclosure gap.

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 short sentences, zero filler. Scope comes first, non-effects second, the alternative route third, with 'Idempotent.' as a one-word close.

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, so return values need not be described. For a two-param teardown tool the description covers scope, non-effects, idempotency, and the sibling alternative — everything needed to invoke it 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 coverage is 100% and both parameter descriptions are strong (owner distinguished from a generated TCP token; bridge_id explicitly 'not a Session reference'). The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource pair: closing the external RSP bridge AND its serial Session, with the capitalization making the dual scope unmistakable. It also distinguishes itself from debug_bridge_restore, so an agent can route correctly 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?

Explicitly names the alternative and the selecting condition: 'Use debug_bridge_restore after externally ending RSP if the Session should be preserved.' It also states the negative cases (does not detach, kill a target, or claim shell restoration), 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?

Goes well beyond readOnlyHint: it discloses that no heartbeat renewal, target I/O, management owner acquisition, or connection secrets are touched, and spells out the authorization model (Host access, no per-bridge owner) and the scan boundary (does not scan OS ports or other Hosts). The "until finalization" clause also explains why a read-only list can be non-idempotent, matching idempotentHint=false.

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 tight paragraph, front-loaded with the verb and scope, and every clause adds either scope or safety detail. Slightly dense (four semicolon-separated qualifiers), 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?

For a 0-parameter, read-only list tool with an output schema already documenting the return shape, the description covers everything an agent needs: what is listed, what is excluded, what is not touched, and which Host boundary applies.

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 the baseline is 4; the description correctly does not invent parameter narrative and instead spends its words on scope and behavior.

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 ("List all unfinished external GDB bridges in this Host") and enumerates what each entry carries (bound addresses, ports, Session refs, targets, states). The inclusion/exclusion clause ("includes disconnected/recovering until finalization; excludes closed/failed/restored") further pins the scope. It does not explicitly contrast with debug_bridge_status, so sibling differentiation is only implicit.

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 include/exclude rules imply when this tool is the right choice, but there is no explicit "use X instead of Y" guidance against debug_bridge_status or debug_bridge_report. An agent must infer that this is the bulk-inventory counterpart to the single-bridge status tool.

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?

Beyond the annotations, the description discloses key lifecycle behavior: current authenticated connections renew automatically, the 60-second grace and 24-hour absolute maximum cannot be resurrected, and expiry closes the serial Session without claiming target restoration. This adds substantial operational context for a non-read-only, non-idempotent renewal 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 front-loaded with the action and scope, then spends its remaining sentences on automatic renewal, lease limits, and expiry consequences. Every sentence carries relevant information and none 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 an output schema present, return values need not be explained. The description, annotations, and fully described parameters together cover safety, scope, lifecycle limits, and expiry consequences well enough for an agent 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 100%, so the schema already documents owner as a secret management capability and bridge_id as an opaque ID from debug_bridge_start. The description does not add parameter-specific meaning beyond that 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?

The description states a specific verb and resource: renewing the external RSP bridge's management heartbeat and internal lease. It clarifies that this applies while listening or disconnected and that current authenticated rsp-client connections renew automatically, but it does not explicitly position the tool against sibling renewal or bridge 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?

It gives clear usage context by implying renewal is for bridges that are listening or disconnected, and it excludes current authenticated rsp-client connections because they renew automatically. It does not name alternative tools or lay out full preconditions, so it stops short of explicit when/when-not/alternatives guidance.

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

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

The description adds substantial behavior beyond the annotations: it publishes only independent Session events visible in attach/events, reporting failure must not interrupt GDB, and renewal is independent of reporting. It also discloses sequence-gap and retry semantics plus redaction requirements, which are rich operational details for a mutation-like reporting 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 key purpose is front-loaded and the paragraph contains no filler, with each clause carrying operational guidance. It is dense and could be better structured, and some sequence/redaction guidance overlaps the schema, but overall it is appropriately sized.

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 an output schema and fully documented input schema, the description supplies the remaining critical context: scope boundaries, failure isolation, retry behavior, redaction, and non-interference with debugging. Nothing essential for correct invocation appears to be 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 already 100%, including sequence gaps, deduplication, redaction, and bridge_id meaning. The description repeats sequence/retry and redaction guidance but adds little new per-parameter meaning beyond what the schema already provides, so the 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 gives a specific verb and resource: report externally executed GDB commands/results/states as Codex reports. It explicitly distinguishes this from a complete audit, event execution, and heartbeat renewal, so an agent can tell it apart from debug_command, debug_events, and debug_bridge_renew.

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 clearly states the reporting context and excludes command execution, RSP forwarding, target verification, and heartbeat renewal. It also defines failure behavior, but does not explicitly name the sibling tools to use for those excluded tasks, so it falls short of fully explicit alternatives.

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 disclose destructive/openWorld/idempotent traits, and the description adds important behavior: it applies and reads back the stty value, verifies a fresh shell marker before releasing the lease, never injects RSP detach, and closes the Session on failure or ten-second timeout. That gives the agent concrete consequences beyond the annotation flags.

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 and front-loaded, starting with the triggering condition and then covering the operational sequence and failure behavior. Every sentence contributes useful 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?

Given the output schema and annotation coverage, the description supplies the remaining critical context: when to run it, what it verifies before lease release, what it will not do, and what happens on failure or timeout. Nothing essential for correct invocation 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?

Schema description coverage is 100%, so all four parameters are already fully documented. The description reinforces the meaning of tty_state and confirm_shell_ready in context, but it does not add new constraints or explain owner/bridge_id 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 names a specific restoration-verification operation: confirming shell readiness, applying/read-back of the saved stty -g value, verifying a fresh shell marker, and releasing the lease. It is clearly distinct from generic close/list tools, though it does not explicitly name an alternative sibling.

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 a clear triggering condition: use this after external GDB disconnects and the target returns to its shell. It also states an exclusion, 'Never injects RSP detach,' but does not explicitly route the agent to a specific alternative tool.

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?

Adds substantial context beyond the annotations: 24-hour maximum bridge lifetime, loopback-by-default binding with allowed_peer required for non-loopback, a secret connection descriptor returned for channelterm rsp-client, and the fact that explicit acknowledgement is mandatory because passive checks cannot prove readiness. It does not explain why destructiveHint=true (what is torn down or invalidated), which keeps it below 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?

Front-loaded with the core action, and nearly every sentence carries a distinct constraint (acknowledgement, defaults, retry, renewal, lifetime). The paragraph is dense and packs several unrelated operational rules together, which slightly hurts scannability.

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 stateful, security-relevant bridge tool it covers binding policy, authentication requirements, acknowledgement, renewal, retry, lifetime ceiling and where to report results. An output schema exists, so return-value detail is rightly omitted.

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 still adds operational meaning by tying owner/request_id to exact-retry idempotency and allowed_peer to non-loopback binds. It does not add anything for listen_address/strict_port_pool beyond the already-detailed 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?

Specific verb and resource: bridge a prepared serial Session to one external GDB over pinned TLS/TCP. It explicitly excludes the nearby capabilities an agent might confuse it with — starting/controlling GDB or gdbserver, probing RSP — which separates it from debug_start and debug_command.

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 the preconditions (target already prepared and acknowledged), the retry rule (reuse owner/request_id and identical parameters), the lease renewal cadence, and routes reporting to debug_bridge_report. Alternatives and when-not conditions are stated rather than implied.

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, so the description earns credit for adding real behavioral context: it does not renew the heartbeat, does not disclose connection secrets, and “Disconnected retains exclusive ownership.” The warning that disconnect does not mean the target or shell recovered is a substantive side-effect clarification 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 action and its negative side effects front-loaded. The second sentence is dense but each clause carries distinct information about ownership and status interpretation.

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, so return values need not be explained, and the annotations cover the safety profile. The description supplies the semantic caveat about “Disconnected” that an agent would otherwise misread; only explicit sibling routing 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%, with both `owner` and `bridge_id` fully documented in the schema, so the baseline is 3. The description adds nothing about parameter formats or provenance beyond what the schema already supplies.

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 (“Read external RSP bridge status”) and implicitly separates itself from debug_bridge_renew by saying it reads status “without renewing its heartbeat.” It does not explicitly name the sibling to use for renewal, so 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?

The “without renewing its heartbeat” clause hints that debug_bridge_renew is the tool for keeping a bridge alive, and the note about “Disconnected” guides interpretation of results. However, there is no explicit statement of when to call this versus debug_bridge_list, debug_bridge_report, or debug_bridge_renew.

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 cover the safety profile (destructive, idempotent, open-world), and the description adds real context beyond them: asynchronous execution, the 60-second heartbeat, retry semantics, and explicit capability limits (no raw MI/console, no multi-inferior). It does not explain what destructive actions affect or auth/permission behavior, leaving a small gap versus 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?

Four dense sentences, front-loaded with the core action, then retry, async, and limitation details in priority order. No wasted text.

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 so return values need not be repeated, and the description supplies the async/event-consumption and limitation context an agent needs to call correctly. It could be marginally more explicit about heartbeat timing behavior but is otherwise complete for a complex control tool.

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 the schema already documents owner, argument, debug_id, and request_id. The description reinforces retry semantics for request_id but adds little argument syntax or enum meaning beyond the schema, so 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+resource ('Execute one supported GDB action') and adds a secondary capability ('renew the 60-second debug heartbeat'). It distinguishes the event-consumption path by pointing at debug_events, though it does not clarify its boundary against debug_start/debug_stop/debug_bridge_* siblings.

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

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

Gives clear operational context: renewal is the heartbeat action, retries reuse request_id unchanged, and stops must be consumed via debug_events rather than this tool. It lacks explicit when-not conditions or a direct comparison to sibling debug tools, keeping it at 4.

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 usefully explains why annotations declare readOnlyHint=false on an event reader: it 'renews the client heartbeat,' a real side effect. It also discloses error semantics ('a stale cursor is an error, never silently skipped') and encoding behavior for invalid UTF-8 MI values, which the annotations cannot convey. Remaining gaps are minor given the schema covers timeout behavior.

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 with no filler; the core wait behavior is front-loaded and each following clause adds a distinct contract (heartbeat, cursor errors, encoding).

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 long-poll event reader with a full input schema and an output schema, this covers order guarantees, cursor lifecycle, side effects, and error behavior. The term 'MI' is left unexpanded, but everything needed to call the tool correctly 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 description coverage is 100%, including cursor ordering, owner secrecy, and timeout bounds, so the schema already carries parameter meaning. The description only adds the ordering/staleness contract around cursor and the base64 rule for values, meeting the baseline but not exceeding 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 gives a specific verb and resource ('Wait for ordered MI records and lifecycle events after a debug cursor'), which clearly separates this polling tool from siblings like debug_command, debug_start, and terminal_read_device_events. It never names those siblings explicitly, so the 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?

Usage context is implied through the cursor contract ('after a debug cursor', stale cursor is an error), which tells an agent this is a sequential follow-up call rather than a one-shot read. There is no explicit statement of when to prefer this over debug_command or the terminal_* read/wait tools, nor any prerequisite beyond the cursor.

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 destructiveHint=true, idempotentHint=true and openWorldHint=true, so the bar is lower, yet the description still adds real substance: exclusive managed lease semantics, the shared-environment requirement, attach-mode rejection rules, the single-inferior/multithreaded/all-stop limitation, and the idempotency mechanism (unchanged owner + request_id). The notable gap is that for a destructiveHint=true tool it never says what is destroyed or what happens to an existing debug session, and it does not mention lease expiry or concurrency conflicts.

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 with no filler, front-loaded with the core action and mechanism before the constraints and retry note. The tradeoff is terseness bordering on cryptic ('ChannelTerm, GDB, gdbserver, and ELF must share one Linux environment'), which costs a read or two but wastes no words.

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, so return values need no explanation, and the description covers the two operating modes, environment preconditions, and retry semantics for a tool with a destructive, leased, open-world profile. It falls short on failure modes and on the lifecycle after start (which siblings to call next, what debug_stop or lease release does to the 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?

With 100% schema description coverage the baseline is 3, and the description earns above that by adding behavior the schema does not: that omitting PID launches with isolated I/O, the attach rejection conditions, and the retry contract for owner/request_id. It still doesn't clarify the gdb/gdbserver default resolution or the 128-argument cap, but those are already in 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 and resource — 'Start native Linux user-space GDB/MI on an idle Bash Session using an exclusive managed lease' — plus the exact environment constraint (ChannelTerm/GDB/gdbserver/ELF must share one Linux environment). An agent knows precisely what is being created. It does not, however, name or differentiate itself from the obvious siblings debug_bridge_start or debug_command, so the agent must infer the boundary between user-space GDB/MI debugging and the bridge 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 launch-vs-attach split is spelled out conditionally ('PID omitted launches with isolated I/O; attach rejects controlling terminals, pipes, sockets, or shared character devices'), and the retry path is explicit ('Reuse owner and request_id unchanged to retry'). What is missing is routing guidance against alternatives: nothing says when to pick this over debug_bridge_start or when to follow with debug_command/debug_stop. Usage is implied by the constraints rather than stated as when-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?

The description goes well beyond the annotations by explaining detach vs terminate behavior, protocol-completion waiting, terminal-mode restoration, harmless shell probing, recovery-failure session closure, and retry safety. These details are consistent with destructiveHint=true and idempotentHint=true.

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 but front-loaded, starting with the core action and then covering defaults, side effects, failure handling, and retry behavior. Every sentence adds operational value without 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?

Given the tool's complexity, available output schema, and rich annotations, the description provides enough detail for an agent to call it correctly. It covers default behavior, termination constraints, terminal restoration, failure consequences, and retry semantics.

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

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

Schema description coverage is 100%, so owner, debug_id, and terminate are already documented in the input schema. The description reinforces terminate semantics and adds little new parameter-level detail beyond what the schema already 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 opens with a specific verb and resource: 'End debugging.' It immediately distinguishes this from debug_start/debug_command/debug_events by describing session termination behavior, and an agent can identify it as the teardown counterpart 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?

It gives clear invocation context: detach by default, terminate only for launched processes, and safe retry. It does not explicitly name alternative sibling tools such as debug_bridge_close or terminal_session_detach, but the usage conditions for this tool are stated clearly.

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 readOnly=false, destructive=false, idempotent=false, but the description adds the genuinely useful contention model: readers are unaffected while competing writers fail until release. It leaves out lease duration/expiry and what error the caller sees when acquisition fails, which are the remaining behavioral unknowns.

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

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

Two short sentences, no filler, and the exclusivity scope is front-loaded before the contention consequence. Every clause 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?

An output schema and annotations are present, so return values and safety profile need no explanation. However, for a lease-acquisition tool the description omits lease duration/expiry and whether acquisition blocks or fails immediately when contended, both of which affect correct invocation sequencing.

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 session_id, owner, and the type enum are already documented, including 'Opaque caller-generated lease owner capability.' The description adds no parameter-level meaning; baseline 3 is appropriate when 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 ('Acquire') and resource ('exclusive Session lease'), and the word 'exclusive' implicitly distinguishes it from terminal_renew_lease and terminal_release_lease. It does not explicitly name those siblings, but an agent can tell this is the acquisition step of the lease lifecycle.

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?

'Readers continue normally; other writers fail until release' implies when this is needed (before exclusive write operations) and what happens if skipped, but it never says explicitly when to call it versus terminal_renew_lease or how to handle an already-held lease. Usage is inferable rather than stated.

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 readOnly=false, idempotent=false, destructive=false, so the safety profile is covered. The description adds the lease precondition, which is real behavioral context, but leaves the key question open: does calling this actually stop the transfer, or only stage a confirmation that must be resolved separately? For a non-idempotent state-changing call, that ambiguity matters.

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 sentence with no filler, and the precondition is front-loaded as a 'only when' clause. It is efficient, though the terseness borders on under-specification rather than crispness.

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, so return values need not be explained. But this is one half of an apparent two-step protocol (begin -> resolve_file_transfer_cancel), and the description never says so; an agent could call it and assume the transfer stopped. For a non-idempotent state-machine step among 37 siblings, that missing linkage is a substantial 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?

Schema coverage is 100% and only one parameter exists, so the schema fully documents session_id. The description adds a meaningful constraint on that parameter — the session must hold an active file-transfer lease — which the schema field text does not say. That is a modest but real value-add above 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?

The verb 'Begin' and resource 'cancellation confirmation' are stated, but the phrasing is jargon-heavy: an agent cannot tell from this whether the transfer is actually cancelled or merely queued for confirmation. It also fails to differentiate from the sibling terminal_resolve_file_transfer_cancel, which appears to be the natural completion of this step.

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?

'Only when a file-transfer lease is active on the Session' gives a genuine precondition, which is more than most. However, there is no mention of what to do next (resolve_file_transfer_cancel), what alternative exists if no lease is active, or whether this may be called repeatedly.

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 destructiveHint=true and idempotentHint=false; the description adds the crucial blast radius (affects every attached client, not just the caller) and the transport-release side effect. It stops short of stating whether an active lease must be held or released first, which matters in a toolset full of lease tools.

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, front-loaded with the destructive scope, then the disambiguating alternative. No filler or redundant restatement of the title.

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 so return values need no explanation, and the scope/alternative relationship is fully covered. Remaining gap is prerequisite context (lease ownership or authorization) for a destructive multi-client operation, which the description leaves implicit.

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 sole parameter's schema text already defines it as an active session ID or short reference. The description adds no format, validation, or lookup guidance beyond that, so 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?

Specific verb and resource ("Close the shared terminal Session") plus explicit scope: "for every attached client and release its transport." The contrast with terminal_session_detach makes it unambiguous against the nearest sibling.

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?

Names the alternative (terminal_session_detach) and the exact condition that selects it: "to record only one client's departure without closing it." When-to-use and when-not-to-use are both stated outright.

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 (destructive, openWorld, non-idempotent) are consistent with the text, which adds substantial context: the interrupt is sent at most once, the Host manages the lease, a submitted reboot cannot be undone, cancellation releases ownership without recovery keys, diagnostics capture retains raw evidence for 15 minutes, and no credential storage exists. It also explains failure semantics (timeout means unconfirmed, not wrong key) that no annotation 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?

It is front-loaded with a one-line purpose and organized under Select/Prepare/Run/Verify/Limits, which suits a timing-sensitive destructive operation. Some material duplicates the schema (hex encoding examples, literal-marker rules), so it is a bit longer than strictly needed.

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 an output schema present the description need not document return shapes, yet it still explains status semantics (entered, boot_started, timeout, isError, structuredContent.result), the cursor/OPERATION_STATE sequencing, and unsupported cases (silent countdown, firmware-disabled interruption). Nothing an agent needs to call this correctly and recover from failure is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including the interrupt hex encodings and countdown pattern rules that the description largely restates. The description adds framing ("no default key", "do not guess or cycle through keys") but not new per-parameter semantics beyond the schema, so 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 opening sentence names a specific verb, resource, and mechanism: interrupting a single U-Boot countdown on an existing serial Session with Host-side raw-byte matching. It explicitly differentiates from siblings terminal_write, terminal_exec, and terminal_list_sessions, so an agent can route without opening another 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 states when to select this tool, when not to (idle prompt already established → terminal_write; unknown Session → terminal_list_sessions), and the preconditions that must hold before calling. It also names the alternatives and the evidence required to pick them, 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?

Annotations already declare destructive=true, readOnly=false, idempotent=false, and openWorld=true. The description adds meaningful context beyond them: the command is non-interactive, requires an idle Bash prompt, and is not added to Bash history. It does not elaborate on destructive implications, but the annotations cover that safety profile.

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 definition is front-loaded with the primary purpose and constraints, then immediately names alternatives. Every clause carries actionable information 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?

For a destructive command-execution tool with rich annotations, full schema descriptions, and an output schema, the description covers the essential operational caveats: non-interactive use, idle prompt requirement, history suppression, and U-Boot avoidance. Nothing critical is missing for correct 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 all three parameters are already documented in the schema. The description reinforces that only one non-interactive command is allowed, but it adds no syntax or timeout details 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 and resource: execute one non-interactive command through an idle Bash prompt. It immediately distinguishes the tool from terminal_write and terminal_enter_uboot by naming the exact contexts where those siblings are required.

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 use conditions and exclusions, including the critical warning never to use it at a U-Boot prompt. It also routes the agent to the correct alternatives, terminal_write and terminal_enter_uboot, for those cases.

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 signal a non-read-only, non-idempotent operation; the description adds crucial behavior: sensitive byte inclusion, metadata-only default, ID/size/SHA256 return values, a four-archive/15-minute retention limit with oldest-first eviction, and no filesystem path exposure.

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 tight sentences, front-loaded with what is exported, followed by the sensitive-data flag, return values, download route, and retention behavior. No sentence is redundant.

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?

Even though an output schema exists, the description supplies the operational context an agent needs: default vs sensitive content, how to retrieve the archive, retention/eviction behavior, and the absence of a filesystem path.

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 adds meaningful semantics for include_raw beyond the schema by emphasizing sensitive terminal/output/write byte inclusion and the metadata-only default. session_id remains adequately covered by 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: export a bounded ZIP snapshot of retained Session evidence. It clearly distinguishes from the sibling download tool by naming terminal_read_diagnostic for retrieval.

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?

Explains that default exports are metadata-only and include_raw=true is required for sensitive terminal/output/write bytes. It also routes the agent to terminal_read_diagnostic for download, though it does not explicitly compare against other diagnostic-read siblings.

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 adds real behavioral context beyond the annotations: the call blocks/waits, and it can only proceed at a 'safe block boundary' while cancellation is pending. It does not say how long it waits, whether there is a timeout, or what happens if cancellation is never confirmed. The 'safe block boundary' phrasing is unexplained jargon.

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 with no filler; the blocking condition is attached to the core action. It is efficient, though the compressed jargon ('safe block boundary') trades clarity for brevity.

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, so return values need not be described, and the annotations cover the read-only posture. But in a family of ~35 terminal_* siblings heavily clustered around file-transfer leases and cancellation, the description gives no routing information, leaving an agent unable to select it 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 100%, so both session_id and owner are already documented, and the description adds nothing about them. Notably it never mentions that owner is a required opaque capability, but with full schema coverage the baseline 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 names a specific resource (a file-transfer lease) and a specific action ('check ... at a safe block boundary'), which goes beyond the tautological title 'Check File Transfer Control'. However, the verb 'check' is vague and the phrase gives no way to tell this apart from closely named siblings such as terminal_wait_file_transfer, terminal_report_file_transfer, or terminal_release_lease, all of which operate on the same lease.

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 states a condition ('while cancellation confirmation is pending') but never says when an agent should call this rather than terminal_wait_file_transfer, terminal_report_file_transfer, or terminal_resolve_file_transfer_cancel. There is no explicit when-to-use, when-not-to-use, or named alternative anywhere in the text.

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 and openWorldHint=false, but the description adds the key non-obvious guarantee that 'this tool never opens a session' despite its connection-oriented name. It also discloses the decision vocabulary (ask/connect/deny/none), which the agent cannot infer from the name alone. It does not mention caching or whether repeated calls are stable, a minor gap against idempotentHint=false.

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?

Front-loaded with the purpose, then the sequencing rule, then the outcome glossary, then the safety guarantee. Three sentences, no filler; only 'deny requires no action, and none requires no action' is slightly redundant phrasing that still signals a real distinction between the two outcomes.

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, so return structure needn't be explained, yet the description still glosses the decision values, which is the right thing to include. An agent knows when to call it, what it produces, and that it has no side effect; only error behavior for unknown endpoints is unaddressed.

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 (endpoint, transport) are documented with examples, so the baseline is 3. The description adds nothing about format, matching rules, or how transport affects the decision, so it does not exceed 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 and resource ('Evaluate the configured response to a discovered endpoint') and positions itself precisely against the sibling it feeds into (terminal_open_serial). An agent can distinguish it from connection/opening tools 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?

Gives an explicit trigger ('After an appeared device event') and an explicit ordering ('call this before terminal_open_serial'), plus the downstream meaning of each outcome. This is a when-to-use plus what-to-do-next instruction, not just context.

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 and openWorldHint=false, so the safety profile is covered; the description goes further by confirming it creates no sessions and opens no devices, which is the real behavioral risk here. It does not touch the idempotentHint=false point (results change as devices appear/disappear), which is the one remaining ambiguity.

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, front-loaded with the verb and resource, with the no-side-effect clause appended exactly where it matters. Nothing redundant.

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 there are no inputs, so the description's job is mostly done. What is missing is only cross-referencing to sibling discovery tools, a minor gap for a simple read-only lister.

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?

Zero parameters, so per the baseline no parameter explanation is needed. The description correctly spends no words on inputs and focuses on the side-effect profile instead.

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 (List) and resource (devices detected by ChannelTerm) and adds scope qualifiers ('currently present'). It implicitly separates itself from session/connect tools by noting it does not open devices, though it never names the adjacent siblings (terminal_list_serial_ports, terminal_list_sessions) an agent might pick instead.

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?

'without opening them or creating sessions' hints at when this is the lightweight discovery step, but usage is only implied. There is no explicit 'use this before terminal_open_serial' or negative routing against the other list_* 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered by structured data. The description adds real value by clarifying ports are enumerated without being opened (non-exclusive, no side effects), but it does not address why idempotentHint=false or what a detection snapshot means over time.

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 with no filler; the key constraint ('without opening them') lands at the end without bloating the text.

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 an output schema covering return values, annotations covering safety, and no parameters, the description says enough to call the tool correctly. It could be slightly stronger by hinting at what the returned port entries represent, but nothing essential is absent.

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 there is nothing for the description to disambiguate; baseline of 4 applies. No parameter-related guidance is needed or missing.

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 (list serial ports) and scopes it to ports 'currently detected by the operating system'. The phrase 'without opening them' implicitly separates it from terminal_open_serial, though no sibling is named 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?

The 'without opening them' clause implies a discovery-then-open workflow, but the description never states when to use this versus terminal_open_serial or terminal_list_devices, and offers no exclusions.

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 and openWorldHint=false, so the safety profile is covered. The description adds only the notion of 'lifecycle states' as content, without stating ordering, pagination, or whether inactive/terminated sessions are excluded or merely annotated.

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 with no filler or repetition of the title. It could carry one more clause of routing information within the same length budget.

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, read-only listing tool with annotations declaring safety and an output schema covering return values, the description supplies everything an agent needs to select and call it. Remaining details (pagination, ordering) are naturally carried by the output 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 tool takes zero parameters and the schema is an empty object, so there are no parameter semantics to document. Baseline 4 applies.

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

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

The description uses a specific verb and resource ('List active terminal sessions') with a clear scope qualifier ('active'), which separates it from mutating siblings like terminal_close or terminal_session_attach. It stops short of naming which sibling is the alternative for non-active/historical 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are referenced despite a large sibling set (terminal_session_events, terminal_read_activity, debug_bridge_list) that could plausibly be confused with it. Usage is only implied by the word 'active'.

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 destructiveHint=true, openWorldHint, idempotentHint=false and readOnlyHint=false. The description adds one valuable behavioral constraint not in the annotations – the approval gate. However, it doesn't explain why the operation is destructive (e.g. whether it claims/holds a serial port or can disrupt an existing session) or what happens on failure.

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, then the gating rule. Efficient and no filler, though the second sentence is dense and could be split for readability.

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 a full input schema, an output schema, and rich annotations, the description only needs to supply the routing/precondition context, which it does. The one gap is that it never mentions whether a lease must be acquired first (terminal_acquire_lease exists as a sibling), which is a plausible source of wrong invocation ordering.

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% across 11 parameters, including enums for parity, stop_bits and flow_control, so the schema carries the semantics. The description only alludes to 'profile and optional connection overrides' and adds no format or default detail beyond that. 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?

States a specific verb and resource: 'Open a serial terminal session from a profile and optional connection overrides'. It's clear what the tool does, but it doesn't distinguish itself from close siblings such as terminal_session_attach or terminal_acquire_lease, which an agent may confuse with opening a session.

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

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

Gives an explicit precondition ('only after user approval or a terminal_get_connection_decision action of connect') and names the sibling that produces the required signal. It also carves out the exception ('explicit user-requested connections remain allowed'), so the routing rule 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 carry the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds genuinely non-obvious semantics: retained output does not prove current device state, and countdown interruption is host-side rather than client-driven. It does not state retention depth or cursor-invalidation behavior, which is why it is 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 tightly packed sentences, front-loaded with the immediate-read rule and the terminal_wait alternative. The U-Boot sentence is long but delivers actionable routing guidance rather than filler; minor density cost keeps it from a 5.

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 an output schema and full annotation coverage, the description need not restate returns, and it supplies the behavioral caveats an agent needs (staleness of retained prompts, U-Boot workflow handoff). It omits retention limits and what happens with an invalid/expired cursor, a modest remaining 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?

Schema coverage is 100%, so every parameter including cursor semantics is already documented in the schema; the description's cursor-omitted/immediate rule largely restates the schema's 'when set, wait for newer output'. Baseline 3 applies 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 (read retained terminal output) with the exact condition that selects immediate-vs-blocking behavior: cursor omitted. It explicitly names the sibling it is not (terminal_wait) and the tool it feeds (terminal_enter_uboot), so an agent can route correctly 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 when-to-use (cursor omitted for immediate read), the alternative and its trigger condition (terminal_wait after a known cursor), and a when-not-to-do-something warning: don't poll and send keys from the client to catch the U-Boot countdown, let the Host-side terminal_enter_uboot interrupt 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?

Annotations already declare readOnlyHint=true, openWorldHint=false and idempotentHint=false, so the safety profile is covered. The description adds real behavioral context the annotations cannot: that only 'retained' activity is returned and that the default call is non-blocking. It stops short of describing pagination or what max_events does to the result shape, which the output schema partly covers.

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, zero filler, with the default path stated before the escape hatch to the sibling. Nothing could be removed without losing routing 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?

An output schema exists and all parameters are documented, so return values need not be explained. The only residual ambiguity is that the schema says a supplied cursor causes a wait, while the description points to terminal_wait_activity for waiting — an agent may hesitate over which call blocks, though the intent is recoverable.

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 cursor, max_events, timeout_ms and session_id are all documented structurally. The description reinforces the cursor's role but adds no format, default, or interaction detail beyond the schema text. Baseline 3 applies when the schema carries the weight.

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 ('Read retained Session activity') and immediately scopes the default behavior ('immediately when cursor is omitted'). It names the sibling terminal_wait_activity as the contrasting operation, so an agent can distinguish the two 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?

Gives an explicit decision rule: omit cursor for an immediate read, use terminal_wait_activity to wait on a known activity cursor. This is exactly the when-to-use / when-to-use-something-else routing an agent needs, stated in one sentence.

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?

Without relying on the annotations, the description discloses blocking semantics that the readOnlyHint does not convey: omitting cursor returns retained events immediately, supplying cursor makes the call wait for newer ones. It also adds a workflow constraint (decision check before opening a serial session) that no annotation captures. Minor gaps remain — nothing about retention window or event-volume limits — but the mutation/blocking 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?

Two dense sentences, each clause load-bearing: the immediate/wait distinction first, the alternative next, the post-read workflow last. No preamble and no repetition of the title.

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 an output schema present, return values need no explanation, and annotations cover the safety profile; the description supplies the sequencing an agent can't infer from structure alone. It stops short of explaining event retention or how many events typically accumulate, which a caller would still want.

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 cursor semantics, max_events, and the 86400000 ms cap are already documented in the schema. The description's cursor clause largely restates what the schema already says and adds nothing for max_events. Baseline 3 applies when the schema carries the parameter burden.

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 (reads retained device appearance/disappearance events) and couples it to a condition (immediately when cursor is omitted). It names the sibling it is not — terminal_wait_device_event — so an agent can separate the two 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?

Explicitly covers when to use it (no cursor → immediate read), the alternative (terminal_wait_device_event to wait after a known cursor), and a mandatory follow-up routing rule (terminal_get_connection_decision before opening a serial session after an appeared event). This is exactly the when/when-not/next-step guidance an agent needs.

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 cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds genuinely new behavior: archives are time-limited and can be evicted, content is base64-encoded, and integrity should be checked against the exported SHA256. It leaves out what happens at end-of-archive or after eviction, and why idempotentHint=false despite a byte-addressable 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 short sentences, zero filler, with the core read semantics front-loaded and the operational caveats (expiry, SHA256 verification) trailing in a single compact clause.

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 an output schema present, return-value detail is not needed, and the description covers the essentials for a chunked read. The remaining gap is how an agent knows it has reached the end of the archive or should retry after eviction.

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 33% (only max_bytes has a schema description), so the description must compensate. It does: it defines offset as an archive byte offset explicitly not a session cursor, ties diagnostic_id to the archive, and restates the 65536 upper bound that governs max_bytes.

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+unit: read ZIP bytes of a diagnostic archive by diagnostic_id and byte offset, returned as base64. That is precise enough to distinguish it from terminal_export_diagnostics (creation) and from cursor-based reads, though it never names those siblings 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?

Gives real usage context: call before the archive expires or is evicted, and verify the exported SHA256 afterward. The clause 'This offset is not a Session cursor' pre-empts the most likely misuse (confusing it with terminal_read/terminal_wait cursor semantics). It does not say whether terminal_export_diagnostics must run first.

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 destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds the meaningful ownership constraint ('owned by this operation'), implying the owner capability is validated, but it does not say what happens on owner mismatch or releasing an unknown/expired lease.

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 with zero filler. The verb, resource, and ownership qualifier all appear before any subordinate clause.

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 the output schema present and annotations covering the mutation profile, the essentials are covered. Still, for a destructive mutation the description says nothing about failure modes (owner mismatch, already-released lease) or the effect on concurrent holders, which an agent would want before calling it.

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 session_id and owner are documented in the schema; the 3 baseline applies. The phrase 'owned by this operation' loosely links the owner parameter to the caller, but adds no format or matching rules 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 gives a specific verb ('Release') and resource ('exclusive Session lease') along with the ownership scope ('owned by this operation'). It is clearly distinct from terminal_acquire_lease and terminal_renew_lease by name semantics, though it never explicitly names the sibling it pairs with.

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 only implied: an agent infers this is the counterpart to acquiring a lease. There is no explicit when/when-not guidance, no mention of terminal_renew_lease as an alternative, and no stated prerequisite that a lease must already be held.

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=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the lease is exclusive and owner-scoped, but omits the operationally important behavior: how much the TTL is extended, what happens on a failed/expired renewal, and that repeated calls stack extensions (implied by idempotentHint=false).

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 with no filler; the critical timing constraint sits at the end of a compact statement rather than buried in prose.

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, so return values need no explanation, and parameters are fully covered. However, for a non-idempotent lease mutation the description never states the consequence of missing the expiry window or whether ownership is lost, which is the main thing an agent needs to decide when to call it.

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 both parameters are documented in-schema, so the baseline of 3 applies. The description's 'owned by this operation' loosely ties to the owner capability, but no format, matching rules, or mismatch behavior is added 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?

Specific verb (Renew) plus specific resource (an exclusive Session lease owned by this operation), with a timing qualifier ('before it expires'). The verb alone cleanly separates it from terminal_acquire_lease and terminal_release_lease, though those siblings are never named 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?

'before it expires' hints at when to call, but there is no guidance on cadence, on what to do if the lease has already lapsed, or on why one would renew rather than re-acquire via terminal_acquire_lease. Usage is implied rather than stated.

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 the mutation/non-idempotent/non-destructive profile, and the description adds two things they do not: an authorization precondition (must own the active lease) and the fact that the event is published without emitting terminal output. It does not warn that non-idempotent repeats may duplicate events, which keeps it off 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?

One front-loaded sentence with no filler; the scope constraint precedes the clarifying negative clause, so the agent reads the essential restriction first.

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 an output schema present, a fully described 6-param schema, and annotations covering safety, the description need not explain return values. It is nearly complete, missing only failure behavior when the lease is stale or already released.

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 all six parameters including the type enum and nested metadata are documented in the schema. The description adds only the owner/transfer_id linkage ('caller-owned active lease'), 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+resource ('Publish a file-transfer status event') and narrows scope to 'the caller-owned active file-transfer lease'. The clause 'without writing terminal output' implicitly separates it from terminal_write / terminal_write_leased, though no sibling is named outright.

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 precondition 'caller-owned active file-transfer lease' implies this is only callable mid-transfer, which is useful, but there is no explicit when-to-use vs when-not guidance and no named alternative (e.g. terminal_file_transfer_checkpoint, terminal_wait_file_transfer).

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 destructiveHint=true and idempotentHint=false, so the safety profile is known. The description adds genuinely non-obvious behavior: the false branch resumes the transfer while true blocks for safe cleanup and lease release, which tells the agent what each choice actually causes.

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 tight sentence with the core behavior front-loaded and the two branch outcomes packed into one clause. Nothing is wasted or redundant.

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 an output schema, full parameter documentation, and destructive/non-idempotent annotations, the description covers what an agent needs about the two outcomes. Minor gap: it does not say what happens if the request_id is stale or expired, a realistic failure mode for a confirmation-resolution tool.

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, and the description earns above it by explaining the consequence of the cancel boolean (resume vs. wait-for-cleanup) — meaning the schema's 'True only for an explicit y/Y answer' does not convey. The session_id and request_id parameters 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 states a specific verb (Resolve) and resource (a file-transfer cancellation confirmation), which is distinct from the sibling terminal_begin_file_transfer_cancel that presumably starts the flow. It is clear what the tool does, though 'resolve a confirmation' is slightly abstract without the accompanying true/false semantics.

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 clause 'false resumes and true waits for safe cleanup and lease release' implicitly frames this as the follow-up step to terminal_begin_file_transfer_cancel, but the description never explicitly states that sequencing or names the alternative. Usage is inferable rather than instructed.

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 a non-destructive, non-idempotent mutation; the description adds real value by scoping the side effects (no lease taken, no terminal bytes written). It does not address what a repeat call does given idempotentHint=false, nor any auth prerequisites, so it stops short of fully covering the mutation profile.

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 sentence that front-loads the action and immediately qualifies it with the two things it deliberately does not do. No padding or redundancy.

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

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

With an output schema available, return values need not be explained, and the description supplies the critical side-effect boundary for a non-destructive mutation. The remaining gap is whether attachment is live versus recorded-only and what repeated non-idempotent calls yield.

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 both session_id and the optional actor label documented in the schema itself. The description adds no format, default, or resolution behavior (e.g., what 'short reference' resolves against) beyond what the schema already states, so 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 names a specific verb and resource: recording a client attachment on the Session event stream. The negations ('without acquiring a lease or writing terminal bytes') separate it from terminal_acquire_lease and terminal_write. It falls short of 5 because it never resolves whether a live attachment is actually established or only a record is written.

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 'without acquiring a lease or writing terminal bytes' clause implies when this tool is preferable to lease-based siblings, but no sibling is named and no explicit when-to-use or when-not-to-use condition is given. The agent must infer that terminal_acquire_lease is the alternative path.

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 indicate mutation (readOnlyHint=false), non-destructive behavior, and non-idempotency. The description adds useful behavioral context by explaining that detachment is recorded on the event stream and does not close the Session for other clients, though it does not elaborate on idempotency or auth requirements.

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 efficient sentence that front-loads the action and follows with the key distinction from terminal_close. Every clause carries useful selection or behavioral 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?

The tool is relatively simple, the schema fully documents parameters, and an output schema exists. The description sufficiently explains the operation and its non-closing semantics, though it could optionally mention actor relevance or event-stream implications in more detail.

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 both session_id and actor are already documented in the schema. The description does not add parameter-level meaning beyond what the schema provides, making the baseline score 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 states a specific verb and resource: record one client detachment on the Session event stream. It immediately distinguishes the action from terminal_close by clarifying that this does not close the shared Session for everyone.

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 explicitly gives the condition for this tool—detaching one client without affecting others—and names the alternative terminal_close for closing the shared Session for everyone. The boundary between the two sibling tools 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 establish this as a read-only operation, so the description's main added value is the payload boundary: events never include terminal output bytes. It does not disclose ordering, retention window, whether the wait blocks until timeout, or what happens when the cursor is stale relative to the non-idempotent hint, leaving notable gaps.

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 read behavior front-loaded and the payload exclusion stated immediately after. No filler, though the wait mode is compressed enough to be slightly ambiguous about blocking 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?

With an output schema present and full parameter coverage, the description only needs to frame intent and scope, which it does. The remaining gap is the wait/blocking behavior and cursor lifecycle, which matter for a non-idempotent read-with-wait tool.

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 all four parameters including cursor, max_events, timeout_ms, and session_id are already documented in the schema. The description only restates the cursor→wait relationship the schema already spells out, adding no format, range, or default detail beyond 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?

States a specific verb and resource: reading retained structured Session events, with an optional wait mode keyed on a cursor. The explicit exclusion of terminal output bytes helps distinguish it from terminal_read, though it doesn't name the similarly-named siblings like terminal_read_activity or terminal_read_device_events.

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 'or wait for events after an event cursor' clause implies two usage modes (drain vs. block/wait), which is useful selection context without saying so explicitly. It never names alternatives such as terminal_wait_activity or terminal_read_activity, so the agent must infer which read surface to pick.

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 and openWorldHint=false, so the safety profile is covered. The description adds important behavioral context: this is a cursor-based wait for terminal output, not an immediate snapshot, and it does not cover file-transfer completion or cancellation. It does not discuss timeout or blocking behavior in depth, but that is largely covered by 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?

Two sentences, front-loaded with the core action and immediately followed by the sibling exclusions. Every clause earns its place by preventing a likely misuse.

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 full schema descriptions, annotations, and an output schema, the description supplies the key routing and behavioral context an agent needs. The only minor gap is deeper timeout/wait semantics, but those are bounded by the schema and annotations.

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 cursor, timeout_ms, max_bytes, encoding, and session_id are already documented. The description reinforces the meaning of cursor as a known position for waiting, but adds no syntax, defaults, or constraints 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 names a precise action ('wait only for terminal output bytes after a known cursor') and explicitly distinguishes it from terminal_read and terminal_wait_file_transfer. An agent can identify the tool's exact scope 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?

It states when to use this tool versus terminal_read ('use terminal_read without cursor for an immediate snapshot') and explicitly excludes file-transfer waiting in favor of terminal_wait_file_transfer. The alternatives and selection conditions are 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 and openWorldHint=false, and the description adds the key behavioral trait beyond them: this call blocks/waits for newer events rather than returning immediately. It does not say what happens when the timeout elapses (empty result vs. error), which is the one missing 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 sentence whose first clause carries the core behavior and whose second clause routes to the alternative; nothing is wasted or buried.

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 annotations covering safety, full schema coverage on parameters, and an output schema handling return values, the description supplies the only thing structured fields can't: that this is a blocking wait vs. an immediate snapshot. Timeout-expiry behavior is left implicit but is inferable from the timeout_ms parameter.

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 cursor, max_events, session_id, and timeout_ms are already documented with their bounds. The description reinforces the cursor's meaning ('after a known cursor') but adds no new syntax or format 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 ('Wait for Session activity events') scoped by a cursor, which is exactly what distinguishes it from the polling siblings. An agent can tell this apart from terminal_read_activity and terminal_read 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?

Explicitly names the alternative (terminal_read_activity) and the condition that selects it ('without cursor for an immediate snapshot'), which is the inverse of this tool's cursor-based wait. When and when-not are both implied by that single contrast.

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 and openWorldHint=false, so the safety profile is covered; the description adds the important behavioral fact that this is a blocking wait whose result must be followed by a decision call before opening a port. It stops short of describing timeout/pagination edge behavior, but the sequencing context is genuinely additive.

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 short sentences, no filler: the operation, the contrastive alternative, and the required follow-up chain. The core purpose is front-loaded in the first clause.

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 so return values need not be explained, parameters are fully documented in the schema, and the description supplies the cross-tool workflow that structured fields cannot express. Nothing needed to invoke it correctly 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% and each parameter is documented there, so the schema does the heavy lifting. The description reinforces cursor resumption semantics ('after a known cursor') but adds no format, bound, or interaction details beyond what the schema already states.

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 (wait) and resource (device appearance/disappearance event) plus the scope qualifier 'after a known cursor.' It is immediately distinguishable from terminal_read_device_events, which the description itself names as the contrasting sibling.

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 says to use terminal_read_device_events without cursor for an immediate snapshot, defining exactly when this tool is and isn't the right choice. It also gives forward workflow guidance: call terminal_get_connection_decision after an appearance, before terminal_open_serial.

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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context: the wait ends on completion, cancellation, or failure after lease release, and completed transfers expose source_path, requested_path, resolved_path, renamed, and optional sha256. It does not discuss timeout behavior or event cursor advancement, keeping it below 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?

The description is three compact sentences with no waste. The core waiting behavior is front-loaded, followed by useful result fields and the sibling routing instruction.

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 100% schema coverage, an output schema, and annotations covering safety, the description supplies the remaining context an agent needs: what states end the wait, which fields matter for saved paths, and when to prefer this over terminal_wait.

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 all five parameters are already documented in the input schema. The description reinforces transfer_id and cursor usage but does not add syntax or constraints beyond what the schema provides, which matches the baseline 3 when 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?

The description states a specific verb and resource: wait for one transfer_id after an event cursor for file-transfer outcomes. It also explicitly distinguishes itself from the sibling terminal_wait, so an agent can select it 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?

It gives a direct alternative: "Use this instead of terminal_wait for file-transfer outcomes." This is an explicit routing rule that names both the preferred use case and the competing tool.

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 destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is covered; the description still adds real hazard context beyond them — shell lines follow target history and an empty Enter may silently repeat the previous command, both surprising side effects on a destructive tool. It misses the lease/permission precondition implied by the terminal_write_leased sibling and the lease tools.

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?

Front-loaded with the core verb and the terminal_exec alternative, which is good, but it then sprawls across four topics (encoding, shell history, U-Boot probing, CLI file-transfer workflow) in semicolon-chained clauses, and the CLI-environment sentence sits awkwardly inside a tool description. Every sentence is informative, but the structure is dense and shifts subject abruptly.

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 an output schema, full annotation coverage and 100% param coverage, the description covers the remaining burden well: hazards, sibling routing, and the file-transfer escape hatch. The notable omission is the lease model and the existence of terminal_write_leased, which matters for a destructive write tool.

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 required params (session_id, data) plus the encoding and actor enums are documented in-schema, including the 1 MiB decoded cap and no-trailing-newline behavior. The description's 'raw UTF-8, hexadecimal, or base64' mirrors the encoding enum rather than adding semantics, so the baseline 3 is right.

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 (write) and resource (raw UTF-8/hex/base64 bytes to a terminal session) and immediately distinguishes the sibling it is not: 'shell lines follow target history, so use terminal_exec at an idle Bash prompt.' An agent can select between terminal_write, terminal_exec and terminal_enter_uboot 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?

Explicit positive and negative guidance: use at a verified idle U-Boot prompt, use terminal_enter_uboot for countdown interruption, do not send empty Enter to probe, do not build Base64/heredoc uploads — route those through channelterm file send plus terminal_wait_file_transfer. The one gap is the closest sibling: terminal_write_leased is never mentioned, so whether a lease is required before calling this is left ambiguous.

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 destructiveHint=true, idempotentHint=false and openWorldHint=true, and the description usefully adds that this path is gated by a Session lease owned by another operation. Beyond that it says nothing about failure modes, such as an expired lease or an owner-capability mismatch, or about the irreversibility of bytes already delivered to a live terminal.

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 names the mechanism, the constraint, and the alternative with no filler. Every clause carries 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?

With an output schema, full annotation coverage and complete parameter descriptions, the description only needs to establish purpose and routing, which it does. The remaining gap is lease-lifecycle behavior on failure, which matters for a destructive write but is arguably out of scope for this tool.

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 session_id, data, owner, encoding and actor are all documented in the schema, including the 1 MiB ceiling and the 'no line ending added' behavior. The description adds no parameter-level meaning beyond what the structured schema already provides, so the baseline 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?

States a specific verb and resource (write raw bytes through an active Session lease) and constrains the scope to managed multi-step operations. It explicitly contrasts with the sibling terminal_write, so an agent can pick between the two without inspecting 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 clearly routes normal terminal input to terminal_write and reserves this tool for lease-holding callers, which is real when-to-use guidance. It stops short of covering the lease lifecycle (acquiring or renewing a lease, or what to do when the lease has expired), which are the main adjacent decisions an agent faces.

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