pcb_placement

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

No annotations are provided, so the description carries full behavioral burden. It never clarifies that this is a read-only query (the 'Pick-and-place:' phrasing could even suggest a write/placement action), nor does it describe units behavior or variant semantics. It does at least disclose the regex filter 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 tight lines with the returned field set front-loaded and the filter note second. Nothing is padded, though the second sentence is narrower than the remaining undocumented parameters.

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 4-parameter, zero-annotation tool with a required `project` argument, the description omits scope (which project/variant?), unit handling, and read-vs-write behavior. The output schema covers return values, but the input-side gaps are significant.

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 only explains one of four parameters: `pattern` and its matched fields. The required `project`, plus `units` and `variant`, are given no meaning anywhere, leaving an agent guessing at scope and formatting.

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 names the data fields returned (designator, footprint, layer, center X/Y, rotation), so an agent can infer this yields PCB component placement data. However, it never states a verb ('get'/'list'), and 'Pick-and-place:' reads ambiguously like an action rather than a query, so the verb+resource pairing is only implied.

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?

There is no guidance on when to call this versus siblings like pcb_info, components_near, or render_pcb. The only usage hint is what `pattern` filters on, which is a parameter note rather than a when-to-use statement.

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