Recycles A Receipt.

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

The behavior is inconsistently described: it first says the receipt can be restored from the recycle bin, then claims 'Permanently removes... This cannot be undone.' This is a fundamental contradiction about reversibility. Though it adds error-payload details and state restrictions, the conflicting statements about whether deletion is soft or permanent severely undermine transparency.

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 longer than needed and contains redundancy: 'Confirm the target id with the matching show or list tool before calling' and 'id must identify an existing parent record — resolve it with the matching list tool first' repeat the same instruction. There is also a garbled phrase 'Permanently removes the recycles a receipt,' and the conflicting statements make the structure confusing rather than tidy.

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 prerequisites, an important state constraint (Final receipts cannot be recycled), default parameter behavior, and likely error statuses. However, it lacks any mention of the return value (e.g., 204 No Content), which matters given there is no output schema. The internal contradiction also leaves uncertainty about the operation's actual effects, so completeness is only moderate.

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% with accurate parameter descriptions, so the baseline is 3. The description adds useful context about resolving id via a list tool and defaulting company_id/project_id, but it also states these are required parameters and then says they default when omitted—a direct contradiction with the schema and itself. This inconsistent guidance reduces the value of the added semantics.

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 opener 'Performs a soft delete (recycle) of the receipt' clearly identifies the action, but the later statement 'Permanently removes the recycles a receipt. This cannot be undone' directly contradicts the soft-delete semantics, making the tool's core purpose ambiguous and misleading. The resource and verb are initially specific, but the internal contradiction downgrades clarity.

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 context: confirm the id with the matching show/list tool, receipts in Final state cannot be recycled, and company_id/project_id default to procore_set_config values. It also lists common error scenarios. While it doesn't name alternative tools, the guidance on prerequisites and exclusions makes usage conditions clear.

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