draw_shapes

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

With annotations marking it as a non-read-only, non-destructive write, the description adds behavioral detail: antialiasing is off by default to preserve hard pixel edges, and each shape is stroked or filled. It stops short of describing save/write-back defaults or permission needs, but adds useful context beyond the annotations.

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-loads the purpose and supported shapes, then covers stroke/fill, antialiasing default, and sibling routing in three compact sentences with no filler.

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 complex, 11-parameter drawing tool, the description covers shape semantics and antialiasing well, and the schema covers most remaining parameters. It could mention save/write-back behavior or target frame/layer defaults more directly, but output schema absence is acceptable.

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 82%, so parameters are already well documented; the description still adds value by explaining bezier point ordering ('start then control1, control2, end per segment') and path op semantics. It leaves many top-level parameters (frame, layer, save, opacity, blendMode) to 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 ('Draws vector shapes') and enumerates all supported shape primitives, and it names use_tool as the alternative for pixel-exact aliased work, so an agent can distinguish its role from sibling drawing tools.

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 a clear routing rule for one alternative: pixel-exact aliased shapes should use use_tool. It does not compare against draw_pixels or draw_image, but it gives enough antialiasing context to decide when vector drawing is appropriate.

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