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

Annotations declare destructiveHint=true, and the description reinforces this with specific behavior: clean 'wipes build dir', fullclean 'runs idf.py fullclean', and notes auto-fullcleans when new apps detected. It discloses build-type restrictions (build_type ignored for IDF, only honored on clean|reconfigure). The description goes beyond annotations by explaining exactly what gets destroyed and when, though it doesn't mention whether the destructive behavior is reversible or if there are additional 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 platform bullets, a clear mode×platform compatibility matrix, and front-loaded purpose in the opening line. Every sentence earns its place — platform mappings, preference rationale, mode compatibility, and output conventions are all packed efficiently without padding. Uses bold for emphasis on precedence ('PREFFER THIS') and clear visual structure with bullets.

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?

This is a complex tool (3 platforms × 4 modes × build_type interactions) with an output schema. The description fully covers platform behavior, mode compatibility, the tricky build_type/IDF/sdkconfig nuance, CMakePresets for STM, and output artifact locations. With the output schema providing return structure and annotations covering destructiveness, the description is complete for agent decision-making and 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 100%, but the description still adds meaningful value. It explains the mode compatibility matrix in the body, provides the output artifact path for STM, documents that build_type maps RelWithDebInfo→Release for STM, and explains IDF ignores build_type (comes from sdkconfig). The description supplements rather than duplicates the schema's parameter 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 clearly states the tool builds CrossPad for a given platform with specific verbs per platform ('CMake + Ninja host simulator', 'idf.py build for ESP32-S3', 'CMake + Ninja + arm-none-eabi for STM32G0'). It specifies the exact output artifact (build/<preset>/CrossPad_STM32_r20.elf), and the platform×mode compatibility matrix distinguishes it from siblings like crosspad_flash, crosspad_run, and crosspad_check.

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 PREFER THIS guidance over raw commands (cmake --build, idf.py build) with justification (picks MSVC env, sources IDF env, parses errors). The mode×platform compatibility matrix explicitly states which modes work on which platforms, and mode usage rationale is given ('fullclean after adding new apps, reconfigure after editing CMakeLists/presets'). This is exemplary usage 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, and the description agrees with all of them. It adds meaningful behavioral context beyond annotations: data source (crosspad-hil daemon), stable ID semantics, usb_mode values, port role meanings, the v9 `kind` compatibility meaning, and the implicit device selection rule. There is 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 dense but every sentence adds value: it states the purpose, defines the output fields, explains value ranges, and clarifies the special `selected` and `kind` semantics. There is no filler or repetition of schema contents.

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 that an output schema exists and there are no parameters, the description sufficiently covers invocation semantics, output field interpretation, and device-selection behavior. It provides all context an agent needs to use this tool correctly and interpret its results.

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 input schema is empty, so there is no parameter burden for the description to carry. The baseline for a zero-parameter tool is 4, and the description correctly focuses on output semantics rather than inventing parameter information.

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: 'List connected CrossPads as seen by the crosspad-hil daemon.' It enumerates the returned fields and possible values, making the tool's function unmistakable. This clearly distinguishes it from sibling build/flash/repo tools that perform actions rather than listing devices.

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

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

The description explains that `selected` is set when exactly one device would be chosen implicitly by every other tool, which tells the agent this tool is the way to discover which device other crosspad commands will target. It does not explicitly say 'use this before crosspad_flash' or name alternatives, but the guidance is clear enough for device-selection decisions.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description discloses `action=restart_daemon` that stops and starts the daemon and, per the schema, drops open console/cdc handles. That is state-changing and handle-destroying behavior, directly contradicting the read-only/destructive-free annotations. Per the rubric an annotation contradiction scores 1.

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

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

The description is dense but purposeful: it leads with the role, organizes host vs daemon checks, specifies output shape, and ends with actionable usage guidance. It could be better structured with bullets, but every sentence carries useful information with no filler.

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

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

