write_document

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

Beyond the sparse annotations (only destructiveHint=false), the description discloses backup-before-replace, optimistic concurrency refusal via expected_uuid, refusal conditions for search threshold/maximum, the exact allow_search_mode semantics, and the need to relay any warning. This is exceptionally transparent for a mutating tool.

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 but every sentence earns its place: core action first, then safety, concurrency, refusal conditions, and result handling. It uses efficient semicolon-separated clauses rather than padded prose, and the most important usage information is front-loaded.

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?

With no output schema, the description still tells the agent how to handle a key part of the result ('Relay any warning in the result to the user verbatim') and enumerates all refusal modes. For a 6-parameter mutation tool, this covers the non-obvious behavior an agent needs to call it successfully.

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 0%, so the description must carry the semantic load. It does: overwrite is defined as replace behavior, expected_uuid is explained as a concurrency guard, and allow_search_mode is precisely distinguished (accepts threshold, never maximum). Even the file-name-without-extension warning adds parameter-adjacent meaning beyond the schema titles.

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 opens with a precise verb and resource: 'Create a document, or replace one with overwrite=true.' It clearly separates create vs replace and stands apart from siblings like read_document, rename_document, and delete_document by describing the write/update action. No ambiguity about what the tool does.

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 clear when-to-use context (create a new document, or replace an existing one) and even points to read_document for expected_uuid. It stops short of explicitly contrasting with alternatives such as rename_document or delete_document or stating when not to use this tool, so it earns a 4 rather than a 5.

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