List invoice attachments

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. However, the description adds no behavioral context beyond restating what the tool does — no mention of pagination limits, whether metadata or content is returned, or how this relates to the download/get siblings. For an operation with no output schema and no behavioral notes, the description leaves agents to guess at the return shape.

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?

Seven words, zero waste, and the key information is front-loaded. The description is exactly as long as it needs to be, a model of verbal economy. Every word earns its place.

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 simple list tool with a single required parameter and the safety profile covered by annotations, the description is minimally adequate. The biggest gap is the absence of any statement about the return shape (metadata vs. content), which matters more because no output schema exists. An agent is left inferring that 'list' means metadata-only, which is reasonable but unstated.

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 100%, establishing a baseline of 3. The description itself adds no parameter-level detail, and oddly, the most critical parameter (invoiceId) has the least helpful schema description ('Path parameter invoiceId' — a tautology). Page, pageSize, and query have genuinely useful schema descriptions. The description could have clarified the relationship between the parameters and the listing behavior but doesn't.

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 ('Lists'), resource ('file attachments'), and scope ('on an invoice'). The description is clear and the naming convention differentiates it from siblings like bokio_get_invoice_attachment and bokio_download_invoice_attachment. However, the differentiation is implicit via the word 'Lists' rather than explicit, so it doesn't quite earn a 5.

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?

No guidance is given on when to use this tool vs. alternatives. There's no mention of the distinction between listing attachments, getting attachment metadata, or downloading content, even though all three siblings exist. With siblings like bokio_download_invoice_attachment and bokio_list_invoices, an agent gets zero help selecting among them. The usage context is purely implied by the verb, which is not enough.

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