Bulk Update Project Observation Templates

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

The description goes well beyond the annotations, disclosing atomic validation ('if any fails, nothing is written'), the 422 error response listing offending IDs, parameter payload nesting ('nested under observation_template'), defaulting of project_id, success return value, and common error statuses (401/403/404). This is substantial behavioral context not present in the structured fields.

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 information-dense with no fluff: every sentence adds value (purpose, validation, usage preference, parameter handling, return, error codes, endpoint). It is slightly longer than necessary (the error code list and endpoint metadata could be trimmed), but it remains well-structured and front-loaded.

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?

Without an output schema, the description compensates by stating the successful return value. Combined with annotations and detailed schema, it covers the mutation's atomicity, error behavior, parameter semantics, and defaults. A minor gap is not explicitly contrasting with the similar company-level bulk update tool, but overall it is complete for an agent to select and invoke 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?

Schema coverage is 100% with detailed descriptions, so the baseline is 3. The description adds meaningful semantics by explaining that fields are passed as top-level arguments but nested into the payload, and by clarifying that project_id can be omitted due to procore_set_config defaulting—important context beyond the schema.

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: 'Applies the same attribute changes to several Project Observation Templates in one request.' This clearly distinguishes the bulk operation from single-record updates and from the company-level sibling (bulk_update_company_observation_templates) via the word 'Project.'

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?

Explicit guidance is given: 'Prefer this over repeated single-record calls when handling many project observation templates at once.' It also notes project_id defaults from procore_set_config, which helps decide when to omit it. However, it does not explicitly contrast with the company-level bulk update sibling, which would make the guidance even stronger.

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