invoices_attachments

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns base64-encoded data with MIME type, which is useful behavioral info. However, it doesn't mention size limits, whether downloads are reversible/safe (it's a read operation but not stated), or error handling for missing/unavailable attachments. Basic transparency, not necessarily full coverage.

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 tight sentences covering function, return format, parameter sourcing, and supported file types. Zero filler, front-loaded with the core action, and every sentence adds specific value.

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 straightforward download retrieval tool with 3 well-documented parameters and no output schema, the description is reasonably complete. It covers the essential workflow (how to get attachment IDs, what's returned) and is consistent with the invoice attachment ecosystem. Could mention error conditions or how to handle the base64 response, but this is adequate for the tool's complexity.

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%, so the schema documents all parameters. The description adds value by explaining the relationship between attachmentId and the invoices_get attachments array, and the companyId parameter has a clear default behavior described in the schema itself. The description meaningfully connects the parameters to the surrounding workflow.

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 it downloads a file attachment from an invoice, with specific details on the return format (base64-encoded binary data with MIME type) and supported file types. It's clearly distinguishable from siblings like invoices_pdf and invoices_xml which generate or export documents, while this tool retrieves attached raw files.

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 provides clear guidance on where to obtain the required attachmentId (from invoices_get 'attachments' array), which is a practical pointer. It names the source tool for UUIDs but doesn't explicitly state when to use this vs alternatives like invoices_pdf or exports_download, so some exclusion guidance is missing but the usage context is clear.

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