lib_convert_designators_to_stroke

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

With no annotations, the description carries the full burden and does so: it declares the mutation (clears UseTTFonts, Bold and Italic), discloses the destructive consequence (stroke text cannot be bold, so those attributes are lost), describes verification and persistence side effects (reads back, saves, reloads), and even documents the return shape.

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?

Purpose is front-loaded in the first sentence, with the persistence rationale and the return shape following in a logical order. The TrueType-position explanation is longer than strictly required but earns its place by justifying why the conversion exists.

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?

An output schema exists, so return values are already covered, and the description nonetheless sketches them. Behavior, side effects and the sibling pipeline are all present; the one real hole is the semantics of library_path, which is undocumented in both schema and description.

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% and there is one parameter, library_path, which the description never mentions. It does not say whether the path is optional, whether it defaults to the active library, or what form the path takes, so an agent must guess on the only input it has to supply.

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?

Names a specific verb and resource ('Convert every TrueType .Designator in a PcbLib to a stroke font') and scopes it to a defined subset of objects. It also distinguishes itself from the neighbouring lib_fix_designators and lib_probe_designator by explaining the pipeline order.

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 concrete trigger ('a handful of designators per library refuse to centre', 'a bold or italic designator is the reliable TrueType tell') and states the follow-up step ('afterwards ... lib_fix_designators can centre them'). It stops short of an explicit when-not-to-use condition or a statement of prerequisites, so it is clear context rather than a full decision rule.

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