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

Goes well beyond the annotations (destructive/openWorld/non-idempotent) by disclosing that the batch is validated before anything is sent, that it halts on the first failing action with screen state reported, that clicks are sent with no preview and require mouse tracking, and how settle/idle timing works. It stops short of stating that typed input into a live shell is irreversible, which is the main behavioral risk for a destructiveHint=true 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?

Front-loads purpose, then a compact bulleted field map, but tucks the critical routing guidance ('use the individual tools') into the final sentence. The bullet list is dense yet each line corresponds to a distinct action type, so little is wasted.

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

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

With no output schema, the description covers the return behavior ('get the screen back once at the end', 'reports how far it got, with the screen as it stands') plus failure modes and stop conditions. Combined with the schema's 1-50 action bound and timeout defaults, an agent has everything needed to call 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%, so the schema already carries the field-level detail and a 3 would be the floor. The description adds value by grouping fields by action type and cross-referencing sibling specs ('same key specs as terminal_press', 'as terminal_scroll'), which the schema does not do; the remaining field docs are largely duplicative of 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?

Starts with a specific verb+resource ('Send a sequence of inputs in one call and get the screen back once at the end') and immediately names the driving use case. It is clearly distinguishable from the per-keystroke siblings (terminal_type, terminal_press, terminal_click) by being the batched equivalent.

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 when ('Use it when you already know the steps') and an explicit when-not with the alternative named ('when you need to look between steps, use the individual tools'). It also maps each action type back to its single-shot sibling (terminal_press, terminal_scroll), so routing 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?

Goes well beyond the annotations (destructiveHint=true, openWorldHint=true, idempotentHint=false): it discloses the refusal behavior when mouse mode is off, warns that TUIs often have destructive actions one click away, explains that idleMs/maxWaitMs are ignored in preview, and notes the coordinate-label clipping at the right edge. This is exactly the extra runtime context annotations cannot carry.

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-loads the core action, then uses clear PREVIEW/EXECUTE/CAVEATS sections so the reader can scan to what matters. The prose is dense and slightly long (e.g. the parenthetical TUI example list), but nearly every sentence carries actionable information.

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

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

For a destructive, non-idempotent 7-parameter tool with no output schema, the description covers the safety protocol, coordinate semantics, return artifact (PNG), and edge cases. The remaining gap is the execute-mode output and the exact semantics of idleMs/maxWaitMs outside preview.

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 71%, and the description adds real meaning: it pins the coordinate frame to the live viewport, explains how to obtain terminal width/height via terminal_read, and documents that preview is the default and that idleMs/maxWaitMs are no-ops in preview. It stops short of saying what idleMs and maxWaitMs actually control in execute mode, which the schema leaves undocumented.

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 precise verb+resource ("Deliver a left mouse-button click at a cell in the terminal") and scopes it to a specific coordinate system, which cleanly disambiguates it from sibling input tools like terminal_press and terminal_type. The mouse-tracking precondition further narrows exactly what this tool is for.

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 states the precondition that gates use (foreground program must have mouse tracking on, otherwise the click is refused) and gives clear preview-first-then-execute guidance. It does not name sibling alternatives such as terminal_press, but the when/when-not conditions here are strong enough to route the agent correctly.

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

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

Annotations declare a non-readonly, non-destructive, non-idempotent, closed-world write, and the description goes well beyond that: it discloses the 50-session LRU eviction with tombstoning and 'evicted' respawn behavior, plus command-mode lifecycle semantics (session lives as long as the program, exit status reported, final screen retained until destroy). This is exactly the kind of behavioral context annotations cannot carry.

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 dense paragraph, but well front-loaded: purpose and prerequisite first, command semantics second, eviction last. Every sentence carries information; it is long only because the tool genuinely has three behavioral clauses worth knowing.

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 10-parameter, zero-required, no-output-schema tool, the description covers the essential call semantics: prerequisite ordering, default interactive mode, command mode, and capacity/eviction. The only gap is the silent geometry/scrollback parameters, which are secondary to 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 70%, so the baseline is 3. The description adds real meaning for `command` (session lifetime, exit status, non-restart) and for the interactive-default contrast, but `cols`, `rows`, and `scrollback` remain undocumented in both schema and description, and `cwd`/`env` are only lightly described.

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 ('Spawn a new terminal session') and immediately declares the return value (sessionId), which is the key artifact for the siblings. It also differentiates itself from every per-session tool by establishing that it is the mandatory entry point.

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 states the prerequisite ('You must call this before any per-session tool — there is no shared default session') and elaborates the when-to-use-command-vs-interactive-shell decision with concrete examples (TUI, test run, CLI under test). The 50-session eviction rule is stated as a condition affecting usage. Nothing critical is left to inference.

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

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

