get_attachment

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

With no annotations, the description carries the full behavioral burden. It discloses that the tool writes to the filesystem, explains output_path constraints, and mentions the return value. However, it omits important side effects such as whether existing files are overwritten, whether directories are created, and whether authentication or prior fetching of message/attachment metadata is required.

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 two sentences with no filler. The primary action is front-loaded, output_path rules are compactly stated, and the return value is mentioned. Every sentence contributes essential information.

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?

The description covers the core write behavior, path constraints, and return value, and an output schema exists to document return structure. But it lacks context about how to obtain valid account/message/attachment identifiers, whether downloads are overwrite-safe, and what download_root itself is. These gaps matter for correct invocation in an agent workflow.

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 0%, so the description must compensate. It adds meaningful semantics for output_path, including bare filename versus absolute path behavior. However, account, message_id, and attachment_id remain undocumented beyond their names; their formats and relationships are left to inference.

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: 'Write an attachment under download_root.' It clearly distinguishes this tool as the attachment-download operation among siblings like get_message and messages_list, and specifies the output location.

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 about when to use this tool versus alternatives, nor any exclusions or prerequisites. The intended use is implied by the name and parameters, but the description never explicitly routes the agent away from similar tools or states when this tool is the right choice.

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