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

With no annotations, the description carries the full burden and does meaningful work: it discloses atomicity ('All or nothing'), the 100-item cap, and the external side effect that send=true actually delivers invoices and returns pay links. Missing are permission requirements, what happens on partial validation failure, and the response shape when send=false.

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 short sentences, front-loaded with purpose and scope, then atomicity, then the send conditional. No filler or restatement of the name.

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 complex batch mutation with no annotations and no output schema, the definition covers atomicity and the send path's returned pay link but leaves the non-send return shape, error/rollback semantics, and per-field constraints unexplained. Adequate to attempt a call, not adequate to call confidently.

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% at the top level, so the description must compensate; it explains `items` (a job plus the worker's lines) and `send`, but says nothing about the nested memo, due_on, tax_rate_id, or unit_price_minor semantics. Some nested enum/boolean fields are documented in the schema itself, which partially offsets the gap.

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?

States a specific verb and resource plus scope: 'Create many invoices at once (up to 100), each from a job and the lines the worker wrote.' The batch framing and 'up to 100' immediately distinguish it from the single-invoice siblings invoices_create and invoices_createFromQuote.

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 batch framing implies when to use it (many invoices from jobs at once), and 'With send=true...' clarifies the optional behavior. However, no alternative is named explicitly (e.g. looping invoices_create) and there are no stated preconditions such as job status or shop permissions.

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