create_invoice

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

Annotations indicate readOnlyHint=false and destructiveHint=false, so the description must clarify behavior. It mentions creation defaults to draft and that approval books the invoice, which implies a mutation but not destruction. It does not disclose any side effects like irreversible number assignment or email sending. Lacks details on what happens to the contact or inventory. Adequate but not rich.

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 concise sentences plus a short clarifying note. Every sentence serves a purpose: identity, default behavior, and a key semantic detail about units. No wasted words.

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 tool with 12 parameters, no output schema, and annotations with no safety hints, the description covers the essential purpose, default state, and currency semantics. It mentions the verbose parameter in the schema but not in the description. The absence of output description is mitigated by the verbose parameter documentation. Overall, it's fairly complete given the high schema coverage.

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 100%, so parameters are already described. The description adds one meaningful piece: 'Amounts are in the invoice currency,' which is not in the schema. It also reinforces the 'state' parameter's effect. Since schema is thorough, the added value is moderate but tangible.

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 states 'Create an invoice (or credit note) in Billy with one or more lines,' clearly specifying the verb (create), resource (invoice/credit note), and key constraint (one or more lines). It distinguishes itself from sibling tools like approve_invoice (which modifies state after creation) and delete_invoice.

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 provides clear usage guidance: 'Created as draft by default; pass state=approved to approve immediately (approval assigns the invoice number and books it).' It explains the default behavior and how to change it but does not explicitly state when not to use this tool (e.g., if you only need to approve an existing invoice, use approve_invoice instead). Sibling tool approve_invoice exists, but the description omits that alternative.

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