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

Annotations establish the mutation profile (not read-only, not idempotent, non-destructive), so the description's job is narrower. It adds the entry_ids echo-back behavior that enables chaining to entry_mark_billed, which is valuable. But for a non-idempotent create it does not warn that repeat calls produce duplicate invoices, and it says nothing about permissions or side effects on referenced entries.

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?

A compact, front-loaded sentence that leads with the purpose and then the branching behaviors. Every clause carries information; the only minor cost is that the fx_rates and entry_ids clauses make it denser than it needs to be, since the schema already explains those fields.

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?

With 14 parameters, a non-idempotent create, and no output schema, the definition should do more work. It gives the gist of the return ('returns a single-line invoice', echoes entry_ids) but omits the idempotency caveat and doesn't sketch the response shape, which matters because there is no output schema to fall back on.

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 ties the core semantics together: hours and rate form a single line, fx_rates with target_currency converts the rate, and entry_ids are echoed back. That is real meaning beyond the field list. It still leaves tax_rate, discount_percent, due_days, issue_date and notes unmentioned, though those are largely self-describing by name.

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 and returns a single-line invoice') plus the narrowing scope ('bill one client for N hours at an hourly rate'). The 'shortcut for the common case' framing implicitly distinguishes it from invoice_create, but never names that sibling, leaving the contrast to inference.

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?

Implies the usage context (one client, one hourly rate, single line) and names the trigger for the fx_rates branch, which is genuinely useful. However it never states when NOT to use it or that invoice_create is the alternative for multi-line or non-hourly invoices.

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