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

Annotations are all false (readOnlyHint=false, etc.), so the description carries the transparency burden. It goes beyond the schema by disclosing that totals are computed from line_items and tax_rate, the invoice starts in 'draft' status, and the invoice is owned by the caller. This is valuable behavioral context that annotations alone do not 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?

Two sentences, no fluff, and front-loaded with the core action. Every clause adds value: caller ownership, optional line items/deal link, computed totals, draft status, and the next-step call to send_invoice.

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 description covers the essential behavior for a create tool: draft status, computed totals, ownership, and follow-up action. It does not explicitly state what happens if no line_items are provided (e.g., zero totals), but the output schema and annotations fill in some gaps. Overall, it is complete enough for an agent to use correctly.

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?

The description clarifies how line_items and tax_rate interact (totals computed from them), which is not obvious from the schema where tax_rate only says 'Percentage'. It also explains deal_id as linking to an owned deal. With 56% schema description coverage, the description adds meaningful parameter semantics, though not all params are covered.

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 begins with 'Create a draft invoice owned by the caller for a client' — a specific verb+resource+ownership that clearly distinguishes the tool from siblings like update_invoice, send_invoice, or convert_deal_to_invoice. It also notes optional line items and deal linking, which further differentiates it from add_invoice_line_item.

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 states that the invoice starts in 'draft' status and directs the agent to call send_invoice to mark it sent, providing clear subsequent workflow. It also mentions optional deal linking, implying when to use this vs. convert_deal_to_invoice, but it does not explicitly state exclusions or when to prefer an alternative.

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