get_attachment

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

With annotations present (readOnlyHint=false), the description adds real behavioral context: the file goes to disk, its bytes are not pulled into the conversation, and content is delimited by a per-call 16-hex-tag marker pair that defends against injected marker text. That last point is essential for correct parsing and is not derivable from the annotations. It stops short of stating permissions or what happens on filename collisions.

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-loads the action and its landing directory in the first sentence; the marker rules follow because they govern how to read the result. Slightly longer than needed — 'its bytes are never read into this conversation' and the marker discussion could be tightened — but every sentence carries operational weight.

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 takes on the return-format burden and does it well by defining the marker boundary. The write-to-disk behavior is covered too. The remaining hole is the two undocumented required parameters, which an agent must guess at from context.

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 33% — only part_id is documented. The description never mentions folder or uid, so those two parameters carry no meaning from either the schema or the prose. With low coverage the description should compensate, and it does not.

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?

Specific verb (download) plus resource (one attachment) and the side effect (written to the configured download directory, location reported back). It is unmistakably distinct from get_email/get_thread/search_emails, which never touch attachment bytes.

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?

Usage is implied — you call it to retrieve an attachment — and the schema cross-references get_email for the part_id. But the description itself states no when-to-use condition, no prerequisite sequencing, and names no alternative; it never says how an agent obtains folder/uid/part_id.

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