Retrieve Recycled Witness Statement

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

The description discloses partial-update semantics ('send only the fields you intend to change'), the project_id defaulting behavior, and error payload structure. However, it never explicitly states that the operation restores the recycled witness statement (i.e., moves it out of the recycle bin), which is a significant side effect. It also internally contradicts itself by saying `project_id` defaults when omitted but later listing it as required.

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 and contains useful information, but it repeats itself (e.g., 'Required parameters: project_id, id' after saying project_id defaults) and includes contradictory guidance. The structure front-loads the purpose but then diverges into update semantics and error handling, making it less focused than it could be.

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?

There is no output schema, so the description must fully explain return values and side effects. It mentions returning the modified statement but fails to clarify that the record is restored (removed from recycle bin). The absence of any request body in the schema is a major gap, and the description doesn't list the editable fields or explain whether a restore occurs even without changes.

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% for the three listed parameters, but the description's instruction to 'send only the fields you intend to change' implies a request body that is entirely absent from the schema. The optional `incident_id` is not explained, and the contradictory statements about `project_id` being both defaulted and required further confuse parameter handling. The description does not compensate for the missing body fields.

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 states the resource and action ('retrieves a specific Recycled Witness Statement from the recycle bin'), but the verb 'retrieve' is ambiguous—it could mean fetch or restore. The endpoint PATCH /restore and the mention of modifying fields suggest a restore-with-update operation, which is never explicitly stated. This ambiguity is especially problematic given the sibling `show_recycled_witness_statement`, which likely handles simple retrieval.

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 useful prerequisites: resolve `id` with the matching list tool first, and it explains common error statuses (401, 403, 404). It also notes that `project_id` defaults to the value from `procore_set_config`. However, it does not explicitly say when to use this tool instead of `show_recycled_witness_statement` or other alternatives, nor does it state when NOT to use it.

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