Download Chat Attachment

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

Annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) are consistent with the description, so no contradiction. The description adds genuine value beyond annotations: it discloses the side effect of writing to local disk and the mode-dependent return semantics (local path in stdio vs temporary URL with a 1-hour expiry in HTTP), which the annotations do not convey.

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?

Two compact sentences carry all essential information with no filler. The core function is front-loaded in the first sentence, and the mode-specific details occupy the second. Every clause earns its place.

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 output schema exists to cover return values, and annotations cover the safety profile, lowering the burden on the description. The mode-specific behavior disclosure is a meaningful addition. Remaining gaps are the undocumented required user_google_email parameter and lack of error-behavior guidance (e.g., out-of-range attachment_index or messages with no attachments), but these are minor given the structured coverage.

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 67%, and the two documented parameters (message_id with a concrete example, attachment_index with default semantics) are well described. However, the required parameter user_google_email has zero documentation in both the schema and the description, and the description does nothing to compensate for this gap. With one required param unexplained, the agent cannot confidently construct valid calls.

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 states a specific verb ('Downloads'), resource ('attachment from a Google Chat message'), and outcome ('saves it to local disk'). It clearly distinguishes this from sibling tools like get_gmail_attachment_content (Gmail domain) and get_drive_file_download_url (URL only, not a download) by explicitly scoping to Google Chat.

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?

The description provides operational context by explaining stdio vs HTTP mode return behavior, which helps the agent know what to do with the result. However, it never explicitly states when to use this tool versus similar alternatives such as get_gmail_attachment_content or get_drive_file_download_url; the routing is left to inference from the Chat domain in the name and description.

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