Annotations only flag destructiveHint=true and idempotentHint=false; the description adds the crucial non-obvious behavior that the id is not tombstoned, future calls error with 'Unknown sessionId', and that auto-respawn only applies to system-driven terminations. This is exactly the extra context annotations cannot convey.

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

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

Three sentences, zero filler, front-loaded with the primary action before the tombstone clarification. Each sentence carries distinct information (action, id invalidation, contrast with system terminations).

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

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

No output schema exists, and the description compensates by describing the post-call state and the exact error an agent will see on misuse. For a single-parameter destructive tool, nothing needed to call 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it tells the agent what the sessionId becomes after the call (permanently invalid, errors on reuse). That is semantic value beyond the schema's 'Numeric id from terminal_create or terminal_list.'

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 ('Kill a session') and immediately clarifies the distinguishing semantic: the sessionId is forgotten, not tombstoned. Combined with the sibling set (terminal_reset, terminal_list), an agent can tell this is the terminal teardown tool rather than a reset or query.

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

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

'Use this when you're explicitly done with a session' gives an explicit trigger condition, and the tombstone contrast carves out system-driven terminations (idle-kill, eviction, shell exit) as cases where this tool should NOT be called. It stops short of naming terminal_reset as the alternative for keeping a session alive, so it's clear but not fully routed.

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

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

Annotations only cover the safety profile (readOnly, idempotent, non-destructive); the description goes well beyond them by disclosing that tombstones are reservations whose shell is gone, that calling one respawns a fresh shell and surfaces the original termination reason (shell-exit, idle-killed, evicted), and that tombstones expire after 30 days. This is exactly the non-obvious behavior an agent needs.

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

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

Three sentences, front-loaded with the core purpose, followed by the tombstone semantics that are impossible to infer from the name or schema. No filler; every sentence carries information an agent would otherwise lack.

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

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

With no output schema, the description must describe the return shape, and it does: the two categories of returned ids plus the termination-reason enum values. Combined with the rich tombstone lifecycle explanation, nothing material is missing for a zero-parameter list 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?

The tool takes zero parameters, so the baseline is 4. The description correctly adds no parameter detail because there is nothing to parameterize.

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 (terminal sessions), and immediately clarifies the two result categories: active sessions and tombstoned sessionIds. That distinction cleanly separates it from sibling tools like terminal_create or terminal_read, which act on a single 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?

Listing is self-evidently the discovery entry point, and the description implicitly signals a use case by explaining that a tombstoned id can be called again. However, it never explicitly states when to reach for this tool versus a sibling (e.g. to discover a sessionId before terminal_read), nor does it name any alternative.

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, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds one useful behavioral detail (shared settle behavior with terminal_type), but says nothing about repeat semantics, timing/idle behavior, or failure on unsupported keys.

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?

Purpose is front-loaded in the first sentence, followed by examples and the settle note. The long example enumeration is justified because there is no enum on `key`, though it is verbose enough to slightly dilute the entry message.

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

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

There is no output schema, so return values need not be explained, and annotations cover the safety profile. Still, two of five parameters are undocumented and the meaning of 'settle behavior' is left to the agent to infer, which is a noticeable gap for a mutation 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 60%, and the description substantially expands the `key` vocabulary well beyond the schema's brief examples, adding genuine value. However, idleMs and maxWaitMs remain entirely undocumented in both schema and description, and the `count` behavior is only covered by the schema itself.

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+resource ('Press a single named key or key combination'), which cleanly separates it from sibling terminal_type (text input) and terminal_click (mouse). The extensive example list of supported key values reinforces exactly what kind of input this tool consumes.

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 never states when to choose this over terminal_type or terminal_click, nor any prerequisites such as needing a live session. The 'Same settle behavior as terminal_type' line hints at a relationship but provides no explicit selection guidance or 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the contiguous scrollback+viewport index space, bottom-up paging in `rows` multiples, the 1000-row cap, and implicit trimming of trailing blank rows. It stops short of describing the return payload shape or any error/empty-buffer 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?

Front-loaded with the core action, then the buffer/window model, then paging semantics, then the trimming note. Every sentence carries information an agent needs to page correctly; nothing is padding.

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

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

