Destroy Witness Statement

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

The description discloses important behavioral traits: irreversibility, 404 on repeat, error payloads with common HTTP statuses, and project_id defaulting. However, it internally contradicts itself by saying 'Sends to the Recycle Bin' and then 'Permanently removes... cannot be undone', which could mislead an agent about recoverability. This inconsistency, while not contradicting annotations, reduces clarity.

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 detailed and front-loaded with the action, but includes some repetition (e.g., 'matching list tool' mentioned twice) and redundant elements like the full endpoint path. It is structured logically, but could be tightened without losing essential information.

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?

For a destructive tool with no output schema, it covers error handling, idempotency behavior, and prerequisite steps, which is good. However, the Recycle Bin vs. permanent deletion ambiguity leaves incomplete information about whether the resource can be recovered, and it does not mention incident_id handling. Overall, adequate but not fully 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%, but the description adds meaningful context beyond the schema: project_id defaults to the configured value, and id must identify an existing parent record resolved via list tool. It reinforces required parameters, which is helpful. The optional incident_id is not mentioned, but the description still adds value over schema alone.

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 a destructive action on a witness statement with 'Sends... to Recycle Bin' and 'Permanently removes'. The verb 'destroy' and resource 'witness statement' align with the tool name, and the endpoint details clarify the operation. However, the dual references to 'Recycle Bin' and 'Permanent removal' introduce slight ambiguity about the final state.

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 gives explicit preconditions: confirm the target id with show/list tools and resolve the id via list tool first. It also notes project_id defaults from procore_set_config, providing context on when to use. It does not explicitly name alternatives but references 'matching show or list tool' sufficiently for an agent to understand prerequisites.

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