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

Goes far beyond the destructiveHint/readOnly annotations by disclosing environment sourcing (MSVC env, IDF env), auto-fullclean when new apps are detected, refusal behavior when no board revision is known, build-dir wiping for clean mode, and STM preset mapping (RelWithDebInfo→Release). The destructive actions described ('wipes build dir', 'runs idf.py fullclean') align with destructiveHint=true — 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?

Front-loaded with the purpose line, then organizes per-platform behavior in bullets and mode compatibility in a compact table. Every sentence carries distinct information — build system choice, preference rationale, output path, or mode constraint. No filler, despite covering a complex 3-platform × 4-mode matrix.

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 3 platforms × 4 modes plus board-revision and build-type logic, the description covers all decision axes: which commands run, which flags are passed, when builds are refused, what gets wiped, and where output lands. Return values are covered by the existing output schema, and environment prerequisites are discoverable via siblings (crosspad_doctor, crosspad_toolsets). 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 coverage is 100%, so the schema already documents all four parameters, setting a baseline of 3. The description adds value on top: concrete flags passed for IDF (-B build_<rev> -DSDKCONFIG=sdkconfig.<rev>), board revision resolution via tools/crosspad_board.py, and the exact STM output path (build/<preset>/CrossPad_STM32_r20.elf). These enrich platform, board, and build_type semantics beyond what the schema alone 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?

Opens with an explicit verb+resource statement — 'Build CrossPad for the given platform' — then disambiguates three platform targets (pc/idf/stm), each with its own build system (CMake+Ninja, idf.py, arm-none-eabi). This clearly differentiates it from build-adjacent siblings like crosspad_flash and crosspad_repo_status. No ambiguity about what the tool does.

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

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

Explicitly states 'PREFER THIS over `cmake --build build`' and 'PREFER THIS over raw `idf.py build`' with concrete reasons (correct MSVC env, error parsing, progress streaming, env sourcing). The Mode×platform compatibility table tells the agent exactly which modes work on which platforms and when to pick each (incremental for normal iteration, fullclean after adding apps, reconfigure after editing CMakeLists). This is textbook when/when-not guidance with named alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds genuine behavioral context beyond this: the data source (crosspad-hil daemon), the stability guarantee of id (stable per USB serial), version-dependent meaning of kind, and the selection rule for 'selected.' Minor gap: no disclosure of behavior when the daemon is not running or no devices are attached.

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

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

The description is front-loaded with the core purpose and each clause earns its place by explaining a field or a constraint. It is dense — the port-role enumeration and version-conditional kind explanation are packed tightly — but for a tool with no schema params and a field-semantics burden, this level of detail is warranted rather than padded.

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 low complexity (0 params), complete annotations, and an output schema that presumably details the return structure, the description covers the semantic meaning an agent cannot extract from structured data: id stability, kind version semantics, and the implicit-selection rule. The remaining gap is edge-case behavior (daemon unavailable, empty device list), which is minor for a read-only enumeration 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?

With zero parameters and 100% schema coverage, there is nothing for the description to explain about inputs, so the baseline of 4 applies. The description instead adds value on the output side by clarifying field semantics (usb_mode value set, port role glosses, kind version mapping), which compensates for the empty 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 specific verb+resource+source: 'List connected CrossPads as seen by the crosspad-hil daemon.' It enumerates the exact fields returned (id, usb_mode, port roles, kind, selected) with their semantics, and its function is clearly distinct from all siblings (build, flash, doctor, snapshot, etc.), which perform actions rather than enumerate hardware.

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

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

Usage context is only implied, not stated. The 'selected' field explanation hints that other tools implicitly choose a device and this tool reveals which one, which lets an agent infer when to call it (before acting on a device), but there is no explicit when-to-use/when-not-to-use statement or routing to alternatives. The differentiation from siblings is conveyed by function rather than by explicit 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 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?

Goes far beyond annotations: discloses the danger tier, preflight always running, confirmation requirement, refusal rules, revision mismatch blocking, and job mechanics. It explains what force does and does not override, and the difference between wait_seconds modes. 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 each sentence carries essential information. It is front-loaded with the danger warning and preflight summary, then organized by target and parameter groups. No fluff; every detail is actionable.

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 tool with 15 parameters, the description covers all critical aspects: preflight checks, transport/method selection, job handling, confirmation token flow, force/dry_run semantics, and board revision implications. The output schema (BootResult) is not described but exists, so no need to repeat. 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?

While the schema already documents every parameter (100% coverage), the description adds significant semantic depth: it explains the preflight checks, the meaning of confirm_token flow, the behavior of wait_seconds=0 vs >0, default paths for firmware, and the board-revision blocking logic. This enriches the schema descriptions substantially.

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 'Flash firmware' with clear scope for ESP and STM targets. It distinguishes itself from siblings by detailing the preflight, confirmation, and job-based execution, making its unique role obvious.

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: it explains when to use each transport/method, what is refused (STM32 bridge console), how to handle confirmation, and when to use dry_run or force. It references crosspad_task for polling, giving clear 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?

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.