With no output schema, the description carries the burden of explaining what comes back, and it does reasonably well (a window of buffer text, blank rows trimmed, cursor/highlight/wrap defaults documented in the schema). It could be more explicit about the returned structure (lines vs rows array) for a read tool with several formatting flags, but the model is clear enough to call 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 description coverage is 100%, so the schema already documents every parameter and the baseline is 3. The description adds genuine framing on top — that pages are counted upward from the bottom, that rows defaults to the current screen height and is capped at 1000, and that page 0 is the newest chunk — which clarifies the interaction between `page` and `rows`.

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 ('Read a window of the terminal buffer') and immediately defines what the buffer is, which cleanly separates it from siblings like terminal_screenshot (renders) and terminal_scroll (moves the viewport). An agent can tell what this returns and from where without opening the schema.

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

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

The paging model implicitly tells the agent this is the way to walk back through scrollback, but there is no explicit when-to-use/when-not guidance and no sibling is named (e.g., vs terminal_screenshot or terminal_scroll). Usage must be inferred from the described semantics.

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 and non-idempotent, but the description adds substantial context beyond them: what is preserved on a soft reset (env vars, cwd, history), what is lost on a hard reset (mid-execution processes), and the command-session re-run side effect. This is exactly the kind of consequence disclosure a destructive tool needs.

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 the primary effect before the optional mode, and every sentence carries distinct information (default behavior, hard-reset behavior, overrides, command-session edge case). No filler.

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

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

With no output schema and full annotation coverage, the description supplies everything needed to call this correctly: default vs hard mode, what each destroys, and the parameters that only take effect in hard mode. Nothing material 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 already documents 'hardReset only' plus defaults ($SHELL, false). The description restates the grouping of the hardReset-only overrides rather than adding new syntax or format detail, 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?

Opens with a specific verb+resource ('Wipe the terminal buffer and scrollback') and immediately distinguishes its two modes (soft clear vs hardReset kill/respawn), which separates it from siblings like terminal_resize or terminal_read. An agent can identify the operation 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?

Clearly states the default behavior and the condition that selects the alternative ('Pass hardReset: true to kill...'), plus a non-obvious edge case (a session created with `command` re-runs it). It never names a sibling as the alternative or states when *not* to reset, so it falls short of a 5.

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

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

Annotations already declare it is a non-read-only, idempotent, non-destructive operation. The description adds meaningful behavior beyond that: it resizes both the PTY and the emulator and propagates change via SIGWINCH to running programs, which an agent cannot infer from annotations alone.

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

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

Two tight sentences with no filler. The core action is front-loaded, and the parameter behavior and propagation detail follow in service of the primary statement.

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

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

No output schema exists, but for a resize tool the critical behavioral facts (partial update semantics, dual PTY/emulator resize, SIGWINCH propagation) are covered. Minor gaps remain around error conditions for invalid sessions or out-of-range sizes, though the schema bounds cols/rows.

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

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

Schema coverage is 100%, so the schema already documents cols, rows, and sessionId fully. The description restates the omit-to-preserve semantics already present in the schema, adding no new syntax or format detail. 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 ('Change the terminal size'), which an agent can immediately distinguish from siblings like terminal_read or terminal_type. The scope is precise and unambiguous.

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

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

Explains the partial-update behavior (omitting cols/rows preserves current values), which is useful contextual guidance. However, it gives no when-to-use or when-not-to-use signals relative to alternatives such as terminal_reset or terminal_create.

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 (readOnly, idempotent, non-destructive, closed-world), yet the description adds real behavior: height is always term.rows, output is inlined as base64 unless filePath is set, and images over 2097152 bytes are auto-spilled to a temp file. That spill behavior is the kind of non-obvious side effect worth crediting, though no pagination or size limits on page depth are discussed beyond the schema's clamp note.

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

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

Three sentences, each front-loaded and earning its place: output format first, then paging semantics, then file/inline behavior. No filler or restatement of the name.

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

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

With no output schema, the description does carry the return-value burden and handles it: path returned when filePath is set, base64 otherwise, temp-file spill for large images. Combined with annotations covering safety, an agent has what it needs; only the absence of any guidance on choosing between text readers and screenshots is a slight 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 the baseline is 3, but the description adds semantics the schema lacks: page windows are rendered 'at the same dimensions as the live screen,' clarifying that paged screenshots are dimensionally consistent with page 0. That is a genuine addition beyond the parameter's own text.

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

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

States a specific verb and resource with output format: 'Render a screen-sized window of the terminal to a PNG.' This distinguishes it cleanly from terminal_read (text extraction) and other siblings without needing to name them.

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

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

