Create Attachment

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

The description discloses several behavioral traits beyond the annotations: it returns the new id with HTTP 201, emphasizes that calling again creates another record (non-idempotent), explains failure responses with common HTTP status codes (401, 403, 404), and mentions the default for project_id from procore_set_config. These additions go beyond the readOnly/idempotent/destructive hints.

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 a dense single paragraph that is front-loaded with the core purpose. It contains some redundancy (e.g., restating required parameters that are already in the schema) but every sentence provides useful information about behavior, errors, or context. The structure is acceptable, though slightly verbose.

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 non-destructive create operation with no output schema. It covers the return value, HTTP status, error payloads and their common status codes, the prerequisite resolution of the parent record, the project_id default, and the API endpoint. Given the schema and annotations, this description fully equips an agent to select and invoke the tool correctly.

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?

Although schema coverage is 100%, the description adds meaningful semantics: project_id defaults to the configured value when omitted (despite being listed as required in the schema), witness_statement_id must resolve to an existing parent record, and attachment is described as a JSON body field for multipart upload. This adds context beyond the schema's basic parameter descriptions.

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 the tool creates an attachment for a specified Witness Statement, using a specific verb ('creates') and resource ('attachment for the specified Witness Statement'). It also includes the API endpoint and parent context, which distinguishes it from other attachment-related tools among the many siblings.

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: it says witness_statement_id must reference an existing parent record and instructs to resolve it with the matching list tool first. It does not explicitly name alternatives, but the reference to the list tool and the specific resource make usage circumstances clear.

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