get_attachment

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses the actual return shape (inline text vs. a saved path), the risky-file policy (flagged and blocked unless allow_risky), and the safety wrapper around results. The untrusted-content warning tells the agent how to treat the payload, which annotations cannot express. The disk-save side effect is disclosed rather than hidden, so it does not contradict readOnlyHint on the source data.

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 tight sentences, front-loaded with the core action and then the conditional outcomes, the risky-file rule, and the untrusted-data caveat. No filler or restatement of the tool name.

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?

With no output schema, the description correctly carries the return-value burden by explaining the text-versus-path result and the UNTRUSTED wrapper. Minor gaps remain around failure modes (missing part number, oversized attachments) and whether saved paths are cleaned up, but the essentials for a correct call are present.

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 80%, so the schema already documents account, attachment, save, and allow_risky. The description reinforces 'save to true to always save' and the allow_risky escape hatch, but adds little syntax or format detail beyond what the property descriptions state. Baseline 3 is appropriate.

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 first sentence names a specific verb and resource ('Gets an attachment of an email') and immediately points to the sibling that produces the required identifier ('get_email lists them with their part number'). An agent can distinguish this from get_email without opening either schema.

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 clear conditional guidance: text and text-containing archives come back as text, everything else is saved and a path returned, and 'save' forces disk output. It also names the prerequisite source for the part number (get_email). It stops short of explicit exclusions such as when not to fetch an attachment or what to do if get_email does not list it.

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