save_diagram_scene

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

With no annotations, the description carries the full burden and does so well: it flags destructive overwrite semantics, states that any omitted element is deleted, documents the isDeleted escape hatch, explains the version/versionNonce bump needed for open editors, describes container/binding relationships, and warns that unsaved browser-tab edits may overwrite the save. That is exactly the mutation-risk and side-effect context an agent needs.

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 core replace-semantics are front-loaded and the IMPORTANT marker flags the destructive behavior early. The paragraph is dense and a bit long, but each sentence — versioning, container/binding structure, files/appState retention, concurrency caveat — carries actionable information rather than 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 destructive 4-parameter mutation tool with no annotations and no output schema, the description covers destruction, preservation, and concurrency risk thoroughly. The only gap is that it never says what the call returns, which matters slightly since no output schema exists.

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 100%, so the baseline is 3, but the description adds genuine meaning beyond it: elements must be the complete array rather than a partial patch, files/appState are preserved when omitted, and it explains the internal structure (containerId, startBinding/endBinding, boundElements) that the flat schema does not convey.

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 and resource — overwriting a diagram's scene with a full Excalidraw elements array — and scopes it to manual layout/precise edits, which cleanly separates it from the read-oriented sibling get_diagram_scene. An agent can distinguish it from generate_diagram without opening either schema.

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?

Gives explicit use context ('manual layout and precise edits: moving, restyling, relabeling, adding or removing specific elements') and a required workflow prerequisite ('Always call get_diagram_scene first, modify that array, and send back EVERY element'). It does not name when to prefer generate_diagram instead, so the alternative-routing is incomplete for a 5.

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