download_attachment

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

With no annotations at all, the description carries the full burden and handles it well. It labels the operation as read-only, warns that it writes a file locally, explicitly says it will not create directories, and explains the security rationale along with the FDS_MCP_DOWNLOAD_DIR confinement option. This is substantive behavioral context beyond the schema or annotations.

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 one-sentence purpose is front-loaded and the Args list is terse. The second paragraph is longer, but it earns its length by explaining a real path-injection risk and the recommended confinement mechanism, so it is not padding.

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 simple two-parameter download tool, the description covers purpose, input source, directory preconditions, and safety configuration. It omits details like return values or overwrite behavior, but those are minor for a download operation and no output schema exists to supply them.

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%, and the description fully compensates: attachment_id is explained as the numeric id from list_attachments, and target_dir is explained as an existing local directory with a usage constraint. Both required parameters receive meaning beyond their bare types.

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 states the verb, resource, and destination clearly: 'download one attachment into a local directory.' It also identifies the attachment_id source as list_attachments, so an agent can distinguish this tool from sibling listing and request tools without ambiguity.

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 explicit preconditions: target_dir must already exist, and the tool will not create a path. It also points to attachment_id as coming from list_attachments, which tells the agent where to get its input. It does not name alternatives, but no sibling tool performs the same download function, so the preconditions are sufficient guidance.

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