Delete Custom Field

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

Even with annotations indicating destructive behavior, the description adds critical context: the deletion is permanent ('cannot be undone'), a repeat call returns 404, and failures come back as an error payload with HTTP status codes (401, 403, 404). It also documents the company_id default behavior via procore_set_config. This far exceeds the annotations and informs the agent of side effects and error handling.

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 lengthy but every sentence carries essential information: the action, prerequisite steps, default behavior, permanence, error reporting, required parameters, and endpoint. It is well-organized and front-loaded with the core action, though it could potentially be tightened by removing the endpoint line since the schema already indicates URL path parameters. No wasted words overall.

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, the description is highly complete. It covers how to prepare (confirm id via list/show tools), what happens on success (permanent deletion, 404 on repeat), and how failures manifest (error payload with 401/403/404). It also provides the API endpoint and required parameters, making the tool fully invocable and safe to use.

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 input schema already covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds valuable semantics beyond the schema: company_id defaults to the value set by procore_set_config when omitted, and field_id must be resolved via the matching list tool first. This practical guidance improves parameter understanding.

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 'Deletes a Custom Field from a company', which is a specific verb + resource + scope. It distinguishes itself from sibling delete tools by specifying the company-level custom field and including the exact API endpoint, making the tool's purpose unambiguous.

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 explicit usage guidance: it instructs to 'Confirm the target id with the matching show or list tool before calling' and 'field_id must identify an existing parent record — resolve it with the matching list tool first.' This clearly tells the agent what to do before invoking the tool and points to alternative lookup tools.

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