Delete Observation Item

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

The description first says it sends to the recycle bin, but then claims 'Permanently removes' and 'cannot be undone,' contradicting the soft-delete nature (as sibling restore tools exist). This could mislead the agent about reversibility. It does provide useful error status info, but the misleading permanence claim is significant.

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 with useful details, but it repeats the id-resolution guidance twice ('Confirm the target id ...' and 'resolve it with the matching list tool first') and contains an internal contradiction between 'recycle bin' and 'permanently removes.' The required-parameters sentence is redundant given the schema.

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?

It covers prerequisites, error codes, and idempotency, but fails to mention that the item is actually recoverable from the recycle bin via restore tools, and doesn't describe what a successful response looks like. For a delete tool with no output schema, this is a noticeable gap.

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 value beyond the bare URL-parameter labels: project_id defaults to procore_set_config when omitted, and id must be resolved via a list tool first. This gives the agent operational detail not found in 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 immediately states it 'Sends the specified Observation Item to the recycle bin,' providing a specific verb and resource. The endpoint and API reference further clarify it is a delete operation for observation items, clearly distinguishing it from other delete sibling tools.

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?

It explicitly instructs to confirm the target id with the matching show or list tool before calling, and explains the project_id default behavior. It doesn't explicitly list when not to use, but the 'resolve id first' guidance gives adequate context for an agent to use it safely.

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