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

With only destructiveHint=false and a title in annotations, the description carries most of the burden and does well: it discloses that creation is non-destructive and reversible-feeling (draft, nothing emailed) and that statement_no has a uniqueness constraint. It does not say what happens on a duplicate statement_no or what permissions/plan are required.

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?

Four short clauses, front-loaded with the WRITE marker and the draft caveat, all doing work. The trailing 'Hiveage: POST /invs.' endpoint notation is the only piece an agent can't act on.

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 an 18-parameter creation tool with no output schema, the description covers the essentials an agent needs to call correctly: it's a write, it's a draft, the id source, and the uniqueness constraint. Missing is any hint about the return value (presumably an invoice id) or that line items may be optional given draft state.

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 coverage is 67%, so several parameters (note, summary, po_number, send_reminders, allow_partial_payments, send_receipts_automatically) are undocumented in both places. The description adds real value on the two most important fields — connection_id's provenance (numeric id from hiveage_list_connections, not hash_key) and statement_no uniqueness — but says nothing about the many line-item arrays or the boolean flags.

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 ('create an invoice') plus the scope caveat that it starts as a draft and emails nothing, which separates it cleanly from hiveage_send_invoice in the sibling list. The 'WRITE:' prefix makes mutation intent unmistakable at a glance.

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 draft/no-email note implicitly tells the agent that a follow-up send step is needed, and the pointer to hiveage_list_connections for connection_id gives the prerequisite call. It stops short of explicitly naming hiveage_send_invoice or hiveage_update_* as the next/alternative step.

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