delete_by_query

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

Beyond the destructiveHint annotation, the description discloses that the operation is irreversible, that match_all is refused as an accidental-wipe guard, that it runs asynchronously with wait_for_completion=false and returns a task_id to poll via get_task, and that it reports the matching document count first. This is substantial behavioral context consistent with the annotations, with no contradiction.

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?

Four sentences, no wasted words, and important signals are front-loaded: the destructive nature appears in the first sentence, the safety guard in the second, the execution contract and prerequisites follow. Every sentence earns its place and none repeats what the schema already states.

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 high-risk destructive mutation tool, all decision-relevant facts are present: prerequisites for permission, the mandatory query and its guard, the async task_id flow, and the match-count guarantee. An output schema exists, so return-value details do not need to be restated, and what the description omits (optional throttling knobs) is low priority for safe 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?

With schema description coverage at 0%, the description carries the burden for the critical parameters: query must be supplied and match_all is rejected, wait_for_completion defaults to async false, and confirm must be true even though its schema default is false. Optional tuning knobs (slices, requests_per_second) are not elaborated, but their defaults in the schema make that a minor gap.

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 states a specific verb (delete), resource (documents in an index), and mechanism (matching a query), which clearly differentiates it from siblings like update_by_query, reindex, and run_query. The scope is unambiguous: it is the destructive deletion counterpart, not a read or transformation tool.

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 strong context for when invocation is permitted: a query is mandatory, match_all is refused, async execution is the mode, and prerequisites (writes enabled, ES_MCP_ALLOW_DESTRUCTIVE=true, confirm=true) gate the call. However, it does not explicitly contrast it with non-destructive alternatives such as update_by_query or reindex, so the when-not-to-use guidance is only implied but not stated.

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