document_update

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

With no annotations, the description does real work: it discloses the draft-only precondition, the 409 failure mode, and precise patch semantics (only sent fields change, explicit null clears). It omits side effects an editor of invoices would care about — whether totals are recalculated, whether validation runs, or what the call returns.

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 short sentences, zero waste, with the precondition first, the failure mode second, and the field-level contract last. Every sentence carries information an agent needs.

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 23-parameter mutation tool with no annotations and no output schema, the description covers the state constraint and patch semantics well but leaves field-specific meaning and post-call behavior undocumented. An agent could call it correctly for simple scalar edits but would be guessing on nested arrays and unsupported fields.

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% across 23 top-level parameters, so the description must compensate, and it does explain the global omit-vs-null contract that governs every field. However, it says nothing about the many opaque fields (reason, source_document_id, business_profile_id, tax_scheme) or whether array fields like line_items are replaced wholesale or merged, which is the highest-risk ambiguity here.

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?

States a concrete verb and resource ('Change a document') plus the gating state ('still a `draft`'), which tells an agent immediately what class of operation this is. It does not name a sibling (e.g. document_transition or document_create) to differentiate the path for non-draft documents, so it falls just short of a 5.

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?

Gives a clear when-to-use condition (document is in draft) and a when-not (finalized documents are immutable, returning 409). It stops short of pointing to the alternative tool for a finalized document, leaving the agent to infer document_transition or document_duplicate.

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