delete_configs

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

Beyond the destructiveHint=true annotation, the description discloses partial-success semantics (non-managed snippets come back as skipped), the no-match behavior (404 if none), that changes are persisted to the database and applied asynchronously by the scheduler, and that the tool cannot confirm the change is live. That is exactly the behavioral context a destructive write tool needs.

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?

Front-loaded with the action and the parameter shape, then failure modes, then the async-application caveat — a sensible ordering with no filler. Minor deduction for telegraphic fragments such as 'others come back as skipped, 404 if none', where '404 if none' is slightly ambiguous about whether it means no snippets matched or none were deletable.

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 single-parameter destructive tool with no output schema, the description covers persistence, deferred application, partial results and the not-found case, which is most of what an agent needs. It omits permission/authorization requirements and any sense of how many snippets may be passed or how results are reported per item.

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 description coverage is 100%, so service/type/name semantics are already documented per-field. The description restates the tuple shape and the 'global' convention, which is mildly useful for orientation but adds no syntax or constraint detail beyond the schema; baseline 3 applies.

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+resource ('Delete config snippets') and immediately defines the batch key shape {service, type, name}, making it unmistakable versus siblings like delete_instances, delete_service or delete_cache_files.

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?

It names the discovery path explicitly ('Use list_configs to find them') and implicitly scopes usage by noting only UI/API-managed snippets can be removed, with file-managed ones skipped. It does not spell out prerequisites or when deletion should be avoided versus updating instead, so it stops short of a 5.

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