fusion_save_document

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

Annotations already indicate idempotent and not read-only, but the description adds valuable behavioral details: it eliminates the need for an interactive dialog and explains that unsaved documents are automatically saved into the active project. This goes beyond the structured annotations by clarifying the save flow. It does not contradict any annotations, and it provides context that helps the agent anticipate side effects (e.g., overwriting without prompt).

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 two sentences, tightly packed with relevant information. The core action ('Save a document') is front-loaded, followed by scope clarification and key behavioral notes. No extraneous words, every sentence 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?

For a moderately complex tool (4 optional params, no output schema), the description covers the main purpose and parameter semantics for three params. Missing details include the behavior for already-saved documents (idempotent implies overwriting, but not explicitly stated), the purpose of the `description` parameter, and any potential error conditions or prerequisites (e.g., must have a document open). The description is sufficient for basic use but not fully complete for edge cases.

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?

With 0% schema description coverage, the description is the sole source for parameter meaning. It explains three of the four parameters: `document` (targets another open document), `name` (optional filename override), and `project` (optional project override). The `description` parameter is left unexplained. Considering the 0% coverage, the description compensates well for most parameters but leaves a gap for `description`.

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 clearly identifies the action: 'Save a document' with the scope 'the active one unless `document` names another open one'. This distinguishes it from a generic save tool and hints at the ability to target a specific open document. It does not explicitly contrast with the sibling fusion_save_document_as, but the behavior of saving automatically without a dialog is unique, making the purpose stand out.

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 gives some usage context: it states that never-saved documents are saved automatically into the active project, and that `name` and `project` can optionally override defaults. However, it does not explicitly mention when to use this tool over `fusion_save_document_as` or other alternatives, nor does it provide conditions like 'use this for in-place saves' or 'use save_as for a new file version'. The guidance is implied rather than explicit.

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