fusion_close_document

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

Annotations declare destructiveHint=true, but the description goes beyond that by explaining the safety behavior: with save=true and never-saved documents, it attempts to write to the active project and leaves the document open if saving fails, avoiding data loss. This is critical behavioral information that annotations do not provide, making the tool's side effects and failure mode clear.

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 concise (three sentences) and front-loaded with the core behavior (save true/false). It efficiently packs critical information about document selection, saving location, and failure handling without unnecessary fluff.

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?

Despite no output schema being present, the description explains the main outcomes (document closed vs. left open) and error behavior. However, it lacks details on edge cases like closing the only open document or what happens if the named document doesn't existiments. Given the tool's complexity and the richness of annotations, this is acceptable but not perfect.

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 must compensate, and it does: it explains that 'document' names another open document to close (rather than active), and that 'name'/'project' choose where to save a never-saved document. It does not explain 'description' or the default behavior of other parameters, but the key ones are covered, so a slight gap remains.

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 states the tool's primary function: closing a document with a flag to save or discard changes. It also explains the two possible behaviors (save vs. discard) and the context of the active document. This distinguishes it clearly from sibling tools like fusion_save_document and fusion_close_other_documents.

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 implies when to use save=true vs save=false (to persist changes or discard them). It also hints at the alternative for closing multiple documents (fusion_close_other_documents is a sibling). However, it doesn't explicitly state 'use fusion_save_document when you want to save without closing' or other exclusions, so it falls short of being fully explicit.

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