pin_rule_baseline

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is free. The description earns credit for enumerating exactly what is captured and for stating the caller-side storage/pass contract, but says nothing about the returned shape or size beyond that. Useful addition, not rich behavioral context.

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?

Three short sentences, zero filler: what is captured first, then the read-only contract, then the ordering constraint. Front-loaded and every clause carries information.

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 single-parameter, no-output-schema tool the description covers purpose, safety, content, and workflow placement adequately. The only missing piece is what pcb_path expects, a minor gap given there is only one parameter and no enums or nesting.

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 sole parameter, pcb_path, is never explained in the description, so that gap is not compensated. The description does clarify the conceptual `baseline` artifact exchanged with verify_board, which is genuinely beyond the schema and keeps this from scoring lower.

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 ('Snapshot') and a precisely enumerated resource (rule severities, netclass limits, .kicad_dru clauses, ignored checks), and anchors it to the consumer tool verify_board. An agent can distinguish this from verify_board itself 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?

Gives a clear timing rule ('Pin before the work, not after it') and explains the downstream usage contract (caller stores the result and passes it as `baseline`). It does not name an explicit alternative or a when-not-to-use case, which keeps it below a 5.

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