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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the auth prerequisite ('Cotlet API key with access to this app') and the structural shape of the response (header, lines, VAT per line, totals). It adds nothing on pagination or error behavior, so it clears the lowered bar but without depth.

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?

Front-loaded with the core noun phrase, then return contents, then usage, then prerequisite – a sensible ordering. There is mild redundancy between 'One invoice with its lines, VAT per line and totals' and 'Returns the header and lines of one invoice', which keeps it out of the top band.

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?

No output schema exists, so the description carries the burden and does so: it enumerates the header fields and per-line fields, states the auth requirement, and gives a usage cue. For a read-only single-entity lookup with one parameter, an agent has everything needed to call it correctly.

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% and the single parameter is documented as 'Invoice ID from list_invoices.', so the schema does the heavy lifting. The description lists the fields present on the returned invoice (relation, date, payment term, reference, line items) but adds no syntax, format or source detail for invoice_id itself. Baseline 3 applies.

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+resource ('Get invoice', 'One invoice with its lines') and enumerates the returned content, so an agent knows exactly what it retrieves. It does not explicitly name the sibling it contrasts with (list_invoices), though the singular framing and the schema's 'Invoice ID from list_invoices' make the distinction inferable.

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?

Gives a concrete usage context: 'Use it to check what an invoice contains before you book a payment on it.' That is a real when-to-use signal rather than filler. It stops short of 5 because it names no alternative or exclusion (e.g. when to use list_invoices or list_outstanding_invoices instead).

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