Create Injury

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

The description directly contradicts the annotations: annotations declare idempotentHint=false, but the description states 'The operation is idempotent.' This is a clear annotation contradiction, which per rubric must score 1. Additional behavioral details (error statuses, default behavior) are present but are overshadowed by the contradiction.

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 fairly long and somewhat disorganized. It contains a confusing, contradictory NOTE about deprecated keys, repeats 'Required parameters' at the end, and mixes deprecation warnings, payload mechanics, and error handling without clear sectioning. It is not concise, though it does front-load the primary action.

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?

The description covers many necessary aspects: required parameters, optional field groups, error handling statuses, validation flag, project_id default, and the endpoint. However, the idempotency contradiction and the ambiguous return statement ('returns Procore's response') leave gaps. For a tool with 27 parameters and no output schema, this is adequate but not complete.

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%, so the baseline is 3. The description adds some value by explaining top-level argument passing (nested under 'injury' in payload), the project_id default, and deprecation guidance. However, it contains a contradictory deprecation note (first says use body_part_ids, later says use affected_body_parts) and contradicts the schema by suggesting project_id can be omitted when it is required, undermining reliability.

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's purpose: 'Creates a new injury record associated with the specified incident.' This uses a specific verb (creates), a specific resource (injury record), and the relationship to incidents, distinguishing it from sibling tools like create_incident or update_injury.

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 clear usage context: it requires incident_id, explains optional field categories, mentions run_configurable_validations for custom validation, and explains the project_id default from procore_set_config. It does not explicitly name alternatives or when-not conditions, but the prerequisites and configuration guidance are solid.

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