delivery_notes_bulk_convert

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

No annotations provided, so the description carries the burden. It discloses the key mutation behavior: creates one invoice combining all lines and marks all delivery notes as invoiced. It doesn't describe what happens to the delivery notes beyond marking them invoiced, or what the invoice response contains, but the core side effects are stated.

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?

Three sentences, zero waste. Front-loaded with the primary action, then constraints, then effect. Every sentence carries distinct information.

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 description covers the operation, constraints, and side effects well. It doesn't explain error behavior when preconditions fail (e.g., mismatched clients), but with heavy schema coverage and no output schema, it's reasonably complete for a bulk operation. No explicit return-value info is needed since there's no output schema, though the implications for unsupported combinations could add value.

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% with good descriptions for both parameters (ids and companyId). The description adds the constraint context (same client, same currency) that affects which ids are valid, which is useful, but the schema already documents parameter meaning. Baseline 3 is appropriate.

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?

Clear verb+resource: 'Convert multiple issued delivery notes into a single invoice.' The scope is well-defined (bulk conversion, single combined invoice) and it clearly distinguishes itself from siblings like delivery_notes_convert (which presumably handles one) and proforma_invoices_convert.

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?

States the preconditions explicitly: all delivery notes must be issued, have the same client, and use the same currency. That's strong context for when to use this tool. It doesn't name an alternative explicitly, but the bulk-vs-single distinction with delivery_notes_convert is implied clearly enough.

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