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

The description adds meaningful behavior beyond annotations: it discloses that the operation changes the chart ('Changes the chart you are building') and highlights non-obvious grouping semantics ('single undoable composition'). It also mandates a follow-up action (call chart_link). Annotations already indicate mutability, so the extra context about composition and workflow earns high marks.

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?

Four sentences, roughly 75 words, with no filler. The main purpose is front-loaded, shape semantics follow, mode guidance comes next, and the workflow note closes. Every sentence contributes a distinct piece of actionable information.

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?

Given the tool's 18 parameters and no output schema, the description covers the essential behavioral and workflow aspects: shape construction, mode selection, and the need to call chart_link afterward. It omits potential prerequisites (e.g., needing an existing chart) and some optional display params, but these are less critical for basic invocation, so the definition is nearly complete.

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 only 39%, and the description compensates for key parameters: it explains the mode enum ('highlighter' vs 'brush'), and clarifies the shape/points structure (line takes two endpoints; ellipse/rectangle take opposite corners). This is critical for correct invocation. It does not cover all remaining params, but the most semantically ambiguous ones are addressed.

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 ('Create'), resource ('freehand strokes'), and the unique composition behavior ('as a single undoable composition'). It clearly differentiates the tool by enumerating supported shapes (stroke, line, ellipse, rectangle) and their input conventions, so an agent can distinguish it from drawing_add, drawing_style, and position_draw_on_chart.

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?

Provides clear context within the tool: 'Use highlighter for translucent emphasis and brush for circles, paths and marks' directs mode selection, and 'call chart_link when you are done' gives a follow-up workflow step. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of full exclusion guidance.

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