Create Attachment

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

The description claims 'The operation is idempotent,' but the annotations set idempotentHint: false. This is a direct contradiction. Additionally, the description does not address the openWorldHint: true annotation, which suggests unknown side effects. This is a serious inconsistency that undermines trust in the tool's 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 well-structured and front-loaded with the core purpose, followed by critical operational details (idempotency, defaults, error handling, required params). It is slightly verbose with a vague phrase 'Acts on the attachment,' but overall every major sentence contributes useful information. The explicit endpoint and API reference are helpful but could be considered repeated from the tool name.

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 essential context: how to resolve incident_id, the project_id default, error scenarios with common HTTP statuses, and the required parameter list. It provides enough guidance for correct invocation despite the absence of an output schema. The idempotency contradiction and lack of mention about run_configurable_validations (beyond schema) slightly reduce completeness, but overall the description is thorough.

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%, so the baseline is 3. The description adds meaningful value by explaining that project_id defaults to procore_set_config, incident_id must identify an existing parent record, and attachment supports both multipart and upload-ID-based formats. This goes beyond the schema's basic descriptions, particularly for the attachment parameter, which is enriched with the multipart/upload-ID distinction.

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's function: 'Uploads a file attachment to the specified incident.' This specific verb+resource combination distinguishes it from generic attachment tools and identifies the target parent (incident). The endpoint and API path further reinforce the purpose, leaving no ambiguity about what this tool does.

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 operational context: it supports multipart and upload-ID-based uploads, project_id defaults from procore_set_config, and incident_id must be resolved via a list tool first. While it doesn't explicitly state when not to use this tool or name alternative tools, the incident-specific scope and resolution guidance effectively steer usage. A minor deduction for lacking explicit exclusions or alternative tool mentions.

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