apple_keynote_save

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

Annotations already flag destructiveHint=true, idempotentHint=false and openWorldHint=true, so safety is covered; the description adds real behavior beyond that by specifying the overwrite gate for existing paths, the parent-directory requirement, and the absence of implicit format conversion. It does not state what happens to the prior file content on overwrite or any permission requirements.

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?

Three tight sentences with the core constraint front-loaded. The trailing 'TextEdit saves RTF; no implicit format conversion' is useful for format routing but is slightly off-topic for a save tool and could read as a sibling note.

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 mutation tool with no output schema and annotations that already convey the destructive/idempotency profile, the description covers the key decision points an agent needs (overwrite gate, directory prerequisite, format behavior). Return-value behavior after saving is not addressed, a minor gap.

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 low (33%), so the description has to carry the load, and it does: it explains that overwrite is mandatory for existing/current paths and that path must point to a .key file under an existing parent. documentName's meaning lives in the schema, so the description's contribution is partial but substantive.

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 ('Save Keynote to a .key path') and pins the format, which distinguishes it from apple_keynote_export and the parallel pages/numbers/textedit save tools. An agent can identify the operation without opening the 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 clear preconditions: an existing parent directory, and overwrite:true for any existing path including the current document path. It implies but never names the alternative for other formats (export), so routing guidance is strong but not fully explicit.

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