Request Attachment Text

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

The annotations already state idempotent=true, destructive=false, and readOnly=false; the description adds value by explaining the 24-hour cached-reuse behavior and the mailbox.read authorization requirement. It also discloses the OCR limitation and the failed-extraction path, which annotations cannot convey. The instruction to 'check status and outcome' stays vague about where or how, but the presence of an output schema offsets that.

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?

Four short sentences, with the core action and the size and cost constraint front-loaded, followed by the authorization, caching, and fallback notes. Every sentence carries operational information, though 'at no extra charge' reads as promotional filler and the size figure adds ambiguity rather than clarity.

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 four-parameter tool with a full output schema, the description covers authorization, cost, caching, limits, and failure handling, so the agent can call it correctly. The remaining gaps are sibling disambiguation and the ambiguous byte limit, which are notable but not blocking.

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 baseline is 3, and the description does not clarify any parameter beyond the schema. The phrase 'up to 7500000 bytes' is potentially misleading next to a max_bytes parameter whose maximum is 1048576, and the description never explains that the 7.5 MB figure is presumably the attachment-size limit; an agent could conflate the two.

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 names a specific verb and resource ('Extract readable text from an attachment'), so the agent knows exactly what the tool does, and it adds a scope limit and cost note. It does not, however, distinguish this tool from close siblings such as mailbox_get_attachment_text and qubrics_mailbox_request_attachment_text, so an agent cannot tell the request and immediate-get variants apart from the description alone.

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 gives useful operating guidance: the required mailbox.read scope, the fact that OCR is unavailable, and the fallback to the original download when extraction cannot complete. It never states when to choose this over the existing get_attachment_text sibling or what error conditions should trigger a retry rather than a fallback, so the when-to-use decision is only implied.

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