get_invoice

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

With no annotations, the description carries the full burden. It discloses the key side effect—the PDF is downloaded and saved—and the return value, but it omits possible auth requirements, overwrite behavior, file location, and error handling.

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, front-loaded, and uses a clear Args/Returns structure. Every sentence earns its place without repetition.

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 one-parameter download tool, it covers the input source, expected format, and return value. It could becomplete with error-case or file-location detail, but nothing critical is missing for normal use.

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?

The schema only provides a title and type, while the description adds crucial meaning: the parameter is the paymentNumber returned by list_invoices, with concrete examples. This makes correct invocation much easier.

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 uses a specific verb and resource: 'Download a specific invoice PDF by payment number.' This clearly distinguishes it from list_invoices and other document-focused siblings like get_prescription.

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?

It tells the agent that payment_number should come from list_invoices, effectively routing the workflow: call list_invoices first, then get_invoice. It does not explicitly state when not to use it, but the context is clear for this narrow task.

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