pcb_place_text

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

No annotations exist, so the description carries the full burden, and it does meaningfully: it discloses that stroke=0 preserves Altium's default, that height accepts decimals, that coordinates are in mils, and that the return value reflects properties read back after placement. It stops short of stating undoability or what happens if no PCB is active, which is the remaining gap for a mutation tool.

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 docstring is front-loaded with the core action, then structured per-parameter with no filler. The Returns block is somewhat redundant given an output schema already exists, but it is brief and does not crowd out the essential content.

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 seven-parameter mutation tool with zero schema descriptions and no annotations, the description covers every parameter, defaults, units, and layer enumeration, and the output schema removes any need to document the return payload in depth. An agent has what it needs to call this correctly.

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% — the schema carries only titles and defaults — so the description must compensate, and it does for all seven parameters. It adds units (mils, degrees), enumerates valid layer values including the Mechanical1–Mechanical16 range, and explains the special stroke=0 semantics.

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 opens with a specific verb+resource+scope: "Place a text string on the active PCB." That is unambiguous and lets an agent distinguish it from library-side text tools such as lib_add_footprint_text or style tools such as pcb_set_text_style. It does not explicitly name the closest siblings (sch_place_text_frame, pcb_set_text_style) in a routing sense, keeping it just under a 5.

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?

It gives a concrete alternative for an adjacent task — "To resize existing designators use pcb_set_text_style" — plus defaults for layer, height, rotation, and stroke that guide invocation. It does not state prerequisites such as needing an open, active PCB document, but the usage context is clear.

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