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

Annotations already declare readOnlyHint and idempotentHint, and the description adds the specific detail of checking the child process. It does not disclose edge cases like invalid session IDs or return value behavior, but this is minor for a read-only check.

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

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

The description is a single sentence that front-loads the action and resource, with no unnecessary words or repetition.

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

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

For a simple check tool, the description adequately states the purpose and the tool name implies a boolean result. The lack of explicit return value documentation is a minor gap, but the tool's simplicity mitigates this.

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

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

The schema has one required parameter (sid) with no description, and the tool description only implies sid is the session identifier. It does not explicitly define the parameter format, origin, or constraints, leaving the agent to infer meaning from the purpose.

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 ('check') and a clear resource ('session's child process'), distinguishing it from sibling tools like list_sessions or start. It unambiguously states what the tool does.

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

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

The usage is implied: use this tool when you need to determine if a session's child process is still running. However, it provides no explicit 'when not to use' or alternatives to other similar 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?

The description adds the specific detail that the daemon is also terminated, which is beyond the annotations' destructive hint. However, it does not disclose side effects, reversibility, or return behavior. With annotations already indicating destructiveness, this partial additional context earns a middle score.

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

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

Two short, front-loaded sentences with no filler. Every word earns its place, and the imperative 'Always close sessions when done' is a clear, useful addition without 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?

The tool is simple (1 param, no output schema), and the description covers the primary action and a usage guideline. However, it omits any mention of return values, potential errors, or what happens to unsaved data, which is relevant for a destructive operation. The presence of annotations helps but does not fully compensate.

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

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

The schema has one parameter 'sid' with no description (0% coverage), so the description must compensate. Yet the description does not mention 'sid', its purpose, format, or constraints. It is only inferable from tool context, but the description itself adds no semantic value.

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 ('terminate') and names the resource ('a session and its daemon'), clearly distinguishing it from sibling tools like list_sessions or start. It fully communicates the tool's core function.

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 instruction 'Always close sessions when done' provides clear context on when to use this tool. It does not explicitly name alternatives or exclusions, but the context is sufficient given the sibling tools and the lifecycle implied by 'close' versus 'start'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the exact return fields and structure, reinforcing that this is a safe, non-mutating observation tool. No contradictions found.

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

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

The description is two short sentences, front-loaded with the primary action, and the return-field list is compact and information-dense. Every word earns its place.

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

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

For a simple zero-parameter listing tool, the description is nearly complete: it documents the return structure and fields. It does not mention error cases or empty-list behavior, but those are minor in context and not essential 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?

The tool has zero parameters, so the schema fully covers parameter semantics. The description's return-field list indirectly confirms that no inputs are needed, which is sufficient for this case.

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 the specific verb 'List' and identifies the resource as 'active drive-tui sessions'. It clearly distinguishes this from sibling tools that modify or send input to sessions, and it even documents the return shape.

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

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

The description clearly implies the tool is for enumerating active sessions, but it does not explicitly state when to use it instead of alternatives like 'alive' or 'wait_ready'. No exclusions or alternative guidance is provided.

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 provide idempotentHint=true and destructiveHint=false, so the safety profile is known. However, the description adds no additional behavioral context such as side effects, error behavior, or interaction with existing terminal content. It only restates the action without enriching transparency.

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, concise sentence that front-loads the action and target. Every word earns its place, and there is no verbose or redundant 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 low complexity, but the description lacks return value information (no output schema) and doesn't mention potential failure modes such as invalid dimensions or non-existent session IDs. It is adequate for a simple resize but leaves open questions about observable effects.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies 'cols' and 'rows' as dimensions via 'cols x rows,' but it does not explain 'sid' beyond the implication from 'session's.' No constraints, bounds, or format details are given, leaving gaps in parameter understanding.

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

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

The description clearly states the verb 'Resize' and the resource 'session's terminal' with the target dimensions 'cols x rows.' It is distinct from sibling tools like close, snapshot, or send_text, which serve different purposes.

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

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

The description implies when to use the tool (when the terminal needs resizing) but provides no explicit exclusions, alternatives, or relationship to other session tools. It doesn't mention when not to use it or what to consider before invoking.

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 beyond the sparse annotations by disclosing key non-obvious behaviors: unknown tokens are typed as literal text (not errors), and arrow keys automatically adapt to the app's cursor-key mode (SS3 vs CSI) for curses navigation. This gives the agent insight into edge cases that wouldn't be evident from the schema or 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?

The description is relatively long but all content is functional: examples, token list, combos, and two critical behavioral notes (literal text, arrow-key adaptation). It is front-loaded with examples and well-structured. While it could be slightly more concise, it avoids redundancy and earns its length.

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

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

For a tool with no output schema and minimal annotations, the description covers the tool's complex input format comprehensively, including edge cases like literal text and arrow-key modes. The main gap is the unexplained 'sid' parameter and lack of any note about return behavior or errors. Given the tool's complexity, the description is largely complete but has small omissions.

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 0% schema description coverage, the description must explain parameters. It thoroughly explains the 'keys' format, including examples, named tokens, combinations, and literal fallback behavior. However, it entirely omits the 'sid' parameter, which is not self-explanatory from its name/type alone. Thus, only half of the parameters are semantically enriched, leaving a clear gap.

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

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

The description clearly states the tool's function: 'Send key tokens' with concrete examples (["Down", "Down", "Enter"], ["C-c"]). It distinguishes itself from siblings like send_text/send_line by focusing on key tokens (special keys, combos) rather than arbitrary text. The comprehensive list of named tokens leaves no ambiguity about what constitutes a key token.

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

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

The description provides detailed semantics but does not explicitly compare to alternatives. It implies usage when you need to send key presses, combos, or arrow keys, and notes that unknown tokens are typed as literal text, suggesting overlap with send_text. However, no explicit 'use send_text when you want to type text' guidance is given, so the usage context 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 readOnlyHint=false, indicating a mutation. The description adds the key behavioral detail that it appends Enter to the text, which is not captured in annotations or schema. It does not cover side effects or prerequisites, but for a simple typing tool this is reasonable.

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, front-loaded sentence that conveys the essential behavior without filler. Every word earns its place, making it highly concise and well-structured.

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

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

For a simple tool with no output schema and two string parameters, the description covers the core action well. However, the 'sid' parameter is not explained, and the description does not mention any side effects beyond typing, which prevents a 5.

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

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

Schema description coverage is 0%. The description implicitly references the 'text' parameter but gives no meaning for 'sid'. With two required parameters, the description fails to explain the purpose of 'sid', leaving the agent to guess based on the parameter name alone.

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 'Type text followed by Enter' clearly states a specific verb-action (type text) and the result (followed by Enter), and frames it as 'the common run this command action', which distinguishes it from siblings like send_text or send_keys. It is specific and non-tautological.

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 phrase 'the common run this command action' conveys that this tool is the standard way to execute a command in a session, providing clear usage context. However, it does not explicitly mention alternatives or when not to use it, 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?

Discloses that it types literal text and does not press Enter. With readOnlyHint=false and destructiveHint=false, this adds useful behavioral context beyond annotations. However, it does not describe potential side effects like overwriting existing field content.

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

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

Two short sentences, front-loaded with action. No filler.

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

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

For a simple 2-param tool with annotations, the description covers purpose, usage, and key behavior. Lacks explicit detail on sid and possible side effects, but is sufficient for most agents.

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 provides no descriptions for sid or text, so description must compensate. It implies sid is the session identifier and text is the literal text, but does not explicitly define sid or elaborate on text limitations. Partial compensation only.

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?

Clearly states 'Type literal text into the session' with a specific verb and resource. Distinguishes from siblings by explicitly noting 'no Enter' and 'filling fields', differentiating from send_line and send_keys.

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 usage context: 'Use for filling fields.' Implicitly indicates when to use (form filling) and excludes sending Enter, but does not explicitly reference sibling tools or state when not to use.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds substantial behavior: alt_screen semantics, json inclusion only with as_json=true, hash vs visual_hash scoping, and a warning not to mix them. This goes well beyond structured annotations.

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

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

The description is two paragraphs, front-loaded with purpose. Every clause adds value: alt_screen behavior, hash baselines, the perceive-step instruction, and parameter effects. No filler 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 no output schema, the description carries the full burden of return semantics and mostly succeeds, covering ok/alive/alt_screen/text/hash/visual_hash and wait baselines. Minor gaps remain, such as the exact meaning of `sid` and a precise definition of `ok`/`alive`, but the tool is adequately specified.

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 description explains as_json's effect (structured json included only when true) and clarifies text vs json. However, with 0% schema description coverage, the required `sid` parameter is not explicitly described, so the description only partially compensates for the schema gap.

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

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

The description uses a specific verb 'Read a semantic snapshot of the session's current screen' and immediately clarifies its role as the 'perceive' step. This clearly distinguishes snapshot from sibling send/wait/action 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 explicitly says 'always snapshot after acting rather than assuming an action landed' and explains how to use hash/visual_hash as baselines for wait_change/wait_visual_change. It does not provide explicit when-not-to-use alternatives, but the context is clear.

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

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

Beyond the annotations, the description discloses key behaviors: the session is owned by a localhost-only daemon, persists across calls, has server-side limits (concurrent sessions, sid format, env restrictions, terminal size cap), and env values may be visible in ps. This is rich, non-obvious behavioral context that helps the agent anticipate side effects and constraints.

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 well-structured and front-loaded: purpose first, then persistence semantics, then parameter details, then constraints, then security note. Every sentence contributes essential information without repetition or fluff, making it readable despite the density.

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

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

For a complex 6-parameter tool with no output schema, the description covers purpose, return format, workflow integration, supported parameter range, failure modes, and security implications. It is complete enough for an agent to invoke the tool correctly and to interpret the returned sid.

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 0% schema description coverage, the description fully compensates by explaining cmd with examples, cwd as a required existing directory, env key constraints, sid format, and cols/rows via the terminal size cap and defaults. It also adds security guidance about env values appearing on the command line, which is vital for safe 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?

The opening sentence 'Spawn a program in a new detached, persistent session and return its id' is a specific verb+resource statement that clearly distinguishes start from sibling tools like list_sessions, send_text, and close. It also immediately establishes the tool's role as the session creation entrypoint.

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

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

The description explains that the session survives across tool calls and instructs 'Use the returned sid for every other tool,' which clearly positions start as the first step in a session lifecycle. It does not explicitly mention alternatives or when-not-to-use, but the context makes the intended workflow 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses critical behavioral traits: list-order tie-breaking, screen-line right-padding making end-anchored patterns never match, and timeout not being an error. These details are crucial for correct invocation and are not present in annotations or schema.

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

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

The description is front-loaded with the core purpose, then efficiently covers edge cases. Every sentence adds value: example, tie-breaking, padding caveat, return format, timeout semantics. No fluff 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?

Despite lacking an output schema, the description fully explains the return object and its key field `index`. It covers the tricky aspects of pattern matching, timeout behavior, and screen padding. The tool is complex (multiple outcomes, tie-breaking, non-error timeout), and the description addresses all of these, making it complete for an agent.

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 0% schema description coverage, the description compensates for the most important parameters: it explains the semantics of `patterns` (list ordering, tie-breaking) and `timeout_ms` (returns success with index=-1 on timeout). It does not explicitly explain `sid`, but that is a standard session identifier likely inferred from context. Overall, it adds significant meaning beyond the raw 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 opens with a specific verb and resource: 'Wait for ANY of `patterns` to appear on screen.' It clearly distinguishes from sibling tools like wait_regex (single pattern) and wait_change by emphasizing racing multiple patterns. The pexpect reference and example make the purpose unmistakable.

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 when to use this tool: 'Race several possible outcomes at once' and gives a concrete example. It also provides ordering and timeout behavior, but does not explicitly contrast with alternative wait tools. The context is clear enough for an agent to decide, though exclusions are absent.

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 far beyond annotations by explaining the baseline default (screen at call time), hash reuse as next baseline, timeout behavior (returns ok=true with changed=false instead of error), and the exact return object fields. Annotations already indicate read-only and idempotent, but the description adds crucial operational context.

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, each essential. The description is front-loaded with the main purpose, then logically details baseline semantics, timeout handling, and return fields—no wasted words or repetition.

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?

Despite lacking an output schema, the description explicitly lists the return fields and their semantics, covers timeout and baseline behavior, and gives a usage hint. This makes the tool's behavior fully understandable for an agent to invoke 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?

With 0% schema coverage, the description compensates by explaining baseline_hash ('pass a prior hash') and timeout_ms ('Timeout is not an error'). The required sid is not described, but it is a common session identifier across sibling tools, so the gap is minor.

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

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

The description clearly states the tool's function: block until screen content changes, then snapshot. It uses a specific verb ('Block until') and resource ('screen content changes'), and explicitly differentiates from sibling wait_regex by noting it can't false-positive on existing text.

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 instructs when to use: 'call it right after send_line/send_keys to wait for ANY change from the baseline.' It also names an alternative (wait_regex) and explains why this tool is better in this scenario, providing clear context and exclusion.

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 richly discloses behavior beyond the annotations: it explains the return reason values ('MARKER', 'STABLE', 'TIMEOUT'), that timeout returns ok=true, and the right-padding caveat affecting marker matching. This adds substantial context beyond the read-only/idempotent annotations and does not contradict them.

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 appropriately sized and front-loaded. The first sentence gives the primary purpose, followed by a parameter usage note, then return behavior and a critical caveat. Every sentence contributes valuable information without 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?

Given no output schema, the description fully explains return values (snapshot plus reason with possible values), timeout semantics, and the right-padding pitfall. It covers the tool's complexity well and provides enough context for an agent to select and 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?

With schema description coverage at 0%, the description must compensate. It does for the marker parameter by explaining it is a regex, should be unanchored, and how to use it for stability-only. It also implies timeout behavior (max_wait_ms) and quiet stability (quiet_ms). However, it does not explicitly describe sid, quiet_ms, or max_wait_ms by name, leaving some reliance on naming conventions.

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

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

The description clearly states a specific action: 'Wait for a regex marker OR for the screen to go quiet (stable), then snapshot.' It uses a specific verb, resource (screen), and condition (regex or stability), and implicitly distinguishes from sibling wait tools by combining both conditions. The additional note 'Use marker="" to wait purely for stability' further clarifies the tool's purpose.

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

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

The description provides clear context on when to use the tool, including the variant 'Use marker="" to wait purely for stability.' It also explains timeout behavior ('Timeout is not an error'), which is important usage guidance. However, it does not explicitly contrast with sibling alternatives like wait_regex or wait_change.

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 (readOnlyHint, idempotentHint, destructiveHint), the description discloses critical behavioral traits: timeout returns ok=true with matched=false, screen lines are right-padded causing end-anchored patterns to never match, and it lists the exact return fields (ok, matched, alive, text, json). This is valuable context for an agent's decision-making.

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

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

The description is concise and front-loaded: purpose in the first line, then essential return info and caveats. No filler words; every sentence adds value, from the timeout behavior to the padding trap to the usability recommendation.

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?

Despite lacking an output schema, the description provides a complete picture for effective use: return keys, timeout handling, regex padding pitfall, and when to prefer this over a delay. This is sufficient for an agent to select and invoke the tool correctly in most contexts.

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 description explains `pattern` as a regex to match on screen and describes the timeout semantics (not an error, returns final snapshot). However, `sid` (session ID) is not explained, and the schema already gives names and types. With 0% schema coverage, the description partially compensates by clarifying two of the three parameters.

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

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

The description opens with a specific verb-resource pair: "Block until `pattern` (a regex) appears on screen, then snapshot." This clearly distinguishes it from siblings like wait_change and wait_visual_change by focusing on regex-based screen matching, and the phrase "the readiness sync" reinforces its distinct role.

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 says "This is the readiness sync — prefer it over a blind delay after send_line/send_keys," giving direct guidance on when to use this tool instead of a naive delay. The timeout behavior ("Timeout is not an error") also helps agents handle non-matching cases 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 already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral details: timeout is not an error, returns ok=true with changed=false plus the final screen snapshot, and explains how the baseline is chosen. This goes beyond the annotations without contradicting them.

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, then usage guidance, then timeout behavior. Every sentence earns its place, with no redundancy or fluff.

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 description covers purpose, usage context, baseline behavior, and timeout semantics. Since there is no output schema, it reasonably explains the return contract. Minor gap: 'visual_hash' is not formally defined, but the meaning is clear from context.

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

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

With 0% schema description coverage, the description must compensate. It explains baseline_hash (referred to as 'visual_hash') and how to use it, but it does not explain sid at all. Timeout_ms is self-explanatory from its name and default. This is partial compensation, not complete.

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

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

The description clearly states the tool's action: waiting for visual changes in text, selection styling, or cursor position. This specific verb+resource phrasing distinguishes it from siblings like wait_regex, which focuses on textual patterns.

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 explicit context: 'Prefer this after arrow/navigation keys in full-screen TUIs,' telling the agent when to use this tool. It doesn't explicitly name alternatives, but the preference direction is clear and helpful.

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