apply_drawing_ops

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

With no annotations, the description carries the transparency burden. It discloses atomicity, the 50-operation limit, and the drawing-target fallback behavior. However, it does not mention that operations may be destructive (e.g., delete, revert_to_snapshot), failure semantics, or what happens on partial failure, so coverage is only partial.

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 only two sentences, front-loads the core purpose ('Atomically apply...'), and contains no redundant detail. Every clause earns its place.

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?

This is a complex tool with many operation types, no output schema, and no annotations. The description covers essential preconditions (read summary first) and target resolution, but it omits details about individual operation semantics, error behavior, and return values. It is minimally adequate given the rich schema, but not comprehensive.

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%, so the description must compensate. It adds meaning for drawingId (used when provided, otherwise selected drawing) and reinforces the 50-operation cap, but it does not explain the ops array structure or clientBatchId. The schema's const values and required fields are self-descriptive, but clientBatchId remains unexplained.

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 opens with 'Atomically apply up to 50 semantic operations,' clearly identifying a batch mutation tool for drawing elements. The verb 'apply' and the resource 'semantic operations' distinguish it from sibling read/inspection tools such as get_drawing_summary and inspect_drawing_element.

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?

The description explicitly explains target resolution: 'Uses drawingId when provided, otherwise the selected drawing.' It also instructs 'Read the summary first,' implying a dependency on get_drawing_summary, though it does not state exclusions or when alternative mutation tools would be preferred.

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