billy_update_invoice

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

With no annotations, the description carries full burden. It discloses the confirm dry-run mechanism and the need for a second call to execute. It does not cover other behavioral aspects like error handling or auth, but the key behavioral trait is well explained.

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 brief (one sentence plus a note on confirm), but the key information is front-loaded. The dry-run explanation is essential and well-placed. Slightly more structure could improve readability.

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?

There is no output schema, and the description does not mention return values or side effects. The dry-run preview is implied but not detailed. Given the complexity of updating an invoice with a nested patch object, more completeness would be helpful.

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?

Only 33% of parameters have schema descriptions (confirm only). The description adds value for confirm but does not explain the 'id' or 'patch' parameters. 'patch' is a free-form object, yet the description gives no guidance on typical fields or structure.

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 'Update an existing invoice' with a specific verb and resource. It distinguishes from sibling tools like billy_approve_invoice and billy_delete_invoice by labeling it as a WRITE operation requiring confirm:true.

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 explains the critical confirm parameter and the dry-run behavior, guiding safe usage. It implicitly distinguishes from other invoice tools, but could be more explicit about when to use update versus approve or delete.

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