save_attachment

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

Annotations are all false, so they carry no safety profile and the description takes the full behavioral burden — and does so thoroughly. It discloses limits (25 MB decoded), side effects ('an existing file is never overwritten and no directories are created'), output_posture ('return only its path, keeping the bytes out of the conversation'), platform restriction ('not available on Windows'), and an explicit security directive that all returned content is untrusted data. No contradiction with the annotations (write op aligns with readOnlyHint=false).

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 sentences, each earning its place: purpose/limit, usage route, path/file-behavior caveats, trust warning. The security sentence is the longest but the list of untrusted fields is justified precision, not padding. Slightly dense but well front-loaded with the core operation.

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 5-param, all-required write tool with an output schema present and flat annotations, nothing an agent needs to call it correctly is missing: what it does, when to use it, size limit, path contract, no-overwrite/no-mkdir constraints, platform restriction, and handling of untrusted data. If anything, the output schema removes the need to describe the return value further.

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%, so per-parameter documentation already does the heavy lifting: uid comes from list_emails/search_emails, index from list_attachments/get_email, folder from list_folders, uidvalidity 'detects stale uids', and output_path's relative/absolute rules. The description adds modest value_: the 25 MB constraint and reinforces that output_path must not already exist. Baseline 3 is appropriate; the description supplements but does not compensate for a gap.

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 and resource: 'Write one attachment (up to 25 MB decoded) to a local file on the server's machine and return only its path.' It names the sibling it is not ('too large to read inline with get_attachment'), so an agent can distinguish save_attachment from get_attachment without opening either schema. A clear, distinct operation.

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?

Explicitly tells the agent when to choose this tool: 'Use this for attachments too large to read inline with get_attachment.' This both selects a condition and names the alternative, which makes the routing decision unambiguous. No other guidance is needed because every sibling (list_*, search_*, save_draft) serves a visibly different purpose.

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