Edit deck

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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description supplies genuinely additive behavior: operations execute in order, the batch is atomic ('All operations succeed or none is saved'), and the concurrency failure mode is stated explicitly. It omits auth requirements and what a failed call returns, keeping it short of a 5.

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 tight sentences with the highest-value claim ('the only way to change a deck') front-loaded, followed by scope, atomicity, and the failure condition in descending order of importance. No filler and nothing repeated from schema or annotations.

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 tool this complex (a large discriminated-union ops array, no output schema), the description covers atomicity, ordering and the revision conflict, which are the essentials. It still leaves gaps an agent needs: how to obtain the current expected_revision, and what the call returns on success or rejection (new revision, per-op errors, previews). Adequate but not complete.

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 high (~80%) and the ops oneOf variants are self-documenting via their const values, so the description's enumeration of op kinds largely restates the schema. The concurrency meaning of expected_revision is the only real addition, and it is already captured under behavioral transparency, so baseline 3 is appropriate.

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 ('change a deck', 'applies operations') and then enumerates exactly what those operations cover: add, update, remove, move slides, set design, motion, title, brief, apply a brand kit. The opener 'The only way to change a deck' immediately separates it from read/validation siblings like get_deck and validate_deck.

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 exclusivity claim ('the only way to change a deck') routes the agent away from non-mutating siblings, and the failure condition on expected_revision tells the agent it must hold a fresh revision first. It stops short of naming the tool to read that revision (get_deck) or suggesting validate_deck before applying, so guidance is clear but not exhaustive.

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