Show Recycled Injury

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds valuable behavioral details: "Read-only — it changes nothing in Procore," failure error payloads with common HTTP statuses, the project_id default behavior, and deprecated response keys. It also clarifies the response structure is identical to Show Injury but for a soft-deleted record. No contradiction with annotations.

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 dense but every sentence adds value: purpose, response comparison, deprecation note, usage context, defaults, error handling, required parameters, API path, and endpoint. The first sentence is clear and front-loaded. It is longer than ideal, but the complexity of the tool and the need for error/deprecation details justify the length.

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 does well by stating the return type (single JSON object), deprecating keys, error behavior, and referencing the Show Injury endpoint for the full response structure. It also lists required parameters and the API location. It could be more complete by enumerating response fields, but the reference to Show Injury and the emphasis on 'full details' compensates for the absence of an output schema.

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 100% descriptions for parameters. The description extends meaning by explaining that project_id defaults from procore_set_config when omitted and that id must reference an existing record 'resolve it with the matching list tool first.' However, the statement about project_id default contradicts the schema's 'required' flag, which could confuse agents. The optional incident_id is not elaborated 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 "Returns the specified recycled injury record with full details," clearly stating the action and resource. It also distinguishes from the non-recycled Show Injury endpoint by noting it represents a soft-deleted injury and explicitly states when to use it: "Use this when you already know which recycled injury you want and need its full field set."

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 explicit usage guidance: "Use this when you already know which recycled injury you want and need its full field set" and "id must identify an existing parent record — resolve it with the matching list tool first." It also notes the project_id default from procore_set_config, which helps agent know when it can omit it. It differentiates from show_injury by describing the soft-deleted context.

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