delete_voucher

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

No annotations are provided, so the description carries the full burden. It discloses that 'associated entries are automatically removed' as a side effect of deletion, which is important destructive behavior. It could further clarify irreversibility or permission needs, but the cascade-deletion disclosure is meaningful.

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?

Well-organized with logical sections (delete rule, cascade behavior, posted-voucher note) and an Args block. Slightly verbose with the back-compat explanation and preferred-parameter rationale, but each sentence earns its place for guiding correct usage. No wasted fluff.

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 2-param destructive tool with no annotations and 0% schema coverage, the description does substantial heavy lifting: usage precondition, cascade side effects, parameter disambiguation, and cross-tool references. An output schema exists, which relieves the need to document return values. Complete given complexity.

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 description coverage is 0%, so the description must compensate, and it does. It explains both parameters: 'id' is the preferred name with an example format ('000001'), and 'voucher_id' is a legacy alias accepted for back-compat. It also states the constraint to pass exactly one of id or voucher_id — genuinely additive beyond the 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?

Specific verb+resource: 'Delete an unposted employee expense voucher.' Clearly scopes the action to unposted vouchers, distinguishing it from the many sibling delete tools (delete_invoice, delete_bill, delete_budget, etc.) and from post/unpost operations. Strong statement of what is and isn't deletable.

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?

Explicitly states the precondition (voucher must be unposted) and gives a pathway: 'unpost first via unpost_invoice, then delete.' Also clarifies that posted vouchers cannot be deleted. This is strong when/how guidance that a sibling comparison supports.

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