add_text

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

Annotations already declare destructiveHint=true, so the destructive nature is known. The description adds the important nuance that the operation does not save, which clarifies persistence behavior. However, it does not disclose other behavioral traits such as what happens on invalid input, coordinate system assumptions beyond 'absolute mm', or whether the change is reversible. It adds some value beyond annotations but is not rich.

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 sentence with no redundant words. The core action is front-loaded, and the critical 'do not save' caveat is placed at the end. Every word contributes to clarity. This is an excellent example of concise, well-structured documentation.

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 simple add-text operation with an output schema already defined, the description covers the essential behavioral and coordinate aspects. It omits details like default layer values or height units, but these are partially discoverable from the schema. The 'do not save' note is important and present. Overall, the description is nearly complete for an agent to safely invoke the tool, though a bit more context on coordinate origin or units would make it fully self-sufficient.

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. It mentions 'absolute mm coordinates' (covering x_mm and y_mm) and 'specified layer' (covering layer), but does not explain the text content or the height_mm parameter, nor the defaults for layer and height. The description adds minimal meaning beyond the schema and leaves several parameters undocumented.

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 clearly states the action (Add), the resource (PCB text), and the key specifics (absolute mm coordinates, specified layer). It also adds a critical note about not saving, which distinguishes it from board-save operations and makes the tool's scope unambiguous. The purpose is fully transparent and easily distinguishable from siblings like add_track or move_footprint.

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?

No guidance is given on when to use this tool versus alternatives such as add_track or move_footprint. The 'do not save' note is a behavioral caveat, not a usage guideline. There is no mention of prerequisites, typical scenarios, or when a different tool would be more appropriate, so an agent has to infer usage context.

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