For a tool this complex, the description covers the check categories, the `{name, ok, detail, fix}` result shape, the all-or-nothing ok semantics, the trigger for using the tool, and the restart action's consequences. The rich output schema and 100% parameter scchema coverage fill any remaining need.

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?

Input schema covers both parameters 100%: `action` has an enum with detailed semantics and `confirm_token` is explained as echoing the token from a confirmation_required reply. The tool description reinforces `restart_daemon` but adds no parameter meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly identifies crosspad_doctor as an environment diagnostic: it enumerates host checks (hil interpreter, versions, ESP-IDF, platform-idf root, build dirs, firmware age, simulator), daemon checks (udev/dialout, port locks, audio visibility), and daemon process reporting. 'Run this first when a device tool errors' also gives it a distinct role next to build/flash/devices 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 explicitly says to run this first when a device tool errors, and explains exactly when action=restart_dae `restart_daemon` is appropriate: after installing crosspad-hil or adding a scenario, or when the daemon accumulated OS resources. It lacks an explicit when-not or named alternatives, so not 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?

The description discloses far beyond the annotations: a preflight always runs and is always returned (refusal included), confirmation is mandatory before any write, board-revision mismatch is a hard blocker because the wrong image 'looks like dead hardware', and the port-role refusal is never overridable. It also reveals job semantics (wait_seconds=0 returns a task handle; a timeout is not an error) and wait_boot returning a BootResult, none of which the annotations 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 dense but logically ordered: danger tier first, then preflight details, then ESP specifics, then STM specifics, then job semantics — with the safety-critical 'needs a confirmation before writing anything' front-loaded. It runs long, but with 15 parameters and two hardware targets every sentence earns its place; light structural breaks would make it exemplary.

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 the most complex and dangerous tool in the set (15 params, destructiveHint=true, no required params), the description covers the complete lifecycle: preflight, confirmation, per-target transports and methods, blocker override semantics, async job polling, and boot verification. The presence of an output schema means return values need no further elaboration. Nothing an agent needs to safely invoke this tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description genuinely adds cross-parameter meaning: it ties force, dry_run, and confirm_token into the preflight/confirmation lifecycle, scopes delta_base to ESP OTA-only, and explains the wait_seconds-to-crosspad_task coupling. The preflight paragraph gives force and dry_run behavioral weight the schema alone cannot.

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

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

Opens with '[ESP HW | STM HW] Flash firmware' — a specific verb and resource that names both hardware targets. The scope is unambiguous and the sibling tools (build, repo_status, devices, doctor, snapshot, toolsets, task) are clearly distinct: this is the only one that writes firmware.

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

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

The description explains the full invocation lifecycle: a preflight always runs and returns a confirmation_required result, the identical call is re-issued with confirm_token to proceed, dry_run stops after preflight, and force overrides blockers. It also routes async polling to crosspad_task. What's absent is an explicit 'when not to use this tool' statement, though the siblings are different enough in purpose that this is a minor gap.

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 readOnlyHint=true annotation already covers the safety profile. The description adds value by disclosing the scope (ALL detected repos), the monorepo layout detail (5-repo), and what the reported fields are. It correctly presents this as an aggregation tool without overclaiming write behavior.

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

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

Two sentences, tightly packed. The key main-verb action and scope are front-loaded. Could arguably be a touch shorter but every sentence earns its place—the first establishes the action, the second gives the preference directive.

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

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

Given an output schema exists (which covers return values), zero params, and a readOnly annotation, the description covers what an agent needs: what it does, what it returns conceptually, and when to prefer it. The monorepo layout context is valuable. Minor gap is not describing submodule sync state semantics more precisely.

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 there's no parameter description to add. The baseline for 0 params is 4, and the description appropriately focuses on behavior since schema has nothing to document at 100% coverage.

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 verb+resource: reports git status across all CrossPad repos. Explicitly enumerates what's returned (branch, HEAD, dirty files, submodule sync state) and differentiates from alternatives by highlighting the 5-repo monorepo layout handling in one call.

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

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

