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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the bar is lower. The description still adds meaningful behavioral context: null clientId 'detaches the link but keeps the current recipient snapshot', a UUID 'rebuilds this invoice snapshot' (disclosing destructive overwrite), and the no-auto-rewrite rule for historical invoices. There is no contradiction with annotations.

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 dense sentences, each earning its place: the action scope, the clientId decision table, and the historical-invoice immutability warning. The synonym chain 'update, revise, correct, translate, restyle' is slightly redundant, but each maps to a real capability (numberCorrection, invoml, templateId), so it is justifiable rather than padding.

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 7-parameter mutation with nested objects, the description covers the genuinely tricky semantics (client link states, snapshot rebuild, number immutability) while the output schema and 100%-coverage input schema handle return values and remaining parameters. Authentication scope ('owned by the connected workspace') is noted. Minor gaps like resync failure behavior are not critical given the schema richness.

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 schema already documents clientId's omit/null/UUID semantics nearly verbatim, and numberCorrection's 'from must equal current canonical number' rule. The description adds modest extra meaning around the resync workflow (why a snapshot rebuild matters, historical immutability), but the schema carries most of the parameter burden.

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 names a specific resource ('an existing invoice owned by the connected workspace') and a concrete action set (update, revise, correct, translate, restyle, resync). It differentiates from siblings implicitly: update_client handles the client resource itself, create_invoice handles new invoices, and the 'existing invoice owned by the connected workspace' scoping sets it apart from archive/send tools. The synonym cluster is slightly broad, but the resource and scope are 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?

The description gives clear context for when to use this tool: correcting persisted numbers, translating, restyling via template, and explicitly resyncing a client. The clientId omitted/null/UUID trichotomy is a precise usage rule, and 'Client edits never rewrite historical invoices automatically' signals when an explicit resync is required. It stops short of naming when-not-to-use alternatives (e.g., create_invoice for new invoices), 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.