kb_update_document

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

With no destructive/read-only annotations, the description carries the full burden of disclosing side effects. It explicitly warns that a resync rebuilds the index and that agent metadata must be re-applied afterward, and it mentions the status lifecycle (ready→pending→ready). This is essential behavioral context beyond what annotations provide.

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 three compact sentences, front-loaded with the core purpose, then the mode selection, then the critical side-effect note. Every sentence adds value and there is no filler.

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?

The tool's core behavior, two input modes, status transition, and side-effect warning are all covered, which is sufficient for a single-document update. It doesn't describe return values (no output schema) or clarify interactions like passing both url and content, but these are non-critical gaps given the concise and informative description.

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 compensate. It explains the meaning of `url` and `content` and their appropriate use cases, but leaves `name` and `config` unexplained. Required params `project_id` and `document_id` are self-evident from their names, but full parameter semantics are incomplete.

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 uses a specific verb ('Refresh') and resource ('a document's content in place') while explicitly noting it keeps the SAME document_id, clearly distinguishing it from tools that create new documents or update metadata. It also differentiates between URL and text document modes, making the purpose unmistakable.

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 guidance on when to pass `url` vs `content` (for URL docs vs text docs), which is the primary selection criterion. It does not explicitly name alternatives like kb_update_document_metadata, but the distinction between content refresh and metadata update is evident from the description and sibling names.

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