sync_from_disk

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.