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

Annotations already establish that this is a safe, read-only, closed-world operation. The description adds valuable behavioral context beyond annotations: it reports live unsaved state and fails fast with a structured error when KiCad is unreachable or no board is open. It stops short of describing the error structure or all possible failure modes.

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

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

The description is a single dense sentence with the core purpose front-loaded, followed by the exact output fields and failure behavior. Every clause earns its place because there is no output schema, making the return-value enumeration necessary rather than redundant.

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 listing the fields returned and explaining the fail-fast error behavior. Together with annotations covering safety, this gives an agent everything needed to decide to call it and understand what it returns.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain. The baseline for zero parameters is 4, and the description appropriately focuses on output content 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 uses a specific verb ('Summarize') and resource ('the board open in KiCad's PCB editor') and enumerates exactly what is returned: path, title block, layer counts, entity counts, outline size, and dirty state. This level of specificity clearly distinguishes it from siblings like session_status or get_selection.

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 implies usage by emphasizing that the summary is live and includes unsaved changes, which helps an agent understand when the data reflects the editor rather than disk. However, it does not explicitly name alternatives such as sync_from_disk or session_status, nor does it state when not to use this tool.

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

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

Beyond the readOnlyHint annotation, the description discloses substantive behavior: non-file items get session-scoped ids with no_file_reference: true, undescribed items are counted and never silently dropped, bbox is reported in mm in the file frame with a board-frame offset, and an empty selection is not an error. These are exactly the traits an agent cannot infer from the structured fields.

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

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

Front-loaded with the core action, then a dense enumeration of return categories, then the filter notes. It is a single long paragraph, but nearly every clause carries distinct information; only the kind enumeration is heavier than strictly necessary.

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 must describe the return shape, and it does: reference designators, 'REF.PAD' strings, net sets, session ids, and mm bbox with frame offset. Combined with the empty-result and undocumented-item notes, an agent has enough to call and interpret results correctly.

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

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

Schema description coverage is 0%, so the description carries the burden and largely does: it gives an example kinds value ('footprint', 'pad') and explains that include_geometry adds per-item positions and boxes. Minor gap in not enumerating the full set of valid kinds strings or clarifying filter behavior for unknown kinds.

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 ('Read what is selected in KiCad's PCB editor') and enumerates the exact categories returned (footprints, pads, nets, nets_of_footprints, other, undescribed, bbox). No sibling tool (session_status, board_summary) could be confused with this targeted selection read.

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 is implied rather than stated: 'live' reads plus 'references that kct commands accept' hint at when it is appropriate, and 'An empty selection is an ordinary empty result' pre-empts a common misread. However, it never names an alternative or an explicit when-not condition relative to siblings like board_summary or show_findings.

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 flag destructiveHint=true, but the description adds real operational context beyond them: the reload refuses with document_dirty when an edit races the command and nothing is lost, discard_unsaved discards that edit, and only allow-listed commands are accepted. It also surfaces the KiCad 10 board-path constraint, which is the kind of gotcha annotations cannot express.

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

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

Front-loaded with the core action, then the protocol, then parameter detail. The prose is dense but each clause carries a real constraint (document_dirty behavior, version caveat). The second sentence is long enough that the argument example has to be parsed out of a run-on.

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

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

For a destructive, multi-step external-command tool with no output schema, the description covers ordering, failure modes, and the concurrency hazard. What remains thin is the return shape (no output schema and no statement of what comes back on success vs. a refused reload) and the undocumented `documents` parameter.

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 has to carry the parameters. It covers command thoroughly (argv list without 'kct', must contain the {board} token, worked example) and clarifies allow_save and discard_unsaved semantics. The `documents` parameter is never mentioned, and timeout_s is acknowledged only as 'a timeout' with no unit or default context.

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: run one allow-listed kicad-tools write command on the board open in KiCad, wrapped in a defined handoff protocol. That is distinguishable from the siblings (saving, syncing, session checking) by the fact it executes an external CLI command. It stops short of naming the sibling tools it sequences with, so a 4 rather than a 5.

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 the ordered handoff: check the session, save the editor, run the command, then reload only if the command succeeded and changed the file. It also states the conditions that select allow_save (dirty state unknown, as on KiCad 10) and discard_unsaved (accept losing a concurrent edit). No explicit 'use X instead of this tool' branching is given.

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 declare readOnly=false and destructive=false. The description goes well beyond them: dirty or unknown-state boards are refused unless allow_save is set, saves are verified by checking the file changed, and KiCad 10 schematics cannot be saved at all without an explicit override. It also describes the return payload (pre-state, action, SHA-256, editor_sha256).

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, then the clean/dirty/refused decision, then return values, then the schematic caveat. Dense but each sentence adds decision-relevant information; only the schematic sentence feels like an addendum rather than part of the main flow.

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 still documents the returned fields and the follow-up call. For a mutating tool with annotations covering safety, the main remaining hole is the documents argument and whether the SHA-256 values are meant to be passed verbatim to sync_from_disk — mentioning editor_sha256 partially closes that.

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 the parameter meaning. It explains allow_save and schematic_unverified_ok clearly, but the documents parameter (string or array of strings, default null) is never defined — an agent cannot tell whether it takes paths, names, or handles.

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 operation and resource: make the on-disk file match the KiCad editor before a file-based tool (kct) touches an open board. It also names its counterpart, sync_from_disk, so an agent can distinguish the two without opening either schema.

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

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

Explicitly scopes when to call it (ahead of kct touching an open board) and states the exclusion that a proven-clean board is left alone. It also gives the escalation path (allow_save=true, schematic_unverified_ok=true) and names sync_from_disk as the follow-up.

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

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

Annotations already cover read-only/non-destructive/non-open-world, so the description's real contribution is the guarantee that failure states are returned as data rather than raised as errors — meaningful behavioral context that changes how an agent sequences calls. It does not elaborate on latency or partial-failure nuance, keeping it just short of a 5.

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 question (is KiCad running / is the API reachable), followed by the returned detail list and one clarifying sentence. The middle enumeration is dense but every item is distinct and useful; nothing is 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?

No output schema exists, yet the description enumerates the returned fields, effectively substituting for one and making the tool fully actionable. For a zero-parameter diagnostic with clear annotations, nothing an agent needs 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?

Zero parameters and 100% schema coverage, so the baseline applies; there are no parameter semantics to explain. The description instead spends its budget on return content, which is the right trade-off.

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 ('Report') and enumerates exactly what is reported: running state, IPC reachability, KiCad/API versions, instance, project directory, open documents with dirty state, and supported tools. This makes it unmistakable against siblings like board_summary or get_selection, which return schematic/board content rather than session diagnostics.

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?

'Always answers' plus the note that 'not running' and 'API disabled' come back as data tells the agent this is a safe, cheap preflight/probe call that will not error out. There is no explicit when-not or named alternative, but the intended usage context (check before acting) is clear.

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

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

Adds substantial context beyond annotations: it warns that the selection is REPLACED, discloses the KiCad 10 limitation where highlight and zoom return unsupported_on_this_kicad while selection still happens, explains that stale findings (pcb_sha256 mismatch) are still resolved and flagged possibly_stale, and describes the per-finding result shape. This is consistent with readOnlyHint=false (it mutates the editor selection) and destructiveHint=false, with 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?

Purpose and the selection-replacement warning are front-loaded, and nearly every sentence carries distinct operational information. It is dense with multi-clause sentences and could be broken into shorter units for scanability, but there is little pure 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?

There is no output schema, so the description covers return values itself (resolved items, unresolved locators with reasons, action taken, totals). Combined with the mode/focus/zoom semantics, the KiCad-version fallback, the stale-finding behavior, and the optional-location case, an agent has everything needed to call this 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% and the schema has no descriptions or enums, so the description must carry the load — and it does: it enumerates mode values (select | highlight | both), focus values ('all', a finding index, 'next', 'previous'), zoom as true/false, and the three accepted forms of findings. It also clarifies that a finding's location is optional and what a null location means.

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

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

Opens with a specific verb and resource: 'Point the user at kicad-tools findings in KiCad's PCB editor', then states the mechanism (resolve locators against the live board, select affected items). No sibling (session_status, board_summary, get_selection, etc.) does anything comparable, so the tool is unambiguously distinguishable.

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

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

Gives concrete input provenance — findings must be the JSON printed by 'kct check / drc / detect-mistakes / net-status --format json', or a list of its findings — which effectively tells the agent when this tool applies. It does not explicitly state when to prefer a sibling (e.g. get_selection) or when not to use it, so it stops 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 flag destructive=true and non-readonly; the description goes further with the refusal conditions, the byte-identical/token-identical cleanliness test, the 'no hash can prove it clean' caveat, the stale_input and document_dirty failure modes, and the fact that the reload is not an undo step. A note on what discard_unsaved actually destroys or on success response shape would make it a 5.

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 action and the refusal gate, and every sentence carries operational content. It is one dense block with long parenthetical asides (KiCad 10.0.7 token comparison) that cost some readability but not correctness.

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

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

No output schema, but the description names the failure signals an agent must handle (stale_input, document_dirty, manual_reload_required), which is the important part. The unmentioned documents parameter and the absence of any return-value hint leave a small gap for a destructive 4-param tool.

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

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

Schema coverage is 0%, so the description carries the burden: it explains editor_hash (editor_sha256 from save_before_external_write, detects later edits), expected_hash (file hash after the external write, guards against stale_input), and discard_unsaved as the override for the dirty check. The documents parameter is never mentioned at all, so coverage is incomplete despite good explanations of the other three.

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

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

Opens with a specific verb and resource plus the exact precondition: reload the KiCad editor from file after a kct write. It is clearly distinguishable from siblings like save_before_external_write, which goes the other direction.

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?

States when to call it (after a file-based tool wrote an open board), when it will refuse (dirty or unknown state, unless discard_unsaved=true), and what to do when the API cannot reload (schematic reports manual_reload_required). Alternatives and exclusions are explicit.

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