List Attachments

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

Adds valuable context beyond annotations: company_id default behavior, error payload with common HTTP statuses (401/403/404), and the requirement that asset_id references an existing parent. However, the claim that it 'Returns a single JSON object describing the attachment' contradicts the opening 'list' and likely actual array response, undermining transparency and potentially misleading the agent.

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 reasonably sized and front-loads the core purpose, but includes redundant statements ('Read-only — it changes nothing' duplicates annotations; 'Required parameters' duplicates the schema) and the contradictory 'single JSON object' sentence adds noise rather than value.

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 covers purpose, prerequisites, and error behavior, but omits pagination and sorting behavior for a list endpoint that has page/per_page and sort parameters. It also provides an inaccurate return-type statement ('single JSON object') instead of clarifying the expected list/array response, which is critical since there is no output schema.

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?

Input schema covers 100% of parameters, so baseline is 3. The description adds meaning about company_id defaulting to procore_set_config and the need to resolve asset_id first, which goes beyond the schema. However, the default statement for an explicitly required parameter creates a contradiction with the schema's required list, confusing parameter usage.

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 'Returns a list of attachments for a given asset,' identifying a specific verb and resource. However, later statements ('Use this when you already know which attachment you want' and 'Returns a single JSON object describing the attachment') conflict with the list semantics, creating some ambiguity about the tool's exact purpose.

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?

Provides explicit when-to-use guidance ('Use this when you already know which attachment you want and need its full field set') and a clear prerequisite ('asset_id must identify an existing parent record — resolve it with the matching list tool first'). It does not name alternative tools for project-scoped or asset-type scoped attachments, so it lacks explicit exclusions.

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