update_drawing

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the destructive character is known; the description adds that the engine validates input before writing and that source/preview are opt-in. However, it never explains what remove/upsert actually overwrite, nor the optimistic-concurrency meaning of the required expectedRevision, so it adds only partial behavioral context on top of 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?

Four short sentences, front-loaded with what the tool does before moving to prerequisites and alternatives. Dense and mostly waste-free, though "Low-level complete-element upserts, removes, or document changes" crams several distinct operations into one clause.

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 10-parameter, nested, destructive write tool with no output schema and 10% schema coverage, the description covers the alternative and validation but omits the semantics of expectedRevision, what the return looks like, and how revision conflicts are signaled. Adequate for routing, incomplete for correct invocation.

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 only 10% across 10 parameters, so the description carries real weight and does help by pointing to get_format for the opaque, untyped upsert element fields. But it adds nothing about the required expectedRevision (a concurrency token), name, seed, sketch, or canvas, leaving most parameters undocumented in both places.

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 states a specific action family – "complete-element upserts, removes, or document changes" – for the update_drawing tool, and differentiates its low-level, complete-element scope from patch_drawing. It stops short of plainly saying it mutates a drawing document, but the verb/resource pair is inferable and the scope note distinguishes it from siblings.

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?

"Prefer patch_drawing for small label/style changes" gives explicit alternative routing with a selection condition, and "Fetch get_format for full element fields" tells the agent what to do before calling. It doesn't address the other write siblings (edit_drawing, compose_drawing) or state prerequisites for expectedRevision, so it's clear context but not exhaustive.

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