The description explains how to use `page` to walk scrollback, which is useful operational context, but it never states when to choose this tool over terminal_read or terminal_scroll for retrieving terminal content. Usage is implied rather than routed.

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

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

Annotations declare this is a non-read-only, non-idempotent action, and the description goes well beyond them by disclosing the emulation semantics: mouse-tracking programs receive wheel events at the cell while non-tracking programs (less, man) receive arrow keys instead, plus the failure mode at a bare prompt. It stops short of describing timing behavior for idleMs/maxWaitMs or what the call returns on success.

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 sentences, front-loaded with the mechanism and progressively narrowing to the dual-mode behavior and then the failure case. Every clause carries information an agent needs; no restatement of the tool name or schema.

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

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

For a 7-parameter mutation tool with no output schema and no annotation coverage of behavior, the description covers the hard parts: what it does, how programs respond, and when it fails. It leaves the timing parameters and the success response undefined, which is a modest but real 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 71%, and the description reinforces the coordinate model by explaining that the target cell matters 'when panes scroll independently' — which clarifies row/col intent beyond the raw bounds. However, it says nothing about amount, idleMs, or maxWaitMs, whose schema entries are terse or absent, so the coverage gap is not compensated.

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 concrete verb and mechanism ('turn the mouse wheel over a cell of a full-screen program') and enumerates the resources it acts on (pager, file list, log pane). It also explicitly distinguishes itself from the sibling terminal_read, so an agent can choose between them 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 positive conditions (full-screen program pane under the cell), an explicit when-not (a plain shell prompt has nothing to scroll and the call fails), and names the alternative for that case: terminal_read with its `page` argument. This is close to a complete decision rule.

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 the annotations by disclosing the newline normalization quirk (\n -> \r, with a worked example), the settle-wait blocking behavior, and the hard 10s cap on the wait. These are exactly the traits an agent needs to avoid mis-timing follow-up calls, and none of them appear in the structured fields.

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

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

Four sentences, front-loaded with the core action, then the normalization rule, then the blocking semantics, then the escape hatch. No filler and nothing 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 no output schema and a destructive, non-idempotent annotation profile, the description covers the key behavioral risks (blocking, timeout, follow-up tool). It stops short of saying what the call actually returns (settled buffer output vs. nothing), which is a minor 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 description coverage is 100%, so the schema already documents text, paste, idleMs, maxWaitMs and sessionId. The description only adds the \r-vs-Enter nuance for `text` and reinforces the wait cap; it does not expand meaning on paste, idleMs or sessionId. 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 ('Type literal characters into the terminal') and immediately scopes it against the alternative keystroke/settle behavior, naming terminal_wait as the escalation path. An agent can distinguish it from terminal_press and terminal_batch from the text alone.

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 when-to-use context for the slow-command case ('for anything slower (builds, installs, test runs) follow up with terminal_wait') and for paste mode (multi-line into editor/REPL/shell). It does not state when NOT to use it versus siblings like terminal_press or terminal_batch, so it stops short of explicit 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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavior the annotations cannot: kernel-level foreground detection, platform-specific Windows fallback, background-job handling, nested-program limitations, and the critical fact that a timeout is not an error and reports the command still running. It even notes no exit status is reported in shell sessions.

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 text is long but well-structured, with labeled sections (DEFAULT, until: "quiet", WITH pattern) and the core purpose front-loaded. Most sentences carry a distinct edge case, though a few restate schema-documented details, keeping it just short of fully waste-free.

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

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

With no output schema, the description steps in to explain the return ("Returns the screen when the condition is met, or when timeoutMs runs out") and the timeout semantics. Combined with the mode-specific behavior, an agent has everything needed to call it correctly across scenarios.

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

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

Schema coverage is 100%, so the schema already documents each parameter, setting a baseline of 3. The description adds real guidance beyond the schema, such as the viewport-plus-200-rows match scope and the gotcha "pick a pattern that only the new output can satisfy," which meaningfully shapes correct invocation.

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?

Opens with a specific verb and resource: "Block until the terminal reaches a state." It explicitly distinguishes itself from the sibling terminal_read ("instead of guessing with sleeps or polling terminal_read"), so an agent can tell the tools apart without opening schemas.

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

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

Gives explicit when-to-use ("after terminal_type for anything that outlives the settle window: builds, installs, test runs, servers starting up") and when-not (complex nested programs, Windows shells, servers that never exit). It also names the alternative rule (terminal_type's settle window) and routes to `pattern` where the default cannot work.

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