document_save

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

With no annotations provided, the description carries the full burden and does well: it discloses versioning, rejected parameters on an already-saved document, ENTITY_NOT_FOUND for missing folders, and background upload with "upload": "pending". It does not discuss permissions, undo/reversibility, or concurrent-save behavior, so it is not fully exhaustive.

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 dense and front-loaded, starting with the critical invocation rule. Every sentence contributes operational detail about saving, parameter behavior, error semantics, or return shape. The examples are compact and useful rather than redundant.

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 four-parameter mutation tool with no output schema and no annotations, the description covers the important behavioral surface: when to call, save/version semantics, parameter applicability, missing-folder behavior, background upload, and return shape. It could still be stronger with permissions or undo semantics, but it is substantially 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 100%, so the baseline is 3. The description adds conditional meaning beyond the schema: name and folder_path are rejected for already-saved documents, a never-saved document needs name, and missing folders are never created. This meaningfully clarifies how the parameters behave in different save scenarios.

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 states a clear verb and resource: save the document. It adds meaningful scope about explicit user request and saved vs. never-saved documents. It does not explicitly contrast with sibling tools such as document_new or document_close, but the purpose is still unambiguous.

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?

It gives a strong usage rule: call ONLY when the user explicitly asked to save the document. It also distinguishes the saved-document path from the first-save path and explains what parameters apply in each case. It stops short of naming alternative sibling tools for creating or closing documents.

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