Delete Waste Log

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

Even though annotations already indicate destructiveHint=true and idempotentHint=true, the description goes further by stating 'Permanently removes the waste log. This cannot be undone, and a repeat call returns 404.' It also discloses common failure scenarios (401, 403, 404) and their meanings, providing valuable operational context beyond the structured 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 not overly long. All sentences contribute useful information: purpose, prerequisites, irreversibility, failure modes, and endpoint details. The structure is logical, starting with the core action, then caveats, then error handling. Slight verbosity in repeating 'Required parameters' could be trimmed, but it is not excessive.

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 operation with no output schema, the description covers what to do before calling, what happens after (permanent removal, repeat 404), and how failures are returned. It also provides the exact API endpoint. The only missing element is an explicit statement of the success response format (e.g., 200 with no content), but this is often implied for deletes and is not critical given the error coverage.

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 covers both parameters with descriptions, and the description adds extra meaning: project_id defaults to the procore_set_config value when omitted (though this slightly contradicts the schema's required field) and id must identify an existing parent record resolved via the list tool. This addition enhances the understanding of parameter usage beyond the schema alone, but the required-project_id contradiction prevents a higher score.

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 begins with 'Delete single Waste Log,' which is a specific verb and resource, clearly distinguishing it from sibling tools like list_waste_logs, create_waste_log, and update_waste_log. The scope is unambiguous and matches the tool name exactly.

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 explicitly instructs to 'Confirm the target id with the matching show or list tool before calling' and to resolve the id with the matching list tool first, providing clear prerequisites and pointing toward alternatives. It also explains the project_id default behavior via procore_set_config, which gives context on when this tool can be used. However, it does not explicitly state when to avoid this tool (e.g., if deletion is not desired), leaving some implicit guidance.

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