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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by explaining the underlying implementation (fetches via `idb ui describe-all`) and the non-destructive analysis pipeline, which aligns with the annotations. There is no contradiction, and the description enriches the behavioral context 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?

The description is long but meticulously structured with headers, tables for rules, JSON examples, and code snippets. It front-loads the core purpose and parameter details, then provides reference tables. Every section earns its place, making it easy to scan and parse 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 the output schema is present (illustrated via JSON example), the description still fully covers the return structure (summary, issues, topIssues), rules, parameter options, and related tools. All necessary information for correct invocation and interpretation is provided, and the examples clarify both default and verbose usage.

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 carries full parameter documentation. It clearly explains 'udid' (auto-detects if omitted) and 'verbose' (returns all issues vs grouped top-10) with defaults, adding meaning beyond the bare types. While concise, it fully covers what the agent needs to know.

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 ('audits') and resource ('live iOS simulator accessibility tree'), and explicitly distinguishes from 'accessibility-quality-check' by noting it diagnoses what is broken and how to fix it. The overview, rule tables, and return types 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?

Provides clear usage context by contrasting with 'accessibility-quality-check' (richness score) and listing related tools with brief guidance. It implies when to use this tool (when you need to diagnose accessibility issues) but does not explicitly state when not to use it or alternative conditions, so it falls short of a perfect 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 readOnly and idempotent, but the description goes further by disclosing the underlying mechanism ('Calls idb ui describe-all'), expected latency (~80ms), token cost comparison, and that it 'Returns quality assessment only (not full element tree).' This gives agents an accurate model of behavior and side effects beyond what annotations provide.

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 long but well-organized with clear headings, code examples, and a decision table. Some redundancy exists between Overview, How It Works, Cost Comparison, and Notes, but the structure helps an agent quickly extract the decision logic without losing important detail.

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 decision-support tool with two optional parameters and no required inputs, the description is complete: it explains parameters, return values, quality thresholds, recommendations, cost trade-offs, and relationships to sibling tools. An agent has everything needed to call it correctly and interpret the result.

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 0%, so the description must compensate. It does: udid is explained as 'Target identifier - auto-detects if omitted,' and screenContext as 'Screen name for semantic tracking' with an example value. The meaning is clear, though it could have specified expected formats or constraints more precisely.

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: 'Quick assessment of accessibility tree richness - decide whether to use accessibility or screenshots.' It clearly differentiates this tool from similar siblings like idb-ui-describe and screenshot by framing it as the decision gate before those tools.

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

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

The description explicitly says when to use the tool ('Recommended as first step before choosing automation approach') and provides a concrete decision rule: use accessibility when quality is rich, fall back to screenshot when minimal. It also names related tools and how they relate, giving clear routing 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?

Annotations already mark the tool as destructive and idempotent, but the description goes further by stating the operation is 'immediate and irreversible' and that clearing all caches forces fresh retrieval on all tools. This adds meaningful behavioral context beyond the structured metadata.

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-organized with headings and front-loads the core behavior. However, it repeats the same ideas ('force fresh data', 'purge cache systems', 'clearing all caches forces fresh retrieval') and includes an irrelevant 'Tool is auto-registered with MCP server' note, so not every sentence 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 single-parameter destructive tool, the description covers the parameter, return structure, side effects, use cases, and related tools. The main gap is the contradictory required/optional labeling and thin per-cache-type semantics, but the essential invocation details are 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?

The description merely restates the enum values already present in the input schema and adds little semantic depth about what 'simulator', 'project', or 'response' caches actually contain. It also labels cacheType as Required while the schema/context signals report zero required parameters, which is misleading rather than helpful.

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 action ('Removes all entries') on a clear resource ('cache system(s)') and states the outcome ('force fresh retrieval'). It also distinguishes itself by listing cache-get-stats, cache-get-config, and cache-set-config as related tools, making the role of cache-clear 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?

The 'Advantages' section provides concrete scenarios: stale cache issues, major Xcode project changes, performance baseline testing, and switching configurations. It lacks explicit when-not-to-use guidance or direct comparisons with cache-set-config/cache-get-stats, so it falls just 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral details: it returns both millisecond values and human-readable durations, shows default configurations before customization, and notes the fixed 30-minute response cache duration. This goes beyond the annotations, though it includes a minor irrelevant note about auto-registration.

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 with sections, but it includes non-essential content like an 'Advantages' bullet list and a 'Related Tools' list that duplicate information available from siblings. While the core information is front-loaded, the verbosity could be trimmed without losing value. It's not as concise as the high-scoring examples.

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 simplicity (one optional parameter, no output schema), the description is complete. It explains the parameter, the return format, default behavior, and fixed characteristics. It also mentions related tools for further context. Nothing an agent needs 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?

The schema has 0% description coverage (no descriptions in the input schema properties), so the description must compensate. It does so thoroughly: 'cacheType (string): Which cache config to retrieve - "simulator", "project", "response", or "all". Defaults to "all"' — this documents the parameter's purpose, allowed values, and default, fully exceeding 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 clearly states the tool's purpose: 'Retrieves the current cache retention policies for simulator, project, and response caches.' It uses a specific verb (retrieves) and resource (cache retention configuration). While it doesn't explicitly contrast with siblings, the purpose is unambiguous and easily distinguished from related tools like cache-set-config or cache-clear.

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 usage context: 'Essential for understanding your current cache configuration before making adjustments or troubleshooting performance' and 'Use to verify config changes after using cache-set-config.' It implies when to use the tool but doesn't explicitly state when not to use it or contrast with alternatives beyond listing related tools. This is slightly below the explicit guidance in the calibration example.

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, idempotent, and non-destructive behavior. The description adds useful context: statistics are calculated in real time and cover all cache systems. There is no contradiction between the description and annotations.

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

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

The description is front-loaded with a clear summary but is padded with repetitive marketing-style bullets and vague notes such as 'Export statistics for performance analysis across time' and 'Tool is auto-registered with MCP server'. A zero-parameter read-only tool does not need this much 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?

