add_rectangle

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

Annotations already cover safety (destructiveHint=false, openWorldHint=false, idempotentHint=false). The description adds one genuinely useful behavioral fact: omitted style parameters fall back to Excalidraw defaults rather than to some tool-specific value. It does not say whether the new element is selected, returned, or how it interacts with an active frame, so the addition is modest.

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?

Two short sentences with the action front-loaded and the defaulting caveat immediately after. No filler, though the second sentence is vague enough ("style parameters") that it could name the relevant group more crisply.

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 a 16-parameter geometry-plus-styling tool with zero parameter documentation in the schema, the description is far too thin; an agent cannot confidently supply coordinates, labels, or frame attachments from it. The output schema does relieve it of describing return values, which is the only reason this is not a 1.

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% across 16 parameters, so the description carries the full burden and largely fails: it never mentions x/y coordinate space or units, w/h constraints, what label does, or what frame_id attaches to. The one contribution — that style parameters are optional and default — is real but covers only a fraction of the surface.

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?

"Add a rectangle to the scene" gives a specific verb (add) and resource (rectangle), and the sibling list makes it trivially distinguishable from add_circle, add_diamond, add_frame. It stops short of stating scope/side effects, but the purpose itself is unambiguous.

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?

No guidance on when to choose this over add_frame, add_text, or update_element, and no preconditions (e.g. whether a scene must be loaded/opened first). The only conditional statement concerns omitting style parameters, which is a defaulting note rather than a usage rule.

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