delete_bill_item

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

With no annotations, the description carries the full burden. It discloses that the tool deletes an item, restricts to unpaid/unissued bills, and returns a confirmation or error message. However, it does not state whether the deletion is permanent, any permission requirements, or how the system handles edge cases like invalid invoice numbers or product IDs.

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 compact and front-loaded with the main purpose. It uses a clean Args/Returns structure, with no wasted words. Every sentence adds value, including the restriction on unpaid/unissued bills and the return behavior.

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?

Given the simple parameter set (two integers) and lack of output schema, the description provides sufficient context: the operation, the bill status restriction, and the return format. It does not explain edge cases or failure reasons in detail, but for this simplicity level, it is mostly 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 description coverage is 0%, so the description must compensate. It adds the constraint that prod_id must be a positive value, which is valuable. However, invoice_no is described only as 'Invoice Number of the bill,' which matches the schema's title but adds no new meaning. The parameter semantics are minimal but slightly enhanced by the positive-value constraint.

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 clearly states the tool's function: "Deletes an existing item from an unpaid/unissued bill." It uses a specific verb and resource, and distinguishes from sibling tools like discard_bill (which deletes the entire bill) and add_item_to_bill (which adds items).

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 implies the use case by stating it works on unpaid/unissued bills, but it does not explicitly mention when to use this tool versus alternatives like edit_bill_item_quantity or discard_bill. No exclusions or alternative references are provided.

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