There is no output schema, so the description appropriately explains what the agent should expect: hit rates, entry counts, storage usage, performance metrics, and timestamps. It also names related cache tools, making the call context sufficiently complete.

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

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

The tool has zero parameters, and the description explicitly lists 'Required: None' and 'Optional: None'. This confirms the schema and removes any ambiguity, though there is no deeper parameter semantics to add.

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 verb and resource: it retrieves statistics from the simulator, project, and response cache systems. It is readily distinguishable from sibling cache tools like cache-get-config and cache-clear, though it does not explicitly say 'use this for stats, not config'.

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 says to use the tool for monitoring cache effectiveness and identifying optimization opportunities, giving clear context. However, it does not provide explicit when-to-use versus alternatives or when-not-to-use guidance, leaving some selection reasoning to the agent.

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, destructiveHint=false, and idempotentHint=true. The description adds behavioral context: 'Changes apply immediately', 'Response cache is currently fixed at 30 minutes', and the constraint 'Specify exactly one of maxAgeMs, maxAgeMinutes, or maxAgeHours'. This goes beyond the annotations and helps the agent understand side effects and constraints. No contradiction with 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 well-structured with sections (Advantages, Parameters, Returns, Related Tools, Notes) and front-loaded with a clear summary. Some marketing language like '⚙️ Configure cache retention times to optimize for your workflow' is slightly fluffy, but the core content is relevant and organized, making it easy to scan.

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 there is no output schema, the description lists expected returns ('Tool execution results', 'Results per cache type with human-readable durations', 'Timestamp of configuration change'). It also covers constraints (response cache fixed, minimum duration) and relationships. Everything an agent needs to configure cache retention 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 0%, so the description must fully explain parameters. It does: cacheType (with enum values), maxAgeMs, maxAgeMinutes, maxAgeHours, and the note about exactly one and minimum 1000ms. This completely compensates for the lack of schema descriptions, making parameter usage unambiguous.

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 purpose: 'Configure cache retention times' and 'Fine-tune cache retention policies for simulator, project, and response caches.' It is specific about the verb (configure/fine-tune) and the resource (cache retention). It distinguishes itself from siblings via the Related Tools section (cache-get-config, cache-get-stats, cache-clear), making clear this is the setter.

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

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

Provides guidance on when to use: 'Optimize for development workflows (longer cache = faster repeated operations)' and 'Optimize for CI/CD environments (shorter cache = fresher data)'. It also lists Related Tools like cache-get-config and cache-get-stats, giving clear alternatives. However, it does not explicitly state when not to use it or contrast with each sibling, so it's not a full 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 mark this as readOnly, idempotent, and non-destructive. The description adds useful context beyond that: it requires a stopped session and reveals whether the agent gets a summary or a per-cluster detail view. It does not describe failure modes for active sessions, but no contradiction exists.

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 tightly structured with a front-loaded purpose sentence followed by concise Parameters and Returns sections. Every element earns its place; the Returns section adds specific value by naming 'severity histogram, bursts, process distribution.'

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 the key invocation context: stopped sessions, required and optional parameters, and expected return shapes even without an output schema. It is nearly complete for a simple read-only tool; a small gap is not saying what happens if the session is still active.

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 carries the full burden for parameters. It explains that sessionId is required and that cluster is optional, 1-indexed, and 'drill[s] into one cluster's events.' This adds real meaning beyond the schema, though sessionId format/source is not detailed.

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 first sentence names a specific verb and resource: 'Return the full L2 summary for a stopped HangBuster session, or the per-event detail of a specific cluster.' This is clear and specific, but it never explicitly contrasts with siblings like hang-list or hang-stop, so the differentiation is left to the agent rather than stated 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 description gives clear context by saying the target is a 'stopped HangBuster session' and offers a conditional branch for a 'specific cluster.' It does not name alternative tools or exclusions explicitly, but the conditions for using this tool are clear enough for selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds ordering and return fields, which is useful but not extensive. It does not mention pagination, error behavior, or empty results. Given the annotations carry the safety profile, a 3 is appropriate.

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, well-structured with clear sections (Parameters, Returns), and every sentence provides value. It is front-loaded with the core action and immediately lists the return format. No wasted 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?

With no output schema, the description compensates by naming the exact fields (sessionId/status/udid/createdAt/stoppedAt) and ordering. This is sufficient for a simple list tool. It lacks details on status values or error handling, but these are not critical for invocation.

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

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

There are zero parameters, and the schema is empty. The description adds 'Parameters: None' which echoes the schema. Per the baseline rule for 0 params, a score of 4 is correct since no parameter explanation is needed beyond the schema already being empty.

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 ('List'), the resource ('all HangBuster capture sessions'), and the ordering ('newest first'), along with the output fields. This distinguishes it from siblings like hang-get-details, which presumably fetches a single session. The purpose is 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?

The description implies usage (list all sessions) but does not explicitly mention alternatives or when not to use it. Sibling tools like hang-start, hang-stop, and hang-get-details exist, but no guidance is given on choosing this tool over them. The context is clear but lacks explicit routing.

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 indicate false hints; the description adds real behavioral context by stating that a detached process is spawned, logs are written to the session's raw log, and shorter hang events are dropped at stop time per `minHangMs`. It does not enumerate cleanup or failure behavior, but it goes beyond the structured hints.

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 compact, front-loaded with purpose, and organized with Parameters and Returns sections. It avoids fluff and every sentence adds operational value for selecting and calling the tool.

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 correctly documents the return fields (`sessionId`, pid, guidance) and the follow-up tool. It covers the core invocation workflow, though it omits details such as session cleanup, concurrency, and what happens if no booted simulator is available.

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 0%, so the description must carry parameter meaning, and it does: `udid` defaults to booted, `predicate` overrides the os_log predicate, and `minHangMs` defaults to 250 and controls the filtering threshold at stop time. This is meaningful and more than the bare schema types.

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 precise verb-resource pairing: 'Begin a HangBuster capture session' and explains the concrete mechanism (spawns a detached `simctl log stream` filtered to hang/stall/watchdog/jetsam events). It also mentions the paired `hang-stop` tool, which distinguishes it from sibling simctl and idb tools.

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

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

