Delete Equipment Category (Deprecated)

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

Beyond the annotations, the description adds critical behavioral traits: 'Permanently removes the equipment category. This cannot be undone, and a repeat call returns 404.' It also details failure modes (401, 403, 404) and the deprecation schedule. This exceeds the annotation info and helps the agent understand consequences and expected errors.

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 delivers needed information: deprecation, prerequisites, destruction semantics, errors, and API reference. It is front-loaded with the core purpose. While it reads as a dense block of text, it is well-structured and not wasteful.

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 all necessary context: what the tool does, deprecation status, alternative discovery, parameter prerequisites, irreversibility, repeat-call behavior, error status meanings, and the exact API endpoint. It is fully complete for a delete operation, even without an output schema.

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, so the baseline is 3. The description adds useful context about id resolution ('id must identify an existing parent record') and error handling, but it also introduces a contradiction: it states 'Required parameters: company_id, id' yet says 'company_id defaults to the value set by procore_set_config when omitted.' This could confuse an agent about whether company_id is truly required, undermining the added value.

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 a specific verb and resource: 'Delete a specific Equipment Category.' It clearly identifies the tool's function and distinguishes it from sibling tools by naming the exact resource type. The deprecated status and endpoint are also included, reinforcing the purpose.

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 guidance: 'prefer a newer version of this resource where one exists, and use procore_search_endpoints to find it' and 'Confirm the target id with the matching show or list tool before calling.' It also explains error conditions and prerequisites, making it exceptionally clear when and how to use the tool.

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