List Attachments

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

The description adds useful behavioral context beyond annotations: company_id and project_id default to procore_set_config values, asset_id must reference an existing parent record, error payloads carry HTTP statuses (401/403/404), and it explicitly states the operation is read-only. However, it claims 'Returns a single JSON object' while the tool name and first sentence indicate a list, which is a significant behavioral misrepresentation that undermines trust.

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 moderately sized but includes redundant and contradictory elements. It repeats the required parameters (already in the schema) and contains the conflicting 'single JSON object' statement. The endpoint and error-handling details are useful, but the inconsistency and redundancy detract from conciseness. It is not overly verbose, yet not every sentence 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?

Given there is no output schema, the description should clearly explain the return value, but it ambiguously says both 'list' and 'single JSON object.' It does cover error handling, default values, and a prerequisite for asset_id, which is helpful. However, the lack of a clear return format and the failure to differentiate from similar attachment/sibling tools make it incomplete for an agent to reliably invoke and interpret results.

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?

The schema already provides 100% coverage of all 7 parameters, so the baseline is 3. The description adds some extra value by noting that company_id and project_id default to values from procore_set_config, and that asset_id must identify an existing parent record. However, it does not elaborate on page, sort, per_page, or Accept-Language beyond their schema descriptions, and the contradictory return-type information does not help parameter understanding.

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 clearly states 'Returns a list of attachments for a given asset' with a specific verb and resource. However, it then says 'Use this when you already know which attachment you want' and 'Returns a single JSON object describing the attachment,' which contradicts the list nature and likely indicates a show operation rather than a list operation. This inconsistency muddles the tool's 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?

The description includes a usage hint ('Use this when you already know which attachment you want'), but it is misleading because the tool lists attachments, not fetches a single known attachment. It does not clearly distinguish when to use this tool vs. show_attachment_project or list_attachments_company, and no explicit alternatives or exclusions are given. The prerequisite to resolve asset_id with a list tool is useful but not enough to offset the confusion.

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