harness_delete

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

Annotations already declare destructiveHint=true, so the description's warning 'destructive and cannot be undone' reinforces but adds the 'cannot be undone' consequence. It also adds the URL auto-extraction behavior. However, it does not disclose the confirmation requirement (the confirm parameter) or mention idempotency aspects, which are relevant to users but covered in the schema.

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 two sentences: the first states the core action, the second adds a key capability and a warning. Every sentence earns its place, with no fluff. It is front-loaded and efficient.

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 tool has 8 parameters, a rich schema, and a detailed output schema. The description covers the essential high-level purpose, destructive nature, and URL convenience. It doesn't mention the confirmation flow, but the schema's confirm parameter is thoroughly documented. Given the richness of structured metadata, the description is sufficiently complete, though it could add a one-line note about the confirm requirement.

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 all parameters described, so baseline is 3. The description adds value by explaining the url parameter's role in auto-extracting identifiers, which clarifies how url relates to resource_id, org_id, project_id, and resource_scope. This cross-parameter insight goes beyond the schema's per-field descriptions.

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 the tool's function with a specific verb ('Delete') and a resource ('a Harness resource'). It distinguishes from sibling tools like harness_create and harness_update since 'delete' is unique. However, it does not enumerate the supported resource types, leaving that to the schema, so it is not maximally specific.

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 implies usage for deleting resources and warns about destructiveness, but it does not explicitly state when to use this tool versus alternatives (e.g., harness_update for modifications, harness_get for inspection). The URL auto-extraction hint provides some usage context, but no exclusions or alternative-recommendations are given.

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