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

The description exposes critical behavior beyond annotations: fixed stroke width ('3 px'), restrictive color palette with silent clamping of invalid values ('anything else... silently clamps to auto'), and the availability of multiple point formats. Annotations already flag destructive and open-world hints, so the description adds significant client-side context (e.g., serialization issue), though it doesn't explicitly state that the tool is not read-only or that it creates persistent state beyond the default annotation signal.

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 detailed and front-loaded, leading with the primary action and use cases, then progressively covering parameters and caveats. While it is wordy, every sentence adds unique information (width, color clamping, format quirks, deletion pointer), so it earns its length. The only minor deduction is that the sentence enumerating colors is lengthy and could be structured as a list, but it is still functional.

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 complexity of the tool (multiple input formats, many color options, client-specific serialization concerns, a deletion or relation to `erase`), the description addresses most of the critical aspects an agent must know. It lacks an explicit note about the output (no output schema), but the absence is unlikely to cause misuse because the tool returns an id (implied by the deletion instruction). The trade-offs of the serialization issue and fixed width are well covered.

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?

The description significantly enriches parameter understanding beyond the sparse schema. It elaborates on the `points` format variants (nested, flat, JSON string) and provides a detailed color enumeration and semantics for 'auto'/empty values. Although the `color` parameter has no enum in the schema, the description defines allowed values and the fallback behavior, effectively compensating for the low schema coverage (~33%) on most parameters.

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 clearly states the tool's action ('Draw a freehand stroke on the board') and immediately enumerates typical use cases ('arrows, underlines, connector lines, annotations, or simple shapes'), which distinguishes it from sibling tools like add_text, add_image, and erase.

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 provides explicit guidance on how to use the tool (e.g., 'a straight line needs two points, a rough circle wants ~20'), notes client-specific serialization quirks ('Some clients (Claude Code as of 2026-04) drop nested arrays... so prefer the flat form'), and references an alternative for deletion ('use erase with kind: 'line''). This is actionable, when-to-use and how-to-use guidance that exceeds the minimum.

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