The description lays out a clear workflow: start capture, reproduce the hang, then call `hang-stop` to parse/cluster/rank. This gives the agent an explicit usage sequence, though it does not explicitly state when alternatives like `simctl-stream-logs` or `hang-list` should be preferred.

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 readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds genuinely useful behavioral context beyond that: it discloses persistence ('persist the summary'), the full processing pipeline, and the auto-selected token-budget view (L0/L1/L2). No contradiction with annotations; the 'stop' mutation aligns with readOnlyHint=false and idempotentHint=true is plausible for a stop-and-analyze.

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 purpose, then cleanly structured into Parameters and Returns sections with headers. The pipeline enumeration (parse → normalise → threshold → fingerprint → cluster → rank) adds slight verbosity but each element earns its place by clarifying behavior. No wasted sentences.

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

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

Moderately complex tool (3 params, multi-stage pipeline, summary output) with no output schema, so the Returns section is the only source for return info. It explains counts and a formatted summary plus a drill-down pointer. Minor gap: the exact summary structure isn't specified, but the lifecycle pointer and full parameter documentation make it adequate 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 0%, so the description carries the full burden and fully compensates. All three parameters are documented with real semantics: sessionId tied to the hang-start session, topN with its default of 3, and budgetTokens explained as a size cap that selects L0/L1/L2. Every parameter is meaningfully covered despite the empty 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 chain ('Stop... parse... persist... return') with an explicit resource (HangBuster session). The clustering pipeline is enumerated, and it clearly distinguishes from siblings by referencing hang-start as the origin and hang-get-details as the follow-up. An agent can tell exactly what this does 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?

Establishes the lifecycle context ('the session from hang-start') and gives an explicit post-call pointer ('Drill deeper with hang-get-details'). It doesn't spell out explicit when-not-to-use conditions or alternative selection rules, but the lifecycle framing plus sibling pointer provides clear contextual 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?

Annotations already carry destructiveHint=true, readOnlyHint=false, and idempotentHint=true, but the description adds genuinely valuable context beyond them: 'clears credentials for EVERY app on the simulator, not just yours' — scoping exactly what gets destroyed, which the annotation cannot convey. It also discloses cost/weight relative to simctl-erase ('Cheaper and more targeted'). Nothing contradicts 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?

