add_icon

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

With no annotations, the description carries the burden and does substantial work: default sizes and valid range, ratio preservation, the mono-versus-colored stroke rule with a default color, label grouping semantics, and the returned ids. The live-vs-file behavior is left to the schema's path description rather than repeated, which is reasonable but leaves a mutation's side effects only partly visible in the prose.

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?

Front-loaded with the operation, then ordered by importance (source, sizing, color, label, return). Dense with parenthetical clauses but nearly every clause carries actionable information; a minor tightening of the sizing sentence would make it a 5.

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 an 11-parameter tool with no output schema, the description supplies the return values (image id and label_id) and surfaces the `warnings` channel for unapplicable markup. Only the live-versus-saved board side effects and permission expectations are absent, and those are partly covered in the schema.

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 already high (82%), so the baseline is 3; the description adds genuine relational meaning beyond it — that `size` is the longest side, that it is not combinable with w/h, that a single w or h preserves the icon ratio, and that `stroke` only applies to mono icons. It does not touch x/y/page defaults, but those are documented in the schema.

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 and resource ('Places an icon of the library on the board') and immediately scopes it apart from sibling resources by naming the source ('an id returned by search_icons') and the follow-up action (add_connector). An agent can distinguish this from add_image, add_shape, and add_table without opening any 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?

Usage is implied rather than stated: the reader infers this is the tool for library icons and that search_icons must run first to obtain an id. There is no explicit 'when not to use' guidance or routing compared to add_image / add_shape, which matters given several visually adjacent siblings.

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