Create Unified Upload

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

Beyond annotations, the description discloses the multi-step workflow: upload to returned signed URLs, then complete via PATCH, and mandatory polling of upload status. It also warns that calling again creates another record (non-idempotent), explains default behavior of company_id/project_id, and details error payloads with common HTTP statuses (401, 403, 404). These add significant behavioral context not present in annotations.

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 long but dense with actionable information: purpose, response structure, workflow, defaults, duplicate-record warning, error handling, required parameters, and API reference. Each sentence adds value, though the structure could be tighter. It is front-loaded with the core purpose, so agents get the essential info early.

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 the tool's complexity (12 params, nested objects, multi-step workflow, no output schema), the description is remarkably complete. It covers what the tool does, the response format (segments array with url, url_expires_at, headers), the required follow-up actions (PATCH, polling), error semantics, defaults, and the exact API endpoint. An agent has enough information to invoke and complete the workflow without external documentation.

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%, but most schema descriptions are generic placeholders like 'the md5 for this File Access & Storage operation'. The description adds value by listing required parameters and explaining the default behavior of company_id/project_id, which is not in the schema. However, it does not clarify the meaning or usage of optional params like md5, sha256, analytics, url_expires_in, or custom_metadata beyond what the schema provides, so it partially compensates but leaves gaps.

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 opens with a specific verb and resource: 'Creates a project-level file upload for the given company and project.' It clearly distinguishes from sibling tools like create_unified_company_upload by scoping to project-level, and explains the unified support for standard and segmented uploads. The endpoint is also included, reinforcing the precise action.

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 states when to use it (project-level unified uploads) and implicitly differentiates from company-level alternatives via 'project-level'. It also notes that company_id/project_id default from procore_set_config, aiding invocation. However, it does not explicitly name alternative tools for comparison (e.g., create_project_upload) or state when not to use it, just enough context to infer.

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