Update document

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

The description goes well beyond annotations by disclosing that only passed fields are touched, that tag_ids is a wholesale replacement while add_tag_ids/remove_tag_ids are relative, and that clear_* flags unset fields. This gives an agent critical behavioral knowledge about merging versus replacing that cannot be inferred from the schema alone.

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?

Three sentences lead with the core action, then state the partial-update behavior, then clarify the tag and clear-flag edge cases. Every sentence earns its place and the most important distinguishing semantics are 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?

For a 16-parameter mutation tool with no output schema and low schema coverage, the description covers the highest-risk semantics but leaves gaps: how to clear simple fields, null-handling for owner_id and archive_serial_number, and the wholesale replacement behavior of custom_fields is only in the schema. An agent could still call it correctly for common cases but would be uncertain about several 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 only 31% schema description coverage, the description compensates for the most confusing parameters: tag_ids, add_tag_ids, remove_tag_ids, and the clear_* flags. However, many parameters (owner_id, custom_fields, archive_serial_number, storage_path_id) are not addressed in the description, and the generic 'only fields you pass are touched' rule only partially fills that gap.

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 'Change one document’s metadata', a specific verb ('change') and resource ('one document’s metadata'), and the singular scope clearly separates it from sibling tools like paperless_bulk_edit_documents. The distinction from paperless_update_object is also implied by the document focus.

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 clearly indicates this is for a single document and explains update mechanics, but it never explicitly states when to prefer this over paperless_bulk_edit_documents or when not to use it. Usage context is present but no exclusions or alternative routing are provided.

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