Download Zip Of Specification Section Revisions

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

The description adds meaningful behavioral context beyond the annotations: it discloses that company_id/project_id default from config, that the tool 'acts on the zip and returns Procore's response', and it enumerates common failure HTTP statuses (401, 403, 404) with their causes. This goes beyond the simple readOnlyHint/destructiveHint flags and helps the agent anticipate errors. No contradiction with annotations; readOnlyHint=false aligns with the POST endpoint.

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 concise and front-loaded with the primary action. It includes endpoint and API version details at the end, which is structured and useful. The phrase 'Acts on the zip and returns Procore's response for the operation' is vague and adds little value, slightly detracting from conciseness. Overall, every sentence earns its place except that minor ambiguity.

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?

For a tool with no output schema and moderate complexity, the description covers the core purpose, required parameters, defaulting behavior, and common error cases. It does not describe the response format or the effect of has_public_markup in the description, but the schema covers has_public_markup. It could be more complete by explicitly differentiating from single-revision downloads, but it is largely sufficient for 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?

The schema already provides descriptions for all four parameters (100% coverage), so the baseline is 3. The description adds the defaulting behavior for company_id/project_id, which is useful extra semantics. However, it merely repeats the required parameter list and does not clarify the optional has_public_markup parameter beyond what the schema states. This is adequate but not a significant enrichment.

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 'sends an url to download zip of a collection of specification section revisions', identifying the verb (send/download) and resource (specification section revisions). It distinguishes from sibling download tools (e.g., single PDF or individual revision) by mentioning 'collection' and 'zip', though the phrasing 'sends an url to download zip' is slightly awkward. It does not explicitly name a sibling alternative, but the resource scope is evident.

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 useful context by noting that company_id and project_id default to procore_set_config values when omitted, and it lists required parameters. However, it does not explain when to use this tool versus the sibling download tools (e.g., download_single_pdf_of_specification_section_revisions, download_specification_section_revision), nor does it state any exclusions or alternative scenarios. Thus, usage guidance is implied but not explicit.

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