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

Annotations only say readOnlyHint=false and destructiveHint=true; the description adds genuinely non-obvious behavior: the draft is private, numbering happens only on send, voided documents still consume the free-plan quota, and Pro is unlimited. That is meaningful context beyond the annotations, though it does not explain why a creation tool is flagged destructive (quota consumption) nor what the response contains.

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?

Six short sentences, front-loaded with what is created and what it copies, followed by the privacy/numbering, quota and prerequisite facts. Dense but every sentence carries operational information; the quota sentence is slightly tangential but still decision-relevant.

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, the description covers prerequisites, side effects and limits well, but never says what the call returns (e.g. the new document's id) or whether the draft can be edited/deleted afterwards. An agent needs that to chain into update_invoice or send_invoice.

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 75%, so most parameters are already documented in the schema (currency defaults, discount units, line fields). The description adds meaning only for the aggregate behaviors (lines accepted, billing details and client copied), not for individual optional parameters such as boardId, terms or taxLabel.

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 specific verb and resource ('Creates a draft invoice or estimate') plus the scope of what gets copied onto it. It is clearly distinguishable from siblings like send_invoice, update_invoice, convert_estimate_to_invoice and create_invoice_from_work because it emphasizes that the result is a private draft with no number.

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 real prerequisite ('Needs the billing details to be set up') and makes clear this is the draft-creation step, with sending deferred elsewhere ('sending takes the next one from the profile's counter'). It does not explicitly name sibling alternatives such as preview_invoice_from_work or create_invoice_from_work, so it falls short of full alternative routing.

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