add_svg_progress_bar

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

With no annotations, the description carries the full burden. It does disclose key behavioral details: how the SVG is composed ('track + fill scaled to value/target'), the effect of kind ('bullet adds a target tick'), and the role of color parameters. However, it does not mention whether the measure is created or updated, what happens if the measure already exists, required permissions, or any side effects. This is a moderate level of transparency for a write operation.

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 exactly two sentences, front-loaded with the primary purpose. Every phrase adds information: the measure type, DataCategory, visual composition, and color semantics. There is no filler or redundancy.

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?

The description explains the core functionality (creation of an SVG progress/bullet measure) but omits practical details that would help an agent complete the task correctly: what the return value is (if any), whether the tool overwrites an existing measure, required model/session context, and any constraints. With no annotations and no output schema, the description alone does not fully cover the operational context.

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 70%, so the description adds value for several parameters: it explains kind semantics ('bar|bullet (bullet adds a target tick)') and clarifies trackColor/fillColor roles ('trackColor is the rail; fillColor the achieved portion'). It also explains the relationship between valueMeasure and targetMeasure. This goes beyond the schema's terse descriptions and compensates for the coverage gap well.

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 uses a specific verb ('Author') and resource ('SVG PROGRESS BAR / BULLET measure') and details the visual composition ('track + a fill scaled to value/target, rendered in-cell'). It clearly distinguishes this from sibling SVG tools like add_svg_sparkline or add_svg_gauge by naming the exact chart type.

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?

The description clearly implies when to use the tool (when an SVG progress bar or bullet measure is needed) but does not explicitly mention alternatives or exclusions. There is no guidance on when not to use it or how it compares to similar tools like add_svg_databar. Usage is implied by the resource type, but no explicit alternatives or when-not-to-use guidance is provided.

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