route_plan_repairs

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

With no annotations provided, the description carries the full burden and does so thoroughly: it declares statelessness and pure-Python execution, enumerates the classification buckets, names each emitted action type with its payload shape, and specifies the error return on malformed input. The executor contract also discloses that the tool does not mutate the board itself — the caller must apply actions — which is exactly the kind of behavioral trait annotations would otherwise cover.

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 one-line purpose is front-loaded and the Args/Returns sections are conventionally placed. The executor-contract paragraph is dense with brace-notation payloads and runs long, but every clause maps an action verb to a required follow-up call, so the length is functional rather than padding.

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 two-parameter planner with an output schema, the description covers the input contract, the full action vocabulary, the downstream execution mapping, and the iteration model. Nothing an agent needs in order to call it correctly and act on the result is missing; the Returns block is mildly redundant with the output schema but not harmful.

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, and it does: 'violations' is defined as either the full pcb_run_drc result object or a bare violation list, and 'max_rounds' is defined as a rip budget for the clearance worst-offender loop with the non-obvious edge case (0 = escalate-only for clearance) called out. Both parameters gain meaning unavailable in 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?

States a specific verb and resource — 'Turn a DRC violation payload into an ordered repair plan' — and immediately distinguishes itself from pcb_run_drc (which produces the payload) and route_plan (which it calls as an executor step). An agent can tell what it produces (an action list) versus what its siblings do 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?

The 'Executor contract' paragraph is explicit about how to consume the output: apply actions in order, mapping each action verb to a concrete sibling tool, then re-run pcb_run_drc and re-plan, with the caller owning the outer loop bound. That is strong when/how guidance. It stops short of an explicit 'do not use when X' exclusion (e.g., no violations present), which keeps it at 4.

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