Procore MCP Server

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

No annotations are provided, so the description carries the full burden. It states 'Bulk Update Hazards' and includes an HTTP PATCH method, implying a mutation operation. However, it doesn't disclose critical behavioral traits: whether it's idempotent, what permissions are required, if it's destructive (e.g., overwrites data), rate limits, or error handling. The PATH suggests it updates hazards for a company, but the description lacks details on side effects or response format.

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—three short phrases without fluff. It front-loads the tool name and adds contextual tags and the HTTP path. However, it could be more structured by separating purpose from technical details. Every sentence earns its place, but it's slightly terse, missing explanatory value that would enhance clarity without adding waste.

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 complexity (a bulk mutation tool with 3 parameters, no annotations, and no output schema), the description is incomplete. It doesn't explain the tool's behavior, output, or error conditions. For a mutation tool that likely modifies multiple hazards, the description should cover aspects like atomicity, validation, or return values. Without annotations or output schema, the description fails to provide enough context for safe and effective use.

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 description coverage is 100%, with clear parameter descriptions: 'company_id' as a unique identifier, 'ids' as an array (though items are empty), and 'active' as a boolean flag. The description adds no parameter semantics beyond the schema—it doesn't explain what 'ids' should contain (e.g., hazard IDs) or how 'active' affects hazards. With high schema coverage, the baseline is 3, as the schema does the heavy lifting, but the description doesn't compensate for gaps like the vague 'ids' items.

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 'Bulk Update Hazards' restates the tool name and adds a category tag '[Project Management/Incidents]' and HTTP method/PATH 'PATCH /rest/v1.0/companies/{company_id}/hazards/bulk_update'. It specifies the action ('Update') and resource ('Hazards') but is vague on scope—'bulk' implies multiple hazards, but it doesn't clarify what 'update' entails (e.g., which fields). It distinguishes from siblings by focusing on hazards, but lacks specificity compared to tools like 'update_hazard' (singular).

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 no guidance on when to use this tool versus alternatives. It mentions 'bulk_update' but doesn't explain prerequisites (e.g., needing hazard IDs), when to choose it over single updates, or constraints. Without such context, an agent must infer usage from the name and schema alone, which is insufficient for informed selection.

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