elasticsearch-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation5/5
Each tool addresses a distinct concern: query execution, DSL generation, SQL translation, pagination, health, snapshots, async tasks, and writes. Even the seemingly similar search tools are clearly separated by their input format and use case, so an agent can select the right one with confidence.
Naming Consistency3/5
Many names follow a verb_noun pattern like list_indices, create_snapshot, and run_query, but there are many noun-first or adjective-noun exceptions such as cluster_health, shard_allocation, field_caps, snapshot_status, sql_query, and bulk_index. The naming is readable and snake_case throughout, but the conventions are mixed enough that the pattern is not predictable.
Tool Count2/5
34 tools is a heavy surface for an agent to navigate, especially since several areas such as cluster diagnostics, query generation, and snapshot management could be consolidated. While the breadth is understandable for Elasticsearch, the count exceeds what is typically needed for a coherent, easy-to-use tool set.
Completeness3/5
The server covers a wide range of operations: search, query generation, SQL, mappings, cluster health, slow-query investigation, snapshots, reindexing, async tasks, settings, aliases, and document writes. However, some core lifecycle operations are missing: no create_index, delete_index, close/open index, get document by id, delete snapshot, or single-document delete, which can create dead ends in common workflows.
Average 4.2/5 across 34 of 34 tools scored. Lowest: 3.3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only and non-destructive, so the description doesn't need to restate that. It adds behavioral value by enumerating exactly which metrics are returned and by implying the default is a wide search until an index pattern narrows it. No contradictions with annotations.
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?
Two efficient sentences: the first front-loads the tool's purpose with a metric list, the second gives the key usage hint. No repetition of annotations or schema, and each sentence carries content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and read-only annotations, the description covers the main purpose and the only core parameter. It misses explicit guidance on default scope (no pattern means all indices), the effect of include_settings, and when to prefer cluster_health or cat_nodes over a per-index health report.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% field description coverage, so the burden falls on the description. It clarifies the 'index' parameter (an index pattern narrows the scope) but says nothing about 'include_settings' (whether it toggles settings details in the output). This is a meaningful gap for an agent choosing parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: reports per-index health and size with an explicit metric set (status, docs, store size, primaries/replicas, segments, refresh/merge stats, throughput). It is clearly distinguishable from many siblings by content, though it doesn't explicitly name the closest alternative (cluster_health) — hence not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage hint is 'Pass an index pattern to narrow it down,' which explains the index parameter rather than when to choose this tool over siblings like cluster_health or cat_nodes. No explicit when-to-use, exclusions, or alternative routing is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotation Contradiction: the annotations declare readOnlyHint=true, while the description says the tool 'closes' a resource and 'frees cluster resources.' That is a state-changing behavior, not a read-only one. The description does not resolve or even acknowledge this mismatch, which can mislead an agent that trusts the annotations.
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?
The description is two short, purposeful sentences. The primary action and effect are front-loaded, and the usage guidance is a compact follow-up with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter cleanup tool, this is nearly complete. It says what, why, and when. However, it omits required preconditions (the PIT must already be open) and the postcondition that the pit_id is no longer usable, and the annotation contradiction undermines overall completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents pit_id only as a required string with no description. The tool description adds 'by its pit_id,' which is almost a restatement. With schema description coverage at 0%, the description should explain how to obtain pit_id (e.g., from open_pit) and that it becomes invalid after closing.
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?
The description uses a concrete verb ('Close') and names a specific resource ('point-in-time'), scoped by pit_id, with a clear purpose ('free cluster resources'). It clearly reads as the terminal counterpart to open_pit and is not likely to be confused with search or query siblings.
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?
'Call after paging finishes' is an explicit, useful lifecycle instruction. It does not list alternative tools or exclusions, but the context of the sibling set (open_pit, paged_search) makes the intended workflow clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already carry readOnlyHint=true and destructiveHint=false, so the description does not need to re-state safety. It, however, adds a description of what the snapshot covers, which is a small value-add. It does not mention any potential cost or latency difference between cluster-only and per-index mode, so a 3 feels right in light of the annotation safety coverage.
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?
Two sentences, front-loaded with the data fields, with the troubleshooting routing at the end. There is no filler or unnecessary repetition, making it easy for an agent to parse.
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 simple two-parameter, all-optional, read-only tool with an output schema, this description covers the relevant surface area: what the health summary includes, how granularity can go per-index, and when it should be used. The only missing piece is more structured parameter wording, so it's close to complete but not perfect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/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 for the two parameter names. It gives a weak hint for the level param by saying 'optionally' per-index health, but it still doesn't explain valid values for level and does not describe include_nodes at all. Without valuable parameter detail, score remains low.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a cluster-health snapshot and enumerates the specific data points it reports — status, node counts, shard states, pending tasks, and optional per-index health. It does not explicitly contrast itself with sibling tools like index_health or cat_nodes, so a top score feels too generous.
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?
The clustering of 'Start troubleshooting here' gives agents a clear behavioral directive: begin diagnosis with this tool. It also signals that per-index health is an optional add-on. Missing is explicit guidance about when to prefer index_health or cat_nodes, but the intended default path is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this tool read-only and non-destructive, so the description is not solely responsible for safety disclosure. It adds some behavioral texture by enumerating returned snapshot details, but does not mention wildcard behavior, verbose mode, potential slowdowns, or repository access implications.
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?
The description is two tight sentences with every word serving a purpose. The key purpose and return information are front-loaded, and the usage hint appears immediately after the action.
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?
The tool has a read-only annotation, a present output schema, and a clear primary use case, so the description covers the most important operational context. It leaves the optional parameters underspecified but is not missing a critical decision point when the agent is choosing between snapshot-related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the prose only indirectly mentions the `repository` parameter via “in a repository.” It does not explain the wildcard behavior of `snapshot` or what `verbose` adds, leaving the two optional parameters underspecified in the very place the description was needed to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a clear action-resource pair (“List snapshots in a repository”) and enumerates the meaningful output fields, so an agent knows what the tool does. It does not explicitly contrast itself with the closely related sibling `snapshot_status`, so it stops short of full differentiation.
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?
It contains direct usage context: “Use this before restoring to pick the right snapshot,” telling an agent the ideal invocation moment. It does not give exclusion criteria or name alternatives, but the context is specific and useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already confirm readOnlyHint=true and destructiveHint=false, and the description adds useful behavioral context: it reports per-shard progress with stage, bytes done, and total bytes. This goes beyond the annotations without contradicting them.
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?
The description is very short, front-loaded, and conveys the essential behavior in a single line. There is no filler, redundancy, or restating of the tool name.
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 read-only status tool with an output schema, the description conveys the main value (per-shard progress). It is incomplete only in clarifying optional parameter behavior and how this relates to snapshot/list siblings, but it is otherwise adequate for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain what the 'snapshot' and 'repository' parameters mean, which combinations are valid, or what happens when they are omitted. The parameter names are reasonably self-explanatory, but the description still leaves invocation semantics ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly indicates a snapshot-status inspection tool, describing progress details like per-shard stage and byte counts. It lacks an explicit verb such as 'get' or 'list' and does not directly contrast with sibling tools like list_snapshots, so it is clear but not maximally differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'running or recent snapshots' gives implied usage context, but the description does not explicitly state when to prefer this over related snapshot tools or whether it can be used for all snapshots vs only active ones. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate readOnlyHint=true and destructiveHint=false, so the safety profile is established. The description adds some context by specifying exactly which informational fields are returned, but it does not disclose behavior beyond that, such as error cases, load implications, or policy effect.
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?
The description is a single compact phrase that conveys all essential information without filler. It presents the primary attributes in a natural order and does not repeat anything already visible in the tool name or schema.
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 zero-parameter read-only info tool with an output schema and annotations, the description is largely complete. It could explicitly explain what the safety policy value means or how the agent should interpret it, but nothing critical prevents an agent from correctly selecting and invoking this tool.
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?
The tool has zero parameters, so the schema already covers all input requirements. The description compensates by describing the kind of information returned; there is no parameter ambiguity or gap for an agent to navigate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns cluster identity information: name, version, distribution, and safety policy. It lacks an explicit verb like 'retrieves' but the resource and specific data fields make the purpose unmistakable and distinguishable from sibling tools like cluster_health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for retrieving basic cluster identity and safety-policy information, but it provides no explicit guidance about when to prefer it over alternatives such as cluster_health or list_indices. Usage context is clear from the name and description, but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare read-only, non-destructive behavior, and the description adds useful behavioral detail on top: it reads four distinct backend signals, checks whether slowlog is enabled, and bounds the result with top_n. This goes beyond what the input schema or annotations alone reveal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the main goal, then gives a precise inventory of data sources and a plugging guidance for controlling result size. Each sentence adds substantive information; only minor redundancy exists in the 'average latency' phrase and the min_avg_ms parameter implication.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema exists and covers return structure, and the annotations cover safety behavior. However, the description leaves index and min_avg_ms underspecified. Since all parameters are optional, this is a moderate completion gap rather than a severe one.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/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 provide parameter meaning. Only top_n is directly explained. index and min_avg_ms are not explicitly connected to the schema inputs, even though 'average query latency' hints at min_avg_ms.
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?
The description opens with a clear goal, 'Find what is slow', then specifies exactly what inputs it combines: indices ranked by average query latency, running search tasks, thread-pool queue/rejection counts, and slowlog thresholds. This makes it clearly distinct from sibling tools like run_query, explain_query, and get_task, which focus on individual queries rather than aggregated slow-query diagnosis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use case is implied: use this when investigating slow query performance. However, the description gives no explicit when-not-to-use guidance and does not contrast this tool with alternatives such as explain_query, get_task, or cluster_health.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. It does add useful behavioral context around pattern matching and the inclusion of aliases/data streams, but it does not mention pagination, pattern syntax limitations, or the potential breadth when pattern defaults to '*'.
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?
A single, front-loaded sentence covers the action, scope, filtering mechanism, and included stats without redundant words. Every phrase adds meaningful information.
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 read-only, two-parameter inventory tool with an output schema, the description is largely sufficient. It could be more complete around the pattern matching semantics, but the annotation safety profile and schema defaults reduce the risk of calling this tool incorrectly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/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 for explaining both parameters. It references 'pattern' and 'aliases' but does not explain wildcard syntax, the meaning or effect of include_aliases, or how the default values influence behavior.
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?
The description uses a specific verb ('List') and identifies concrete resources: indices, data streams, and aliases. It also communicates the returned information (doc counts and store size), which separates it clearly from sibling tools like cat_nodes, get_mapping, and index_health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies discovery/inventory use by saying 'matching a pattern', but it does not explicitly state when to prefer this tool over siblings such as alias_actions, cat_nodes, or index_health. There are no exclusions or alternative routing hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the description does not need to restate the safety profile. The description adds the 'running task' qualifier and the expected usage scenario, but it does not address what happens when the task is already completed or whether confirmation is required.
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?
Two short sentences with no filler: the first gives the action and object, the second provides a concrete use case. The information is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, and the annotations plus the description give a solid starting point: cancel a running task by ID, notably for runaway reindexing or searches. However coverage lacks the optional confirm parameter's meaning and how cancellation behaves if the task is already done, which an agent may need to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/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 only explains task_id indirectly by saying 'by id'; the confirm parameter is not described at all, leaving an agent uncertain about its role and whether it must be set.
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?
The description states a precise verb and resource: 'Cancel a running task by id.' It also differentiates from siblings by targeting running tasks, so an agent can distinguish it from get_task or stop-like operations.
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?
The description clearly says when to use it: 'for a runaway reindex or a search eating the cluster.' It does not explicitly mention when not to use it or name alternatives, but the use cases are concrete and helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool is read-only and non-destructive, so the description adds value by specifying the behavioral scope: it surfaces progress and errors for specific long-running task types. This complements, rather than contradicts, the annotations.
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?
One focused sentence states the verb, target, examples, and the information returned. There is no fluff or redundant context.
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?
This is a simple, two-parameter, read-only tool with an output schema, and the description covers the main use case and scope. It could optionally explain where task_id comes from or that wait_for_completion blocks, but those details are partially implied by the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no parameter-level guidance. The parameter names ('task_id' and 'wait_for_completion') are somewhat self-explanatory, but the description does not clarify behavior of or relationships between these parameters."
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States the action 'Poll' and the resource 'a long-running task' with specific, recognizable examples (reindex, update_by_query, delete_by_query). This makes the tool's purpose clear and distinguishes it from sibling actions like cancel_task, though it does not explicitly compare itself to those siblings.
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?
The description implies usage after launching tasks such as reindex, update_by_query, or delete_by_query, and the polling language distinguishes this from cancel_task or the operations themselves. It does not explicitly state when not to use it or mention alternatives, but the provided context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint already protects against mutating behavior, and the description adds new detail by explaining that the tool tokenizes the field's indexed text and shows how that mapping differs from a user-provided search term. This is meaningful behavioral information that also aligns with the safe profile and does not contradict any annotation.
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?
Two sentences with zero filler: the first states the function plainly, the second gives a focused usage context. It front-loads the core action and then gives the precise diagnostic trigger.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema and requested annotations already cover result formatting and safety, while the description gives the key diagnostic use case. However, it leaves ambiguity about how optional parameters (field, index, analyzer) interact or what happens when only `text' is provided, which could trip up an agent needing to debug a particular field.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/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 clarify parameters, but it only hints at 'text' and 'field' through the phrase 'the field's analyzer.' It does not explain 'index' or how to choose among analyzer/field/index, nor whether they are optional and have defaults.
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?
The description uses a clear verb-resource pair ('Run text through an analyzer', 'see the resulting tokens') and positions it against a concrete scenario: 'when a match query returns nothing.' This distinguishes it from sibling tools that run queries, count documents, or inspect health.
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?
It explicitly names a decisive trigger ('when a match query returns nothing') and explains what the tool clarifies, giving an agent an actionable decision rule. It does not explicitly mention when not to use it or list alternative siblings, but the one condition provided is strong and specific.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With all annotation hints set to false, the description carries the burden of explaining behavior. It adds meaningful context by disclosing that this call returns immediately and that persistence must be confirmed via snapshot_status. It also mentions the confirm=true prerequisite, which is the useful and not captured by the annotations. It could go further on effects of wait_for_completion or include_global_state, but the core behavioral disclosure is strong.
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?
The description is two sentences with no filler and the purpose is front-loaded. It packs the final semantics into a concise sentence and keeps the key identifying purpose first. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential flow: create, non-blocking, poll, and prerequisite. It omits the semantics of wait_for_completion=true and include_global_state, which are likely to matter for an agent deciding how to invoke the tool correctly. The schema makes up some parameter defaults, but given only two required parameters and several optionals, the description is at minimum viable completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/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 for the six parameters. It only indirectly covers: repository, indices, and confirm. The important parameters wait_for_completion and include_global_state are not explained in the description. The phrase 'non-blocking by default' implies wait_for_completion, but it is not stated directly. This materially falls short of the required parameter guidance.
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?
The description opens with 'Create a snapshot of selected indices into a repository,' which states a specific verb and resource while also defining the scope of the operation. It is clearly distinguishable from sibling tools like restore_snapshot or list_snapshots. The description is not a tautology of the tool name.
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?
The description provides practical usage context: it is non-blocking by default, the agent should poll with snapshot_status, and confirm=true plus writes-enabled are required. It clearly covers when to invoke it and what to do after invocation, though it does not explicitly discuss alternatives or exclusions relative to sibling snapshot tools. This is clear and actionable context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only and non-destructive, and the description adds useful behavioral context: it returns no hits and is cheap to run. This goes beyond the annotations without contradicting them, though it does not describe edge cases like null query semantics or exact response shape.
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?
Two short sentences with no filler. The core behavior is front-loaded, and the secondary sentence provides a practical reason to use the tool without 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 simple, low-parameter tool backed by a readOnly annotation and an output schema, the description is mostly complete. The only meaningful gap is query parameter semantics, which is not provided by the schema description either.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does little to explain the two parameters. 'Matching documents' implies query filtering, but the description does not clarify that query can be a string, object, or null, nor what a null query does or why the index parameter is required.
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?
The description states a specific operation: counting matching documents. It also explicitly notes that it does not return hits, immediately distinguishing it from search-style sibling tools like paged_search or run_query.
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?
It gives a concrete use case: 'cheap way to size a query before running it,' which tells an agent when choosing this tool is appropriate. It does not explicitly list exclusions or alternatives, but the guidance is still clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is covered. The description adds a little extra by mentioning the returned fields (type, settings, bucket, base_path), but it does not describe any further behavior such as whether the list is cached or dynamic. No contradiction with annotations.
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?
The description is a single, front-loaded sentence that states the action, the resource, and the interesting output fields without unnecessary qualifiers. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, an output schema, and annotation coverage, the description supplies sufficient context for an agent to know what this tool returns. The openWorldHint and readOnly annotations further cover expectations around mutation and result completeness.
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?
The tool has zero parameters, so there are no parameter semantics to explain. The description adds nothing about parameters, but none are needed; this supports the baseline score of 4 for parameterless tools.
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?
The description uses a specific verb 'List' and a clear resource, 'registered snapshot repositories', and adds expected content ('type and settings'). This clearly separates it from sibling tools like list_snapshots, which would focus on snapshots rather than repositories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the tool to use when you need an inventory of registered snapshot repositories, but it does not explicitly state when to use it over alternative siblings like list_snapshots or snapshot_status. There is no exclusion or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only and non-destructive behavior. The description adds valuable detail beyond that, specifying the exact outputs: _cat/shards, per-node disk usage, per-node usage, and decider-level allocation explanations for unassigned shards. This helps an agent understand what to expect without excelling the documented safety profile.
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?
The description is three sentences long, front-loads the core purpose, and every sentence adds useful detail. It includes concrete output categories and the key use case without unnecessary fluff.
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 an annotated read-only diagnostic tool with an output schema, the description provides strong context and enough detail about outputs. The missing explicit handling of the parameters is the only notable gap, but the output schema and self-explanatory parameter names keep this mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain the 'index' or 'only_problems' parameters. While the parameter names are somewhat self-explanatory and default values are in the schema, the description does not carry the weight needed to compensate for the missing semantic documentation.
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?
The description clearly states what the tool does: reports shard placement, why shards are unassigned, and cluster allocation decisions. It differentiates itself by specifically targeting the yellow/red cluster diagnostic scenario, which helps separate it from broader health tools like cluster_health or index_health.
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?
The description explicitly gives a usage context: 'This is the tool for a yellow/red cluster.' This gives a clear when-to-use signal, though it does not explicitly contrast this tool with alternatives such as cluster_health or explain_query.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
BT beyond annotations by exposing the confirm gate, reporting counts and 'first few errors,' and hinting mutating behavior ('write'). Scopes of atomicity partial failure are missing, but because annotations already mark readOnly=false no contradiction arises.
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?
The description is front-loaded with the main purpose, compact, and every sentence adds value. No fluff.
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?
core call path and constraints are present, and output schema handles return values. However, it leaves refresh and documents-string behavior under-specified. Otherwise a reasonable complete description for a 5-parameter writing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates enough for documents array, id_field, and confirm, but does not cover refresh nor the schema's documents-as-string alternative. Therefore it partially adds meaning.
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?
The description states a specific verb and resource: 'Bulk index many documents into one index in a single request.' It also distinguishes itself from index_document by pointing out 'Much faster than index_document in a loop,' so an agent can tell noisy apart.
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?
It provides clear context by statine that this is for bulk operations and explicit prerequisite 'Requires writes enabled and confirm=true.' However, it does not state exclusions such as when to prefer index_document for a single document.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety with readOnlyHint=true and destructiveHint=false, so the description only needs to add non-obvious context. It adds the list of exposed fields and the intended diagnostic uses. It does not disclose additional behavioral details such as how results are sorted, whether the response is sampled, or any default node filtering—though output schema may cover return format. It is adequate, not exceptional.
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?
Two sentences with no filler. The first sentence states what the tool returns; the second states why it is useful. Every phrase earns its place, and the description is front-loaded with the list operation.
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 zero-parameter read-only listing tool with an output schema present, the definition is largely complete. It covers the result content and the motivating scenarios. A small gap is the lack of explicit disambiguation from the overlapping sibling cluster_info or cluster_health, but that is minor relative to the complexity of this tool.
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?
This tool takes zero parameters, so there is nothing to clarify. Per the rubric, a 0-parameter tool earns a baseline of 4. The description appropriately spends no words on input semantics.
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?
The description uses a specific verb and resource: 'List cluster nodes' and enumerates the exact attributes returned (role, version, heap/RAM/CPU/load, master flag). This clearly separates it from sibling tools like cluster_health or cluster_info, which operate at cluster level rather than node level.
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?
It provides explicit use cases: 'spot a hot node, a version mismatch across nodes, or which node is master.' This is actionable guidance. It does not explicitly name alternative tools or exclusion criteria, but the scenarios are specific enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It discloses important behavior beyond the readOnlyHint: the output is a flattened catalog showing field path -> type, includes multi-fields like .keyword, and optionally returns dynamic templates and total field count. It also clarifies the raw=true switch returns the untouched mapping JSON. This precisely sets expectations for what the agent will receive.
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?
It is only two sentences long and stays on task. The first sentence states the primary action and its main output; the second sentence adds the raw-mode option without fluff. Every phrase in the result provides value.
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?
The description covers the operational core: what the tool returns, why an agent would need it, and the raw toggle-and has an output schema to document returned values. It is almost complete, but the field_filter parameter is still a black box, and since the schema itself has no descriptions, an agent would not know how to use that particular optional input effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the only source of parameter meaning. It explains raw=true and implicitly clarifies that index names the mapping target, but it says absolutely nothing about field_filter. That parameter remains a mystery, which is a meaningful gap because an agent may incorrectly spread or omit it. The description adds some value but does not fully compensate for the missing schema descriptions.
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?
The description opens with a specific verb and resource: 'Get the mapping for an index,' and immediately distinguishes the tool from write-oriented siblings like put_mapping. It also clearly explains the output's purpose, which makes the tool's role among the sibling list unambiguous.
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?
The description gives a concrete use case: 'which is what you need to write correct queries,' meaning the tool should be run when the agent needs field-level type information to construct valid queries. It does not explicitly name alternatives or when-not-to-use scenarios, but it offers enough contextual direction to route an agent correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though destructiveHint=true already flags mutating behavior, the description adds concrete destructive behavior details: an existing index must be closed or renamed or the restore fails, and confirm=true is required. This explains the failure mode and safety gate beyond what annotations alone provide.
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?
Two compact sentences deliver the core purpose, a key destructive behavior, and the prerequisites. It is front-loaded with the action and immediately warns about the important destructive constraint with no filler.
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?
The description covers the essential operational guardrails: the destructive nature, the index conflict rule, the environment flag, and the confirmation parameter. With an output schema present and annotations indicating destructive behavior, the remaining gaps around individual defaults like wait_for_completion are minor, so the tool is sufficiently understandable to be used correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate for parameter meaning. It does add meaning for rename_pattern/rename_replacement and identify confirm=true as a requirement, but it omits semantics for repository, snapshot, indices, include_aliases, and wait_for_completion, leaving gaps for an agent trying to construct a correct call.
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?
The description states a specific verb and resource: 'Restore indices from a snapshot.' It clearly identifies the action and the entity, and is distinguishable from sibling tools such as create_snapshot or list_snapshots. The term 'Restore' makes the intent unmistakable.
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?
It provides strong usage context: it warns about the need to close or rename existing indices and explicitly lists the prerequisites of writes enabled, ES_MCP_ALLOW_DESTRUCTIVE=true, and confirm=true. It does not explicitly mention alternatives, but no alternatives are really comparable at the same action level, so context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is read-only and non-destructive, and the description builds on that by disclosing behavior not visible in the schema: a server-side size cap, an injected timeout, deep-paging rejection, and the return shape. These are exactly the kind of hidden constraints an agent needs before invoking the tool.
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?
The description is compact but information-dense. Every sentence serves a purpose: define the call, describe constraints, describe output, and give pivotal pagination guidance. There is no redundancy, filler, or vague wording.
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 low-level Elasticsearch search tool, the description provides key execution semantics: what it sends, what the server does, and what is returned. It covers a safe, courteous usage pattern by disclosing limiting and deep-paging behavior. It leaves a gap around explicit alternative-tool selection with other search-family siblings, but the presence of an output schema and the readOnly annotations lower the need for additional detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 10 parameters and 0% described in tooling, so the tool description cannot rely on parameter documentation. It does add semantics for the central parts — query accepts a full Elasticsearch Query DSL body, size is capped, and search_after is used for deep pagination. However, sort, from_, routing, preference, source_includes, and profile rely on property titles and types, leaving somewhat unresolved how an agent should compose a full request.
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?
The description names the exact operation with a specific verb and resource: "Execute an Elasticsearch search against an index or alias." It also conveys the query contract by saying it accepts a full Query DSL body, which helps distinguish it from siblings like count_documents, sql_translate, and generate_dsl. The mention of returned data (hits, aggregations, timing, shard stats) further clarifies the tool's role.
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?
The description clearly communicates operational constraints: size is capped, a timeout is injected, and deep paging is rejected. It also explicitly advises using search_after for pagination beyond 10k, which tells the agent how to behave when large result sets are involved. It does not explicitly exclude siblings like paged_search or count_documents, so the guidance about alternatives is mostly implied rather than fully stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive behavior. The description adds meaningful transparency by explaining what each execution path will reveal—rewrites, invalid query details, per-component timing, and match/scoring explanation—making the behavioral outcome clear.
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?
The explanation is delivered in one dense, structured sentence with numbered modes and no filler. The core action is front-loaded, and each clause describes one distinct behavior or use case.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For this tool, the description covers validation, performance analysis, and document-level explanation—essentially all behavior the caller needs to decide invocation. The presence of an output schema also relieves the description from enumerating return structures.
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 for parameter documentation. It explicitly explains the behavioral effect of profile=true and the doc_id parameter, and it clarifies the abstruse rewrite mode. Only the index parameter is left implicit, which is already self-evident from its name.
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?
The description clearly states the tool explains a query and enumerates three concrete modes: query rewriting/validation, profiling, and per-document matching. This makes it unambiguous what the tool does and distinguishes it from generic run/query tools.
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?
The description gives clear context for when to use each mode: validation rewrite, finding slow clauses, and explaining document matches. It does not explicitly name alternatives or state when not to use the tool, but the mode-specific guidance is strong enough for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to restae safety. It adds useful behavioral context: the tool inspect capabilities, reports tapabilities, and supports multiple fields including wildcards. No behavioral surprises are hidden, and there is no contradiction with annotations.
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?
The description is three sentences with no filler. The primary behavior is first, the motivating use case is second, and the fields parameter usage is last. Every sentence adds useful information and the syntax is flat and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description does not need to explain the full return shape. The use case, parameter input, and behavioral scope are all covered. For a rea-only introspection tool with simple parameters and rich schema output, this is complete enough for an agent to select and call it.
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 carry parameter semantics. It directly explains the fields parameter ('comma list or *') and clarifies why you would pass certain fields. The index parameter is not given a separate formula, but it is contextued by 'across indices' and the talk of index patterns, so an agent can reasonably map it to the required index string.
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?
The description states a specific verb ('Show the capabilities'), a precise resource (fields across indices), and names the underlying API (_field_caps). It also enumerates the concrete outputs (type, searchable, aggregatable), making the tool unambiguous and distinguishable from sibling tools like get_mapping.
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?
The description gives a clear primary use case: detecting fields mapped to incompatible types across indices, which breaks queries over an index pattern. It does not explicitly enumerat alternatives or when-not to use it, but the context is strong enough for an agent to know when field capabilities are relevant.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, openWorld, and non-destructive, and the description adds meaningful behavioral nuance: the tool validates generated queries against the real index and returns a field catalog to guide corrections. It does not cover edge behavior/errors, but the safety profile is already declared.
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?
The description is compact but information-dense: purpose first, then a structured list of accepted spec shapes, operators, and return value. Every sentence contributes, and no content is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a complex spec object and 0% schema descriptions coverage, the description gives enough details for an agent to supply a valid input and understand what will be returned. Since output schema exists, return-format explanation is unnecessary.
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?
Despite 0% schema parameter description coverage, the description compensates for the critical spec param by enumerating supported top-level keys, filter operators, agg fields, and sort/size options. Index and validate are not elaborated, but they are self-explan from names and schema.
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?
States a clear, specific action: generate Elasticsearch Query DSL from a structured spec and validate it against the real index. The resource is identifiable and the explanation distinguishes generation/validation from execution-oriented/neighbor tools like run_query or sql_translate.
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?
The description conveys when to use it, especially via 'correct field names before running it', signaling a validation-before-execution workflow. It does not explicitly name sibling alternatives or give exclusions, so a perfect routing guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds useful lifecycle context: PIT freezes the data view, is held by the cluster for a time controlled by keep_alive, and must be explicitly closed. This goes beyond the structured hints, though it does not detail side effects like resource usage or closure behavior after timeout.
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?
The description is concise: two sentences, no filler, and front-loaded with the primary function. It packs in the pagination motivation, pair with paged_search, close_pit requirement, and the semantics of keep_alive without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only two parameters, uses existing annotations, and has an output schema available, the description supplies the critical integration logic: why to open it, how it supports pagination, and the mandatory close_pit call. All needed operational context is covered succinctly.
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 coverage is 0%, so the description must carry parameter meaning. It covers keep_alive explicitly ('controls how long ES holds it open') and states that index is the target of the PIT. The descriptions are useful and disambiguate the meaning of both parameters, though the index parameter is only implicit in 'against an index' rather than explicitly labeled.
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?
Description states a specific verb ('Open'), a specific resource ('a point-in-time (PIT) against an index'), and the desired result ('return its pit_id'). It also distinguishes itself from related tools like paged_search and close_pit within the description, so an agent understands the tool's exact role.
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?
The description clearly explains when open_pit is useful: for consistent pagination past the 10000-depth limit with paged_search. It also provides explicit guidance to always pair it with close_pit. It does not explicitly state when not to use it (e.g., for one-shot queries), so it misses the full when-not/exclusion aspect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important non-obvious behaviors beyond the annotations: a sort is required, an implicit _shard_doc tiebreak is added, the PIT binds the index so no index argument is needed, and the returned pit_id may be refreshed. This is exactly the behavioral context an agent needs to use the tool safely and correctly.
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?
The description is dense but not bloated: purpose, workflow, ordering constraint, PIT binding, and closing requirement are each covered in a few direct sentences. There is no filler, and the most important stateful protocol is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a stateful PIT-based pagination tool, the description covers the full lifecycle: open, call, continuation, and close. It also explains response behavior (page plus next_search_after and refreshed pit_id) and the sort/stability requirement. Output schema and annotations cover the remaining structural safety information, so nothing essential is missing for a correct call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate heavily. It does explain pit_id, query, and search_after via next_search_after, and notes that sort is required. However, size, keep_alive, and source_includes receive no semantic explanation in either the schema or the description, leaving gaps for a 7-parameter tool.
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?
The description opens with a specific verb and resource: 'Page through a large result set beyond the 10000 deep-paging limit using a point-in-time and search_after.' This clearly distinguishes the tool from ordinary query tools and from its open_pit/close_pit siblings. It names the exact mechanism and scope without tautology.
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?
The description gives a clear sequential protocol: first call open_pit, then call paged_search with the pit_id and query, pass next_search_after and refreshed pit_id back, and finally close with close_pit. This is strong contextual guidance. It does not explicitly mention when not to use this tool versus alternatives like run_query, 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses atomicity, the allowed action types, the write-policy check on every index, and the requirement that writes be enabled and confirm=true. These are valuable behavioral details the annotations do not provide, and there is 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense but still compact, and the concrete example earns its place. The most important constraints, atomicity and allowed operations, are front-loaded before the example and prerequisites.
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 two-parameter, not-destructive configuration operation, the description covers how to call the tool, what operations are allowed, when to use it, and what prerequisites must hold. The output schema implicitly explains return behavior, so the absence of an explicit return description is not a meaningful gap. The only slight miss is no detail about partial failure behavior beyond 'atomically,' which is minor.
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?
Since schema description coverage is 0%, the description carries the full burden of explaining parameters. It gives a concrete JSON array example for 'actions' and clarifies that only add/remove operations are valid. It also explicitly ties 'confirm=true' to execution requirements. The main gap is not explaining the string alternative allowed by the schema, but the core semantics are well covered.
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?
The description states a specific verb and resource: 'Add or remove index aliases atomically in one request.' It also clearly differentiates the tool from sibling operations by naming the only allowed actions ('Only add/remove are allowed') and by framing the operation as an atomic alias swap.
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?
Explicitly identifies a concrete use case: 'Use this to swap an alias from an old index to a new one with zero downtime after a reindex.' It also gives operational prerequisites, but it does not name sibling alternatives or explicitly exclude them; the context makes the intended usage clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing asynchronous execution, task_id polling, environment flag requirements, and the mandatory confirm parameter. It also orients the agent to handle the operation as non-though and non-idempotent, which is critical for a rebuild/restore-style action.
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?
Three sentences that pack a functional summary, use-case routing, asynchronous behavior, and prerequisites into a compact structure. No padding or redundant restatement of the tool name.
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?
Describes what the operation does, when to use it, how it runs, and what is required before calling it. Lacks explicit detail on destination index behavior and tuning parameters like slices, but for a modal-input tool the guidance is solid and actionable.
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?
With 0% schema coverage, the description compensates by explaining the roles of core params: query, pipeline/script, wait_for_completion, confirm, source/dest indexes. It does not comment on slices, requests_per_second, or op_type, but their names are self-explanatory and the main semantics are covered.
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?
Clearly states the operation: 'Copy documents from a source index to a destination,' with optional filtering and transformation. The use cases 'change a field type, reshard, or migrate data' make the tool's role unmistakable and distinguish it from sibling data-manipulation tools.
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 explicit when-to-use guidance ('Use this to change a field type, reshard, or migrate data') and specifies prerequisites such a = 'confirm=true' and 'ES_MCP_ALLOW_DESTRUCTL=true.' Does not name explicit alternative tools or when-not-to-use scenarios, 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.
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description discloses dynamic-only behavior, refusal of static settings, and the required configuration/confirmation gates. This tells the agent not only that mutation occurs, but exactly what preconditions need to be satisfied before it attempts the call.
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?
The description is compact and front-loaded. Its first sentence states action and scope, and the remaining sentences cleanly communicate limits and prerequisites. Every clause carries useful information without padding.
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?
With an output schema present and the destructiveHint already annotated, the description is sufficiently complete for a moderate update-settings call. Minor gaps, such as specifying how the settings parameter should be serialized and how partial updates behave, keep it just short of perfect.
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?
With 0% schema coverage, the description compensates by naming concrete settings values and making the confirm parameter's requirement explicit. It could additionally clarify the accepted string/object format for the settings argument, but the examples and the static-settings refusal add real semantic value beyond the raw schema.
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?
The description opens with a specific verb and resource: 'Update dynamic index settings', and gives concrete examples like number_of_replicas, refresh_interval, max_result_window, and blocks.*. It also narrows the tool's scope by excluding static settings, so an agent can immediately tell it apart from other index-related siblings.
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?
The description gives clear usage boundaries: use it for dynamic live-index settings, and static settings will be refused. It also states the prerequisites for invocation, including writes enabled, ES_MCP_ALLOW_DESTRUCTIVE=true, and confirm=true. It does not explicitly name alternative sibling tools, but the dynamic/static distinction and index-settings scope provide strong routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description discloses overwrite semantics, automatic ID assignment when doc_id is omitted, the searchability/performance trade-off of refresh=true, and the mandatory confirm=true requirement. This gives the agent realistic expectations about mutation and preconditions.
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?
Each sentence carries a separate useful fact: operation/semantics, doc body, doc_id behavior, refresh trade-off, plus confirm/writes requirement. There is no fluff; it is front-loaded and economical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema, no return-value description is needed. The description covers the write/overwite behavior, both optional parameters with meaningful semantics, and the critical confirm/writes-enabled precondition. A capable agent can invoke this tool correctly with the provided details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description does the required lift: 'document' is cast as a JSON object, doc_id's overwrite/auto-assign behavior is spelled out, refresh's trade-off is explained, and confirm's necessity is stated. Only 'index' is left implicit, but its role is obvious from the operation name.
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?
The description clearly identifies the operation ('Index (create or overwrite) a single document into an index') and differentiates the tool from bulk, read, and query siblings by emphasizing 'single document'. It also states the core create-vs-overwrite behavior, which makes intent unambiguous.
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?
The description gives clear operational context: pass a JSON document, use doc_id to overwrite, enable refresh for immediate visibility, and confirm that writes are enabled and confirm=true. It does not explicitly name sibling alternatives such as bulk_index, so guidance is strong but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true and readOnlyHint=false, and the description adds strong behavioral context: only additive changes are possible, field-type changes require reindex, writes must be enabled, and confirm=true is required. This goes well beyond the annotations and gives an agent a clear picture of the mutation's constraints.
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?
Three short, dense sentences with no repetition or filler. The main purpose is front-loaded, the key limitation is stated second, and the invocation prerequisite closes it. Every sentence earns its place.
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?
Given the tool's complexity, the description covers the most operationally important context: what the tool does, when it cannot work, and what prerequisites must be met. It is slightly less complete on the exact expected shape of the properties parameter, which the schema leaves entirely open.
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 does by associating properties with new fields and index with an existing mapping, and it explicitly says confirm must be true. It does not give an example or exact format for the properties parameter, which keeps it from being a 5.
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?
The description opens with a specific verb and resource: 'Add new fields to an existing index mapping.' It clearly distinguishes the tool from reindex by stating that changing an existing field type requires reindex, so an agent can correctly select this tool for additive mapping changes only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when this tool is appropriate (additive mapping changes) and when it is not (changing existing field types requires reindex). It also states the operating prerequisites: the server must have writes enabled and confirm=true must be provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the read-only, non-destructive nature. The description adds substantial behavioral detail beyond that: the index allow/deny policy check, the fetch_size cap, server result-size limits, and cursor-based pagination behavior. This is valuable operating context an agent needs before calling.
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?
Four sentences, each earning its place. The main purpose is front-loaded, the example is compact and illustrative, and the constraints are stated in two short clauses. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only SQL execution tool with 3 optional parameters and an output schema, the description covers all necessary operational details: what query types are allowed, index policy enforcement, row limits, result shape, and cursor continuation. Nothing important for an agent to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must carry the meaning of the parameters alone. It does this well: the example illustrates the query parameter, 'Row count is capped by fetch_size' explains fetch_size, and 'a cursor is returned to pass back as the cursor argument' defines the cursor parameter. All three parameters are semantically grounded.
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?
The description opens with a specific verb-resource pair ('Run an Elasticsearch SQL query via the _sql API') and immediately clarifies its purpose: quick aggregate/filter questions without hand-writing Query DSL. The SQL example and 'Only SELECT is allowed' makes the tool's scope unambiguous and distinguishable from DSL-oriented siblings.
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?
It clearly states when to use it ('quick aggregate/filter questions without hand-writing Query DSL') and provides an explicit exclusion ('Only SELECT is allowed'). It does not name specific sibling tools as alternatives, so guidance is strong but not maximally explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond annotations by stating the operation is a translation only and that the query is not executed. It also clarifies the relationship to run_query, which is valuable for understanding side effects.
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?
Two sentences with no filler. The core action is stated first, followed by a concrete usage recommendation. It is concise, scannable, and every clause adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one parameter, an output schema, and readOnly annotations, the description addresses all essential aspects: what the tool does, that it does not run the query, what it is useful for, and how to proceed afterward. Nothing critical is missing.
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?
The input schema only exposes 'query' with no description, and schema coverage is 0%, so the description carries the burden. The description compensates by indicating the parameter is a SQL SELECT statement that must be translatable, though it could explicitly name the parameter for absolute clarity.
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?
The description clearly states a specific action: translating an Elasticsearch SQL SELECT into native Query DSL via _sql/translate, and notes that it does not execute the query. This distinguishes it from siblings like run_query and sql_query, which actually run queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains when to use the tool: to learn the DSL for a query. It also names run_query as the next step for full control and implies the appropriate workflow, giving the agent a clear decision path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![elasticsearch_mcp MCP server](https://glama.ai/mcp/servers/baburajr/elasticsearch_mcp/badges/card.svg)](https://glama.ai/mcp/servers/baburajr/elasticsearch_mcp)

Score Badge

Copy to your README.md:

[![elasticsearch_mcp MCP server](https://glama.ai/mcp/servers/baburajr/elasticsearch_mcp/badges/score.svg)](https://glama.ai/mcp/servers/baburajr/elasticsearch_mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/baburajr/elasticsearch_mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server