The description is long but well-structured with clear headers (Overview, Parameters, Returns, Examples, Related Tools, Notes), and the key behavioral insight (uninstall doesn't clear keychain) is front-loaded in the overview. Each section earns its place — examples illustrate a real composed workflow and the destructive scope warning is critical. Slightly verbose for such a simple tool, but nothing is wasted.

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

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

Complete for a destructive 3-param tool with no output schema. The description documents the return format (confirmation with audit entry: timestamp, action, scenario, step), covers all parameters, provides a worked example, routes to related tools, and warns about the destructive scope. Nothing an agent needs 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 coverage is 67%; the schema documents step and scenario but not udid. The description's Parameters section lists all three and adds one useful fact — udid 'auto-detects if omitted' — plus notes the scenario is recorded in the audit entry. This is modest added value that mostly echoes the schema rather than deeply enriching parameter meaning.

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 (clear), resource (simulator keychain), and purpose (test isolation). The overview explains why this matters — keychain entries survive app uninstall, so a fresh-install test can still be logged in. It clearly distinguishes from siblings: workflow-fresh-install (wipes data but not keychain), simctl-erase (heavier factory reset), and simctl-privacy (permission grants).

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 Related Tools section explicitly names alternatives and the precise condition that selects this tool versus them, including what each sibling does and does not do (e.g., 'workflow-fresh-install: Wipes app data, but NOT the keychain'). The example pairs it with workflow-fresh-install to demonstrate the correct composed workflow for a clean-login test.

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 transparently states deletion is permanent and irreversible, warns clients may want confirmation, and clarifies that exactly one selector is required to prevent deleting more than intended. It adds meaningful behavior beyond the destructiveHint annotation without contradicting it.

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-organized into clear sections: Overview, Parameters, Returns, Examples, Related Tools, and Notes. Information is front-loaded and every section contributes actionable guidance 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?

With no output schema, the description compensates by describing what the tool returns. It covers why to use it, which selector to use, the deletion side effects, related tools, and an example workflow. The description is complete enough for an agent to invoke the tool correctly and safely.

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 parameter section explains each parameter's meaning, including udid which lacks a schema description. It adds the crucial 'exactly one selector required' constraint and provides concrete examples tying parameters to real usage, going well beyond the input 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 precise verb and object: 'Delete crash reports from a simulator.' The Overview further clarifies its purpose as establishing a clean test baseline, which clearly distinguishes it from sibling tools like idb-crash-list and idb-crash-show.

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 describes when to use the tool ('establishing a clean baseline before a test run'), states constraints ('exactly one selector required'), and points to idb-crash-list as the tool to inspect before deleting. The example demonstrates a complete workflow.

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 non-destructive behavior, so the bar is lower, but the description adds valuable behavioral context beyond those hints: crash reports persist across launches/reboots, simulators accumulate unrelated system crashes, unfiltered lists are mostly noise, and an empty list is a meaningful non-crash result. No contradictions with 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 long but every section earns its place: Overview, Parameters, Returns, Examples, Related Tools, and Notes. It is front-loaded with the core purpose and scoping guidance, and examples are compact and directly illustrative.

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 5-parameter optional surface, existing output schema, and rich sibling set, this description is fully sufficient. It explains return shape, filter semantics, time units, common pitfalls, and how to route to related tools. An agent can correctly select and invoke this tool without additional inference.

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%, but the description goes well beyond the schema by clarifying udid auto-detection, emphasizing Unix SECONDS for timestamps, explaining the default limit, and providing concrete example values like 'com.example.MyApp'. The 'Returns' section also explains how filters map to results, which the schema does not convey.

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: 'List crash reports on a simulator,' and immediately frames the operational purpose ('so an agent can tell a crash from a no-op'). It also distinguishes itself from related tools like idb-crash-show and idb-crash-delete, making sibling differentiation explicit.

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

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

The description gives explicit when-to-use context: it resolves ambiguity between 'tap did nothing' and 'app crashed'. It also provides exclusions and alternatives, noting that simctl-stream-logs catches non-fatal errors and hang-start catches hangs that produce no crash report. It even prescribes the scoped pattern: pass bundleId and since.

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 this as read-only and idempotent, and the description adds substantial behavioral context: it returns a summary plus cache ID instead of a huge report, explains the .ips dual-JSON format, and documents symbolication limitations. This goes well beyond what the annotations alone convey. No contradiction with 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 long but tightly organized into Overview, Parameters, Returns, Examples, Related Tools, and Notes. Each section earns its place, and the most important behavioral fact—summary plus cache ID—is front-loaded. 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?

With no output schema, the description fully documents the return content: appName, bundleId, timestamp, exception type, termination reason, top frames, cacheId, and resource link. It also includes an example call pattern and a note about unsymbolicated frames, making the tool's behavior and output interpretable without needing the schema.

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

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

Schema coverage is only 50%, but the description compensates by explaining both parameters: name is sourced from idb-crash-list with an example, and udid auto-detects when omitted. This adds practical meaning beyond the bare schema, though it does not define udid's exact format or validation rules.

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 first line states a specific action and resource: 'Fetch one crash report, summarized, with the full report available on demand.' This clearly distinguishes idb-crash-show from idb-crash-list (finding names) and other crash-related tools. The overview reinforces the tool's unique progressive-disclosure behavior.

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 establishes a clear workflow: use idb-crash-list to find crash report names, then pass one to idb-crash-show. The example concretely demonstrates this progression and the Related Tools section names idb-crash-list. It lacks an explicit 'when not to use' statement, but the context and example make the intended usage unambiguous.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable behavioral context: what is checked (CLI, companion, version floor, Xcode framework, stale registrations) and that it returns a JSON report plus remediation commands. It also explains a specific failure mode, giving the agent a clear mental model without contradicting the safe, read-only nature.

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 efficient. It front-loads the purpose, then lists checks, provides a specific usage scenario, and states the return value. Each sentence adds value without redundancy. It is concise enough to parse quickly but detailed enough to be useful.

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 zero-parameter complexity, existing annotations, and the description of the return format (JSON report plus remediation commands), the description is complete. It covers the tool's purpose, checks performed, when to use it, and expected output. No critical information is missing for an agent to decide when and how to invoke 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?

The tool has zero parameters, so the baseline is 4. The description does not need to explain any parameter details since none exist. It correctly focuses on the tool's behavior and return value 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?

The description states a specific verb and resource: 'Diagnose whether idb can drive simulator UI on this machine.' It clearly distinguishes from siblings by focusing on environment diagnostics rather than direct UI interaction (idb-ui-*) or build/install operations. The specific checks listed further clarify the scope.

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

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

The description gives explicit when-to-use guidance: 'Run this first when taps, swipes or typing appear to succeed but nothing happens on screen.' It also provides a concrete scenario (Xcode 27, idb-companion <1.5.1). However, it does not mention alternatives or explicitly state when not to use it, so it falls short of a perfect 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 idempotentHint=true and destructiveHint=false, and the description adds meaningful behavioral context: it validates app path format before transfer, auto-terminates running apps before installation, extracts bundle ID from output, and can take 10-60 seconds. It also discloses failure modes (code signing, architecture mismatch, already installed) with troubleshooting guidance. This goes beyond what annotations provide.

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 with clear sections (Overview, Parameters, Returns, Examples, Related Tools, Notes) and front-loads the core purpose. It is somewhat long, but every section earns its place by covering installation behavior, examples, and troubleshooting. The Notes section is slightly redundant with the Overview but still adds operational details.

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 2-parameter tool with no output schema, the description is quite complete: it covers input formats, target selection, return values, timing, platform constraints, and failure guidance. The only minor gap is that it doesn't describe the exact output schema or error response structure, but the prose description of returns is sufficient for an agent to invoke and interpret the result.

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 carries the full burden. It explains appPath as an absolute path to .app or .ipa, and udid as a target identifier that auto-detects if omitted. This adds real meaning beyond the bare schema properties, though it doesn't specify udid format or how auto-detection resolves ambiguity.

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 ('Install'), resource ('application to iOS target'), and the exact artifact types (.app bundles or .ipa archives). It clearly distinguishes from siblings like simctl-install and idb-launch by focusing on the transfer/registration/validation workflow.

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 for when to use this tool (deploying .app or .ipa for testing) and notes platform differences (simulators accept unsigned .app, physical devices require provisioning). It doesn't explicitly say 'use simctl-install instead for X' or list exclusions, but the Related Tools section routes to idb-list-apps, idb-launch, and idb-uninstall for adjacent steps.

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 annotations only provide boolean hintschen; the description fills in real behavioral detail: -w enables stdout/stderr streaming, absence of -w makes it fire-and-forget, process ID is extracted, and failure modes include not installed, already running, and crashed on launch. This goes well beyond the annotations and helps an agent predict side effects.

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 with a front-loaded summary, parameter table, return details, examples, related tools, and notes. It is somewhat long and has minor overlap between the Returns and Notes sections, but every section contributes meaningful information for an agent.

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, yet the description provides a thorough Returns section covering success indicator, bundle ID, process ID, streaming status, captured output, error details, and troubleshooting guidance. It also includes relevant examples and related tools, making the definition complete for a five-parameter 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 input schema has 0% description coverage, but the description explains every parameter: bundleId, udid, streamOutput, arguments, and environment. It also clarifies the environment KEY=VALUE format and demonstrates usage through examples. This fully compensates for the bare 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 the exact operation: launch an application on an iOS target by bundle ID, with optional streaming, arguments, and environment variables. It clearly distinguishes itself from related tools like idb-list-apps and idb-terminate. The verb-resource pair is specific 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?

The description provides a 'Related Tools' section and multiple examples indicating when to use simple launch, streaming, or argument passing. It does not explicitly state when to prefer idb-launch over the sibling simctl-launch or give exclusion criteria, but the intended usage contexts 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 signal readOnly and idempotent behavior. The description adds meaningful context by disclosing that output is parsed from IDB's pipe-separated text into structured JSON, that udid auto-detects when omitted, and that the result includes summary counts and separate running/installed arrays. No contradiction with 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 well-organized with clear headings, a front-loaded summary, examples, related tools, and notes. It is lengthy but mostly earns its length; there is minor redundancy between the overview and the notes section regarding pipe-separated output.

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 the description compensates with a Returns section, output format note, usage examples, and related-tool workflow context. An agent has enough information to call the tool correctly and interpret its result.

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 carries the full burden for parameters. It documents all three parameters with semantics, enum values for filterType, and the auto-detection behavior for udid. The examples also map parameter combinations to concrete agent intents.

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 installed applications' and enumerates the exact metadata returned (bundle ID, app name, install type, running status, debuggability, architecture). This clearly differentiates it from action-oriented siblings like idb-launch, idb-terminate, and idb-install.

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

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

The description gives concrete use cases: finding a test target, finding a running app for UI automation, and listing apps on a specific device. It also explains when filters are useful, but it does not explicitly state when not to use this tool or name alternatives like simctl-list.

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 this as non-read-only, non-destructive, and idempotent. The description adds important behavioral context beyond those hints: the warning is advisory, iOS may or may not terminate the app depending on footprint, and the tool records an audit entry. This effectively sets expectations about nondeterministic outcomes and side effects without contradicting any annotation.

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 with a one-line summary up front, followed by Overview, Parameters, Returns, Examples, Related Tools, and Notes. Each section earns its place: the advisory note and related-tool routing are genuinely useful, and the example shows a realistic invocation with a follow-up check.

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, the Returns section clearly describes the confirmation and audit entry structure (timestamp, action, scenario, step). The examples, related tools, and notes cover what an agent needs to invoke it correctly and interpret the result. No critical operational context 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?

With 67% schema coverage, the schema documents two of three parameters. The description compensates by explaining that udid auto-detects if omitted, that scenario is recorded in the audit entry, and that step is the step number within the scenario. This adds semantic value, especially for udid, which has no schema description.

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

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

The description opens with a specific verb and resource: 'Deliver a memory warning to a simulator, to exercise low-memory code paths.' It explains the precise iOS code paths affected (didReceiveMemoryWarning, SwiftUI cache eviction, NSCache purging), making the tool's purpose unambiguous and distinct from sibling tools like idb-crash-list.

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 overview identifies when to use the tool: to deliberately exercise low-memory code paths that are rarely tested. The Related Tools section gives clear follow-up actions: use idb-crash-list to check if the app was killed, accessibility-quality-check to verify UI survival, and simctl-stream-logs to watch memory logs. It does not state explicit 'when not to use' exclusions, but the guidance is clear enough.

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 idempotentHint=true, readOnlyHint=false, destructiveHint=false; description adds specific behavioral detail for the connect operation (persistent gRPC connection for faster subsequent calls). It does not contradict annotations and adds useful context, though it could say more about side effects of focus/disconnect. This is solid beyond what annotations provide.

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?

Well-structured with a clear overview, operation-specific sections, parameters, examples, and notes. The length is justified by the five operations; each sentence serves a purpose. Front-loaded with the overview and then detailed operations. No unnecessary verbosity.

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 multi-operation tool with no output schema, this description is thorough: includes parameter meanings, examples, return types for list and describe, behavioral notes for connect, and a related-tools section. An agent has all necessary information to invoke correctly and understand the tool's purpose in the broader toolset.

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%, but the description fully compensates: it explains each parameter (state, type, udid, operation) in the context of each operation, with examples and notes (e.g., connect auto-detects udid if omitted). This is exemplary parameter documentation.

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?

Clear, specific statement of purpose: 'Unified IDB target management - discover, inspect, focus, and manage connections.' It lists concrete operations and distinguishes from sibling tools by being the unified IDB target tool, not just a generic list or control tool.

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

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

Provides clear context that this is the unified tool for IDB target management, covering all operations. It does not explicitly contrast with simctl or other alternatives, but its role is evident from the description and the operation set. Not fully explicit on exclusions, hence 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?

Annotations provide idempotentHint=true and readOnlyHint=false, and the description adds substantial behavioral detail beyond that: it is a force-kill with no graceful shutdown, succeeds even when the app is not running, reports a wasRunning flag parsed from output, and is safe to call multiple times. No contradiction with annotations exists.

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 longer than average but well-structured with Overview, Parameters, Returns, Examples, Related Tools, and Notes. Core information is front-loaded and each section adds value, though there is minor redundancy about idempotency and wasRunning appearing in multiple sections.

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 explains return fields (success indicator, bundle ID, wasRunning flag, command output, error details, next steps guidance). It also provides two realistic examples and enough behavioral context for an agent to call the tool correctly. Nothing critical is missing.

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

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

The input schema has 0% description coverage, so the description must compensate. It does: bundleId is defined as "App bundle identifier to terminate" and udid as "Target identifier - auto-detects if omitted." The meaning is clear, though udid could be more explicitly described as a device identifier.

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: "Force-terminates running applications by bundle ID with immediate stop." It clearly positions the tool as a force-quit operation distinct from idb-launch, idb-uninstall, and idb-list-apps, and the Related Tools section reinforces how it fits among 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?

The description gives clear context for when to use it: "resetting app state between test runs and preparing for reinstallation." It also names related tools (idb-launch, idb-list-apps, idb-uninstall) that may be used before or after. It does not explicitly say when not to use it, but the use-case guidance is strong enough.

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 set readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these: it mentions caching large outputs to prevent token overflow, progressive disclosure, NDJSON parsing, and data quality assessment. It also explains the filtering behavior and when to escalate, which is not present in annotations. No contradiction.

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 long but well-structured with clear sections (What it does, Why you'd use it, Parameters, Returns, Examples, Related Tools) and effectively front-loaded. Every sentence contributes necessary information for a tool of this complexity. The examples are concise and illustrate key usage patterns.

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 must explain return values, and it does thoroughly for both operations. It covers all parameters, return structure, progressive filtering, and even includes code examples. It also relates to sibling tools, completing the decision-making context. Nothing an agent needs 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 has zero descriptions and parameter coverage is 0%, so the description carries the full burden. It meticulously explains each parameter: operation enum, x/y coordinates, udid auto-detection, screenContext, purposeDescription, and filterLevel (even though filterLevel is missing from the schema, the description documents it thoroughly with four levels and defaults). It adds meaning far beyond what the bare 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 states a precise verb ('query UI accessibility tree') and resource (iOS UI elements), and explicitly distinguishes itself from siblings like idb-ui-tap and idb-ui-find-element. It clearly defines what it does: discover tappable elements, text fields, and coordinates. No ambiguity.

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 'Why you'd use it' section provides concrete scenarios, and the 'Related Tools' section names alternatives with their purposes. It gives explicit fallback guidance (e.g., 'if minimal data, fall back to screenshots') and a progressive filter escalation pattern, leaving no doubt about when to use this tool versus others.

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), and the description enriches this with concrete behavior: case-insensitive partial matching, returning all matches, filtering out elements without valid frames, empty array on no match, and performance data (~80ms vs 2000ms for screenshots). No contradiction with annotations; these details add real decision value.

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?

Well-organized with clear headers and purpose front-loaded, but verbose: the three TypeScript examples are nearly identical (only the query string differs), and the how-it-works/notes sections repeat the same facts about case-insensitivity and ~80ms latency. Trimming redundant examples would tighten it without losing 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?

Despite lacking an output schema, the description explains the return shape (type, label, identifier, centerX/centerY, frame boundaries) and empty-array behavior. It covers parameters, examples, workflow, performance, and related tools — 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 0%, so the description carries the full burden, and it delivers: query is explained as a search term matched case-insensitively against labels/identifiers, and udid as auto-detecting when omitted. Examples demonstrate realistic usage for each parameter, fully compensating for the empty 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 opening line 'Find UI elements by semantic search in accessibility tree - no screenshots needed' states a specific verb, resource, and method. It distinguishes itself from siblings like idb-ui-describe (full tree) and screenshot (visual), making tool selection 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?

The Related Tools section explicitly names alternatives and their purposes, including 'screenshot: Visual fallback if accessibility insufficient', which gives an implicit when-not condition. The description also frames this as the fast, cheap option versus visual analysis. Guidance is clear but selection criteria are mostly implicit rather than stated as explicit if-then rules.

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 indicate non-read-only, non-destructive, and non-idempotent behavior, which is minimal. The description adds that velocity is validated and coordinates are checked against device bounds, but it does not clearly disclose side effects (e.g., launching gestures actually changes UI states) or limitations beyond what the annotations imply. With annotations providing little content, the description should carry more weight, and it does not fully disclose the real-world impact.

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 with headings and tables but is progressively verbose. 'Complete JSON Examples' and the later 'Examples' section repeat nearly the same information in different syntax, and some sections (like full JSON examples for every button type) are redundant. Each piece has value, but the description could be tightened without losing clarity.

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 has 11 parameters and no output schema, yet the description covers all parameter meanings, coordinates, profiles, return contents, and provides error examples. It matches the tool's complexity well. The only gap is the lack of more precise output format descriptions, but since no output schema exists, the returned description is reasonable.

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 9%, so the description this must compensate. It does so admirably: it details the operation parameter, defines profile values and their measured speeds, explains coordinate space (POINT vs PIXEL), gives defaults for duration, and lists button types. Extensive examples illustrate how parameters combine, which goes far 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 clearly states the tool performs swipe gestures and hardware button presses on iOS targets, using specific verbs and resources. It differentiates itself from sibling tools by naming related tools like idb-ui-tap and idb-ui-describe, making its unique purpose clear.

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 'Why you'd use it' section provides specific scenarios, and 'Related Tools' names alternatives for tapping and describing elements. However, it does not explicitly state when not to use this tool or provide exclusion criteria, so it stops short of full when-to-use guidance.

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

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

With no helpful annotations (all hints false), the description carries the full burden. It discloses that it sends input, redacts sensitive data, tracks semantic context, and returns error details with troubleshooting. It does not contradict annotations and adds meaningful behavioral context, though some specifics about UI side effects are omitted.

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 long but well-structured with clear sections (What it does, Why you'd use it, Parameters, Returns, Examples, Related Tools). It is front-loaded with the core purpose and uses examples to illustrate usage. While verbose, it is appropriately detailed for a tool with 9 parameters and 3 operation modes, so it doesn't waste 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?

Given the tool's complexity (no output schema, 9 params, 3 operation types), the description covers everything an agent needs: parameter semantics, operation-specific requirements, return behavior, error handling, and related tools. It is complete for correct invocation without requiring additional lookups.

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 0%, so the description must explain every parameter. It does so thoroughly: operation lists the enum and which parameters are required per operation, and optional parameters like actionName, fieldContext, expectedOutcome, and isSensitive are described with examples. This fully compensates for the schema's lack of descriptions.

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 explicitly states it sends text and key input to focused elements on iOS targets, with a clear definition of operations (text, key, key-sequence). It distinguishes from sibling tools by mentioning idb-ui-tap for focusing fields and idb-ui-describe for finding coordinates, which differentiates its 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?

It provides a 'Why you'd use it' section listing concrete scenarios like form filling and keyboard shortcuts, and a 'Related Tools' section explicitly naming alternatives and their roles (e.g., idb-ui-tap as a prerequisite to focus fields). This gives clear when-to-use and when-not-to-use 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 useful behavioral context beyond the annotations: automatic screenshot-to-device coordinate transformation, coordinate bounds validation, support for simulators and physical devices over USB/Wi-Fi, and semantic action tracking. While annotations already indicate non-read-only, non-idempotent behavior, the description enriches the agent's understanding with actionable details about input validation and transformation. It could mention a requirement like a booted target, but that is a minor 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?

The description is well-structured with clear headings, bullet lists, and an example that aids comprehension. It is somewhat long and the opening 'What it does' slightly restates the title and the header line, but given 13 parameters and 0% schema coverage, the length is justified.

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 13-parameter tool with no output schema and no schema parameter descriptions, the description carries the entire burden and succeeds. It covers all parameters, return behavior, an example, and relationships with other tools. An agent can invoke this tool correctly with no gaps in meaning.

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%, yet the description compensates thoroughly. It explains each parameter's meaning beyond its type: x/y coordinate space with applyScreenshotScale, UDID auto-detection when omitted, duration for long press, and the semantic metadata fields (actionName, expectedOutcome, etc.). This is exactly the value the description is expected to add.

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 immediately states a specific action and resource: 'Sends precise tap events to iOS targets at specified screen coordinates.' It clearly differentiates this tool from related siblings like idb-ui-gesture (swipes/hardware buttons) and idb-ui-describe (discovering tappable elements), leaving no ambiguity about what it 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 'Why you'd use it' section provides clear use cases such as tapping elements identified in screenshots, transforming coordinates automatically, validating bounds, and tracking test metadata. The 'Related Tools' section also names alternatives with their roles, which helps agents choose the right tool. However, it lacks explicit 'when not to use' guidance beyond those brief sibling descriptions.

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=true. The description adds valuable behavioral context: complete data and preferences deletion, automatic termination of running apps, system app protection, and error guidance. This goes beyond what annotations provide, though it doesn't detail permission requirements or exact response format.

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 with clear sections (Overview, Parameters, Returns, Examples, Related Tools, Notes) and front-loads the core purpose. It's somewhat verbose with repeated information across Overview and Notes, but each section earns its place and the examples are useful.

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 2-parameter tool with no output schema, the description covers the essential context: what it does, parameters, return information, examples, and related tools. It could be more explicit about edge cases like invalid bundle IDs or device connection failures, but the error guidance mention covers common failures.

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 explains bundleId as the app bundle identifier to uninstall and udid as target identifier with auto-detection. This adds meaning beyond the bare schema, but the descriptions are minimal and don't provide format examples or constraints beyond what a developer would infer.

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 uninstalls applications from iOS targets by bundle ID with complete data deletion, distinguishing it from related tools like idb-install and simctl-uninstall. The verb 'uninstall' plus resource 'application from iOS target' is specific 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?

The description provides clear context for when to use the tool (clean installs, removing user-installed apps) and notes that idb-terminate is auto-handled, idb-install is for reinstall, and idb-list-apps verifies removal. It doesn't explicitly state when NOT to use it versus simctl-uninstall, but the related tools section gives useful routing 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds useful context beyond them: it does not build anything, operates on already-installed bundles, parses both JSON and plain lines, preserves unrecognized raw text, and treats an empty list as normal. This equips the agent with behavior 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?

The description is well-organized with Overview, Parameters, Returns, Examples, Related Tools, and Notes, with the core purpose front-loaded. It is longer than minimal but each section serves a purpose; minor redundancy exists in the empty-result expectation appearing in both Returns and Notes.

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 without an output schema, the description explains the return shape (bundles or tests plus a count), normal empty results, prerequisites, and behavioral resilience across idb versions. With examples and sibling routing, an agent has everything needed to decide when to invoke it and what to expect.

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 only 50% schema description coverage, the description compensates by explaining both parameters: udid auto-detects if omitted and testBundleId switches the tool to listing tests inside a bundle. The example using a realistic bundle ID adds concrete usage semantics 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: 'List xctest bundles installed on a target, or the tests inside one.' It explicitly distinguishes itself from xcodebuild-test with 'This is NOT a replacement' and from idb-list-apps in Related Tools. An agent can immediately understand the tool's scope and boundaries.

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

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

Provides explicit when-to-use guidance: discover installed bundles before running tests or confirm an install succeeded. It names the alternative xcodebuild-test for building/running tests and lists related tools like idb-install and idb-list-apps. No ambiguity about when this tool should be selected.

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 the tool as readOnly, idempotent, and non-destructive, and the description reinforces this with 'Pure file analysis — no simulator required.' It also adds meaningful behavioral detail such as strict mode setting isError:true and placeholder mismatch handling skipping empty-value locales.

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 long but well-structured and front-loaded with a one-line summary, followed by sections for behavior, parameters, formats, returns, examples, gap reasons, and placeholder matching. It is somewhat detailed, but most sections earn their place given the complexity of the audit output.

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

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

For a 4-parameter tool with sparse schema, the description covers input semantics, supported file formats, output JSON fields, gap reason meanings, placeholder-matching rules, and complete usage examples. This is sufficient for an agent to select and invoke the tool correctly without external documentation.

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%, but the Parameters section documents all four parameters with types, requiredness, and plain-language meaning, such as catalogPath being 'Path to .xcstrings, .strings, or .stringsdict catalog file' and strict setting isError:true when findings are present. The examples further clarify how catalogPath, sourceDir, strict, and verbose are used together.

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: 'Audit .xcstrings, .strings, or .stringsdict catalogs for localization gaps, placeholder mismatches, and unused or missing keys relative to Swift source code.' This is precise enough for an agent to distinguish it from unrelated siblings such as accessibility-audit or visual-diff.

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

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

The description gives clear context by noting 'Pure file analysis — no simulator required' and enumerating supported catalog formats and example invocations. It does not explicitly name alternatives or when-not-to-use conditions, but no sibling tool provides the same localization-catalog audit function.

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 claim destructiveHint=false and idempotentHint=true, but the description states that clearData=true deletes existing cache files and that the operation is immediate and irreversible. Deleting cache files is a destructive behavior, so the description contradicts the destructiveHint annotation. This conflict undermines the safety profile an agent would rely on.

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 with front-loaded summary, parameters, returns, related tools, and notes. It is longer than strictly necessary—the Advantages section and some Notes repeat the default behavior—but each section is scannable and adds either context or usage guidance.

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 one-parameter tool with no output schema, it covers inputs, return information, related tools, and operational consequences (state loss on restart, irreversibility). It doesn't mention prerequisites or when not to use it, but the included information is sufficient 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 coverage is 0%, and the description fully compensates: it documents the sole optional clearData parameter, its boolean type, its meaning ('delete existing cache files when disabling'), and its default of false. The Notes reinforce the default and the effect of setting clearData to true.

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 first line uses a specific verb and resource: 'Disable persistent state management and return to in-memory-only caching.' It clearly distinguishes itself from siblings by naming persistence-enable and persistence-status, and by describing what happens after disabling. An agent can tell exactly what this tool does 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 concrete use cases (privacy, disk space, CI/CD, troubleshooting stale caches) and lists related tools persistence-enable and persistence-status. It lacks an explicit 'when not to use' or a precondition such as checking persistence-status first, so it doesn't reach 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 mark the tool as non-read-only and idempotent; the description adds meaningful behavior by specifying what is persisted (usage patterns, build preferences, simulator metrics, cached responses) and what is never persisted (source code, credentials, personal information). It also discloses automatic cache-location selection and auto-registration with the MCP server, adding context beyond 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?

The document is organized under headings and front-loads the core purpose, making it scannable. However, it repeats the privacy point and the automatic-location behavior across sections, and the Advantages list is largely promotional rather than necessary for invoking the tool.

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 one optional parameter and no output schema, the description is operationally complete: it explains the results (activation confirmation, resolved cache directory, storage writability, privacy notice, next steps) and lists related tools. No critical invocation detail 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?

The input schema provides zero description coverage and only a bare 'cacheDir' string property. The description compensates fully: 'cacheDir (string): Custom directory for cache storage. If omitted, uses intelligent location selection.' This tells the agent the parameter is optional and what happens when it is absent.

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 by saying the tool 'Enable[s] opt-in persistent state management for learning across server restarts' and 'Activates file-based persistence' for XC-MCP's caching systems. It names a specific action on a specific resource, and the Related Tools section distinguishes it from persistence-disable and persistence-status.

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 frames the tool as the opt-in activation path for persistence and lists concrete contexts where it is beneficial: retaining learned configurations, accelerating repeated workflows, team collaboration, and CI/CD runs. It names related tools for disabling and checking status, but it does not explicitly say when not to use this tool or directly compare selection criteria.

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, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds useful behavioral context beyond that: what data is returned (storage metrics, last save times, recommendations), the lightweight check behavior when includeStorageInfo is false, and a note that it is auto-registered. This adds value without contradicting 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 well-structured with markdown sections (Advantages, Parameters, Returns, Notes), but it is verbose for a tool with a single optional parameter. There is redundancy: the main paragraph, Advantages bullet, and Returns section all repeat similar information (disk usage, timestamps, recommendations). It could be tightened without losing clarity, though the front-loaded summary helps.

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 has only one optional parameter and no output schema, the description is thorough: it explains what the tool returns (Returns section), parameter behavior, related tools, and practical notes (e.g., lightweight check, regular monitoring). Everything an agent needs to call it correctly and interpret the result 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?

The schema has no property descriptions (0% coverage), but the description fully explains the only parameter: 'includeStorageInfo (boolean): Whether to include detailed disk usage and file information. Defaults to true.' It also gives usage guidance in Notes ('Set includeStorageInfo: false for lightweight check'). This completely 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 clearly states it 'Provides detailed information about the persistence system's current state' and enumerates the specific data returned (enabled state, cache directory, disk usage, file counts, timestamps, recommendations). This specific verb+resource combination clearly distinguishes it from sibling tools like persistence-enable and persistence-disable, which perform actions rather than status queries.

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 'Related Tools' section names persistence-enable and persistence-disable as alternatives, implicitly indicating when to use this status tool vs. those. The 'Advantages' list further clarifies usage contexts (monitoring disk usage, verifying persistence, troubleshooting). It does not explicitly state 'when not to use' but provides enough contextual guidance to route an 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: fuzzy matching for removed router names, case-sensitivity, the 'tool not found' response format with suggestions, and the fact that documentation is embedded as TypeScript constants bundled into the compiled JavaScript. It also explains the v4.0 migration from routers to discrete tools, which is important context for agents that might try to call removed router names.

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 comprehensive but very long, covering version history, implementation details, migration notes, and benefits. While all information is relevant, the version history and implementation details (TypeScript constants, central registry) are more relevant to developers than to an AI agent deciding whether to call the tool. The most actionable information (parameters, examples, response format) is present but buried under extensive context.

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 documentation-lookup tool with no output schema, the description is remarkably complete. It covers parameters, examples, response formats (both success and error), fuzzy matching behavior, category listings, and common use cases. An agent has everything it needs to call this tool correctly and interpret the response.

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 0%, so the description carries the full burden of parameter documentation. It does this well: toolName and categoryName are both explained with examples, case-sensitivity is noted, and the behavior of omitting both parameters is described. The only minor gap is that it doesn't explicitly state whether toolName and categoryName can be combined or are mutually exclusive.

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 identifies rtfm as a documentation lookup tool with a specific verb ('Read The Manual') and resource (tool documentation). It distinguishes itself from sibling tools by explaining it provides progressive disclosure documentation for all other tools, not performing any device/simulator operation.

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

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

The description explicitly explains when to use rtfm: when you need full parameters, examples, and related tools after seeing a one-liner description. It also explains the progressive disclosure pattern and how to browse by category or tool name, with examples of both valid and intentionally-invalid calls.

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