Update Specification Section Revision

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description adds substantial behavioral detail: it specifies HTTP methods (PUT/PATCH), success status (200 OK), validation error structure (422 with error.code, reason_code, failures object), and common auth/permission errors (401, 403, 404). This significantly enhances the agent's ability to anticipate and handle responses.

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 long paragraph but well-structured with bold labels for HTTP methods, success, and error sections. Most sentences add value, though the successful response is mentioned twice ('Returns 200 OK with the updated revision' and 'Returns the modified specification section revision on success'), creating minor redundancy. Overall, it is dense but efficiently organized.

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?

With no output schema, the description compensates by describing the 200 OK body, full validation error format, parameter defaulting, and endpoint. It also covers prerequisites (resolve id with list tool), common failure statuses (401, 403, 404), and partial update behavior. This provides complete guidance for correct invocation without needing 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?

The schema provides only terse descriptions for five parameters, but the description adds meaning by stating that specification_section and specification_section_revision must be included in the request body, explaining default behavior for company_id/project_id, and clarifying partial update semantics. This goes beyond the schema and helps the agent construct correct requests.

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 'Updates a specification section revision,' a specific verb+resource statement that clearly identifies the tool's function. It distinguishes this singular update tool from siblings like 'bulk_update_specification_section_revisions' and 'destroy_specification_section_revision' by focusing on a single revision update with PUT/PATCH methods and a specific endpoint.

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?

It provides clear usage context: send only fields to change, omitted fields keep current values, and resolve id with the matching list tool first. It also notes that company_id/project_id default to procore_set_config, which is practical guidance. However, it does not explicitly exclude when to use bulk_update or other alternatives, though the singular resource and required id make the intended scope evident.

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