Delete Bid Form Item

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds genuine value beyond them: 'Permanently removes the bid form item. This cannot be undone,' the repeat-call-returns-404 behavior, and a concrete error taxonomy (401 expired token, 403 missing permission, 404 unresolved id). There is no contradiction with annotations — the idempotentHint is consistent with the explained repeat-call semantics.

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 front-loaded and logically sequenced: purpose, preconditions, parameter defaults, destructive behavior, error codes, then API reference. It runs slightly long, and the 'Required parameters' line redundantly restates the schema, but nearly every other sentence contributes distinct value.

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 simple 3-param destructive tool with no output schema, the description is nearly complete: it covers verification preconditions, permanence, idempotency semantics, common failure codes, and the exact endpoint. The only notable omission is what a successful call returns (e.g., 200/204 versus null), though the error-payload framing implies success when no error payload is returned.

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?

With 100% schema coverage, the schema already documents all three parameter descriptions, setting a baseline of 3. The description adds the procore_set_config default for project_id, the requirement that bid_package_id and bid_form_item_id reference existing parent records, and the REST path mapping. Minor tension: the description says project_id defaults when omitted while the schema lists it as required.

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 opens with 'Delete single Bid Form Item,' pairing a specific verb with a precise resource and scope ('single'). This clearly distinguishes it from sibling deletion tools like delete_bid_form and delete_bid_form_section, which operate on larger aggregates.

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 concrete procedural guidance: 'Confirm the target id with the matching show or list tool before calling' and 'resolve them with the matching list tool first,' establishing a verify-before-delete workflow. It also explains project_id falls back to procore_set_config when omitted. However, it never names alternative deletion tools or states when NOT to use this tool, so the guidance is procedural rather than comparative.

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