delete_invoice

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses the destructive consequence ('Automatically removes associated entries (line items)'), warns that posted invoices cannot be deleted, and explains the alternative (void or credit note). This covers the key behavioral traits for a delete operation reasonably well, though it doesn't specify idempotency or error behavior for nonexistent invoices.

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?

The description is well-organized with sections for the main behavior, the associated-entry side effect, posted-invoice handling, and parameter guidance. It is concise and front-loaded with the core purpose. The Args section is formatted clearly with a code-style layout. Minor verbosity in the legacy-alias explanation, but overall efficient.

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 tool has an output schema (mentioned in context signals) and two parameters fully documented in the description. The description covers the delete action, side effects (line item removal), preconditions (unposted), and parameter disambiguation. It leaves a small gap around what happens if the invoice_id doesn't exist or error handling, but for a straightforward delete operation with output schema present, it's fairly complete.

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 0%, so the description fully compensates. It explains the 'id' parameter with a format example ('000001' or 'INV-2026-001'), designates it as the preferred parameter matching sibling tools, and explains 'invoice_id' as a legacy alias with the constraint to pass exactly one of the two. This adds substantial meaning beyond the bare schema.

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 a specific verb + resource: 'Delete an unposted customer invoice.' It clearly distinguishes the tool from siblings through the 'unposted' qualifier and explicitly references alternatives (post_invoice, void, credit note). The scope is precisely defined, differentiating it from delete_bill, delete_credit_note, delete_voucher, and delete_transaction.

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 context on when the tool applies (unposted invoices) and explicitly states when it cannot be used ('Posted invoices cannot be deleted — void them or issue a credit note instead'), pointing to the alternative actions. It does not name specific sibling tools by name but describes the alternative paths sufficiently.

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