elasticsearch-mcp

Overview Schema Source Related Servers Discussions Admin

update_by_query

Destructive

Update documents matching a query in an index using a Painless script, with asynchronous task tracking and explicit confirmation for destructive operations.

Instructions

Update documents in place by query, using a painless script. DESTRUCTIVE and irreversible. A query is mandatory: match_all is refused so you cannot rewrite a whole index by accident. Runs asynchronously; returns a task_id to poll with get_task. Reports how many documents match before updating. Requires writes enabled, ES_MCP_ALLOW_DESTRUCTIVE=true, and confirm=true.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "index": "<index>",
      "query": "<query>",
      "script_source": "<script_source>"
    },
    "name": "update_by_query"
  }
}

Input Schema

Name	Required	Default
`index`	Yes
`query`	Yes
`slices`	No	auto
`confirm`	No
`script_params`	No
`script_source`	Yes
`requests_per_second`	No
`wait_for_completion`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Aug 23, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Adds substantial behavior beyond the destructiveHint annotation: the operation is irreversible, runs asynchronously, returns a task_id to poll with get_task, reports the match count before updating, and guards against full-index rewrites by refusing match_all. This is precisely the contextual depth the annotation bar expects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence earns its place: two-sentence purpose benefit, the destructive warning is second, and the guardrails/flow/prequisites follow tightly. No fluff or word repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive 8-parameter tool with 0% schema coverage, the output schema exists and thus return values are already handled, but the description leaves throttling (slices/requests_per_second) and script_params unconfirmed. The core invocation path is fully routed, so it is almost complete; the remaining param gaps drop it a notch.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaning for query (mandatory; match_all refused), confirm (must be true), script_source (painless), and wait_for_completion (async, via the task_id flow). However, slices, requests_per_second, and script_params remain entirely unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Statesa specific verb and resource: 'Update documents in place by query, using a sanctionscript.' The in-place updating distinction separates it from the sibling reindex (which copies to a new index) and delete_by_query (which removes documents). An agent can tell exactly what this tool does and how it differs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for when this tool will succeed or refuse: requires writes enabled, ES_MCP_ALLOW_DESTJRUCTIVE=true, confirm=true, and a non-match_all query. It does not explicitly name alternatives or exclusions (e.g., 'use reindex for copying'), so it earns 4 not 5.

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