Explicitly instructs to PREFER this tool over running `git status` per repo, providing an explicit when-to-use directive and naming the alternative it replaces. This is a clear usage guideline with a specific alternative context.

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

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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds meaningful behavior: refs are ENC_GROUP indices invalidated by UI actions, next snapshot re-mints them, diff_from appends changed, unknown diff id falls back to full snapshot, and sim mode nulls ui. This goes well 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 dense but tightly organized: snapshot contents first, then the subtle ref invalidation warning, then the two optional modifiers. Every clause earns its place and important caveats are front-loaded before parameter 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 read-only snapshot tool with an output schema, the description is complete: it covers all parameters, edge cases (unknown diff_from, sim-specific ui null), device selection defaults, and behavioral invariants around refs. No meaningful gap remains for an agent 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?

The schema covers 100% of parameters, and the description enriches each one: include sections map to 'fewer CDC round-trips', target=sim maps simulator stats and nulls ui, diff_from adds changed and handles unknown ids, and device omission is valid when only one CrossPad is connected.

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 'One-call state snapshot' and enumerates the exact sections returned (apps, ui, kit, leds, pads, mem, ble, console), making the tool's verb and resource unmistakable. It also distinguishes the hardware and simulator modes, so it is not confused with sibling build/flash/task 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 gives strong usage context: device or sim selection, default behavior, optional include filtering, and diff_from semantics. It does not explicitly name sibling tools or state when not to use the snapshot, but the tool is clearly a read-only introspection utility and the guidance is otherwise concrete.

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 readOnlyHint=true and destructiveHint=false, yet the description documents a 'cancel' action that stops a running task — a state-changing operation. This is a direct contradiction between the description and annotations, so the transparency score must be very low.

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

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

Two sentences, front-loaded with the action verbs and supported task types. Every sentence carries information, and there is no filler or repetition of the schema.

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

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

The description covers the full action surface, the task handle format, result retention, and the client-capability condition, while the output schema handles return shape. It is nearly complete, though the annotation contradiction undermines overall reliability.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds the task_<n> handle pattern and the 1 h retention window, but those facts already appear in the schema defail. No meaningful extra parameter semantics are provided 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 opens with a specific verb set ('Poll, wait on, cancel or list') tied to a concrete resource ('long-running crosspad tasks') and enumerates the task types it manages. It is clearly distinct from sibling tools like crosspad_build or crosspad_flash, which create tasks rather than manage them.

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

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

The description explicitly states when to use the tool: when the client does not support the MCP tasks capability. It does not spell out exclusions or alternative sibling tools, but the clear context is enough for an agent to route 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?

The description discloses useful behavior such as emitting tools/list_changed and excluding tools hidden by a readonly policy, but it directly contradicts the readOnlyHint=true annotation by describing mutating enable/disable actions and a change event. Per the rubric, a description that contraindicates annotations earns a 1.

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 and front-loaded, with the purpose in the first sentence and essential operational rules packed into two sentences. Every clause adds value, with no meaningless filler.

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

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

The description covers initial state, all actions, constraints, side-effect guidance, and the readonly policy, which is very complete for an agent invoking the tool. It loses a point because the readOnlyHint annotation conflict leaves the agent uncertain whether calling the tool is truly side-effect-free.

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?

Despite the schema describing both parameters, the description adds meaning well beyond the enum and names: list shows enabled state, enable/disable pair with toolset, core cannot be disabled, describe returns safety tiers, and the valid toolsets are enumerated. This gives the agent actionable semantics for both parameters.

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

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

The description opens with a specific verb and resource ('Manage which crosspad_* toolsets are visible') and then lists the exact actions and toolsets, making its purpose unambiguous. It clearly distinguishes itself from the crosspad_* sibling tools, which are build, repo, device, doctor, and task operations rather than toolset visibility management.

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

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

It states when to use each action (list, enable, disable, describe), the initial state (only core on), and the constraint that core cannot be disabled. It does not explicitly name alternatives or when-non to use this tool, but no sibling tool overlaps this toolset-visibility role, so 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.