Download All Company-Level Email Attachments

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds valuable behavioral details: it states the return format (JSON with file or download URL), explicitly says it changes nothing in Procore, and outlines error payloads with common HTTP statuses (401, 403, 404). It also discloses the prerequisite that communication_id and email_id must reference existing parent records and the company_id default behavior.

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 front-loaded with the main purpose and includes many useful details, but it is somewhat lengthy and contains redundancy (e.g., 'Required parameters' repeats schema information). The phrase 'and need its full field set' is confusing and could be trimmed without losing meaning.

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 is highly complete for a tool with no output schema: it covers purpose, usage prerequisites, return type, read-only behavior, error handling, and the exact API endpoint. This provides an agent with enough information to invoke the tool correctly and understand likely outcomes.

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 100% with basic identifier descriptions, so baseline is 3. The description adds meaningful context by explaining company_id defaults to procore_set_config when omitted and that communication_id/email_id must identify existing parent records. However, there is an inconsistency: the schema marks company_id as required, yet the description implies it can be omitted, which could confuse an agent.

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 clearly states the tool returns a URL to download all email attachments as a .zip for company-level communications. However, the subsequent phrase 'which company-level email attachment you want and need its full field set' introduces ambiguity about whether this downloads a single attachment or all attachments, and 'full field set' is more typical of a show operation than a download.

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 clear usage context: use when you already know the target email, resolve IDs with the matching list tool first, and company_id defaults from procore_set_config. It does not explicitly name alternative sibling tools or state when not to use this tool, but the context is sufficient for selection.

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