Allows interaction with an Elasticsearch 7.x cluster, including searching and retrieving documents, managing indices, mappings, aliases, and templates, reindexing data, checking cluster health and tasks, and optionally performing read-only diagnostics or destructive admin operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@elasticsearch7-mcp check cluster health and show the last 5 docs in logs-*"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Server for connecting to your Elasticsearch cluster directly from any MCP Client (like Claude Desktop, Cursor).
This fork targets Elasticsearch 7.x only. It pins the @elastic/elasticsearch 7.17 client,
whose product check accepts servers older than 7.14. For an Elasticsearch 8.x cluster, use the
upstream project @awesome-ai/elasticsearch-mcp,
which this fork is derived from — the 8.x client cannot talk to a 7.x server, and vice versa.
This server connects agents to your Elasticsearch data using the Model Context Protocol. It allows you to interact with your Elasticsearch indices through natural language conversations.
Tools come in three sets. Only the first is always exposed; the other two are
opt-in through an environment variable, so a production deployment can offer
diagnostics without offering deletes. Gating happens at registration: a disabled
tool never appears in tools/list, so the model cannot call it and it costs
nothing in the agent's context.
elasticsearch_health: cluster health, optionally down to index level
cluster_info: cluster name, Elasticsearch version and build flavour
list_indices: list indices, filtered by an Elasticsearch wildcard (log-*)
create_index: create an index with optional settings and mappings
reindex: copy an index, optionally filtered by a query or transformed by a script
get_aliases: which aliases point at which indices
get_mappings: the fields of an index, as dotted paths with their types, then the raw mapping
create_mapping: create or update the mapping of an index
search: run a query DSL search, with highlighting injected over every text field — nested ones included — unless the query brings its own highlight
count: how many documents match, without transferring any
get_document: fetch one document by id
bulk: index many documents at once
create_index_template: create or update a composable index template
get_index_template: read index templates
field_caps: which fields exist across an index pattern, and whether each is searchable and aggregatable. Takes a wildcard, unlike get_mappings — and it is the only way to see a field mapped as two different types across indices, which makes an aggregation over it silently partial rather than failing.
analyze: the terms a text is broken into, which is what a query must produce to match. This is the answer to "my search returns nothing and I do not know why".
get_task: progress of a long-running task, such as the one reindex returns
ES_ADMIN_TOOLS=true — diagnostics (read-only)These only read, so they are safe to enable in production — and are the point of this set: an agent can then explain why an index is unhealthy without anyone logging into the cluster.
explain_allocation: why a shard is unassigned, with each allocator's decision
list_shards: shard-level state, leading with the copies that are not STARTED
list_nodes: heap, CPU, load and disk pressure per node
get_node_stats: garbage collection, thread pool queues and rejections, tripped breakers — the counters list_nodes cannot show
get_index_stats: per-index counters — size, segments, indexing, search, merges
get_index_settings: an index's settings (refresh_interval, replicas, read-only blocks)
get_cluster_settings: cluster settings that were overridden at runtime
list_tasks: what the cluster is currently running
ES_ALLOW_DESTRUCTIVE=true — irreversibleIntended for a staging environment, and off by default so production cannot reach them at all.
delete_index: delete an index and its data
delete_document: delete one document by id
delete_by_query: delete every document matching a query — asynchronous, it returns a task id and the deletion continues in the background
delete_index_template: delete an index template
Even with the flag on, these refuse a wildcard, a comma-separated list, * and
_all: they act on one named index at a time. A model that mistakes logs-*
for a single index gets a refusal instead of an emptied cluster.
ES_ECS_TOOLS=true — ECS log search (read-only)Five tools for clusters whose application logs are in ECS. They take named parameters instead of a query DSL and answer in log lines instead of JSON documents, because the schema is known in advance — which is also what lets them request only the fields they print.
They need ES_ECS_INDEX_PATTERN, which has no default: the server refuses to
start with the flag on and the pattern missing. A guess like logs-* would sweep
whichever indices happen to match on your cluster and answer confidently from the
wrong data.
search_logs: recent events, newest first, one line each — filter by service, env, levels/minLevel, host, logger, dataset, traceId, requestId and free text, over a window given as 15m, 2h, 7d
log_histogram: counts per time bucket, to see when something started, peaked or stopped. The bucket width is derived from the window, and empty buckets are kept because a gap is part of the answer
error_summary: errors grouped by error.type, with counts, first and last occurrence, affected services and a sample message
trace_request: one request across every service that handled it, oldest first, with the chain of services it travelled through and its failing events. Matches trace.id or http.request.id, so it works whether or not your stack emits distributed traces
top_values: the most frequent values of a field — what your cluster actually indexes, before you filter on a guess
env matters on a shared logging cluster. Where several environments are
collected into one set of indices, omitting env sums them, and nothing in the
answer says that it is a sum. Measured on one such cluster: a service reporting
390 errors over a day was 210 from integration, 179 from acceptance and 1 from
qualification. Run top_values on service.environment to see whether yours is
arranged that way.
trace_request is the "where did this come from" tool. The other four
aggregate across requests, so none of them can attribute a failure to a call two
services further down. It reads oldest-first, because a chain is followed
forwards, and its chain and failing events come from aggregations — so they stay
complete even when the timeline is capped by limit.
These target ECS 1.x field types, because that is what Elasticsearch 7.8 can
express. match_only_text arrived in 7.14 and wildcard in 7.9, so a mapping
pushed to a 7.8 cluster necessarily predates ECS 1.12, where error.message and
error.stack_trace moved to those types.
The consequence is visible in the tools: error.message is text with no
keyword sub-field, so errors cannot be grouped by message — error_summary
groups by error.type and gives events lacking one their own reported bucket
rather than dropping them. Grouping by error.stack_trace looks possible, since
ECS 1.x types it as keyword, but ECS sets ignore_above: 1024 on keywords, so
a longer trace is not indexed and would silently vanish from the aggregation.
Enabling this set adds about 8.4 KB to the tools/list response every
session, which is why it is a flag: a cluster whose logs are not in ECS would
pay for four tool schemas that can only return nothing.
The MCP Client analyzes your request and determines which Elasticsearch operations are needed.
The MCP server carries out these operations (listing indices, fetching mappings, performing searches).
The MCP Client processes the results and presents them in a user-friendly format.
Related MCP server: Elasticsearch 7.x MCP Server
An Elasticsearch 7.x instance (tested against 7.8; the 7.17 client supports 6.8 through 7.x)
Elasticsearch credentials — an API key, or a username and password
An MCP client: Claude Code, Claude Desktop, Codex, Cursor, or anything else that speaks MCP over stdio
This package is published toGitHub Packages, not npmjs.com, and GitHub
Packages requires a token even for public packages. Until you add one, every
install below fails with a 401. Put it in your user-level ~/.npmrc:
@agrica:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKENYOUR_GITHUB_TOKEN is a personal access token with the read:packages scope.
Keep it in your own ~/.npmrc rather than a project file — a token committed
to a repository is a leaked token, and some package managers refuse to read one
from there at all.
Every example below sets ES_HOST and ES_API_KEY. Swap in
ES_USERNAME/ES_PASSWORD for basic auth or the ES_OAUTH_* variables for
OAuth2 (see OAuth2), add ES_ADMIN_TOOLS=true to get
the diagnostic tools, and set ES_INSTANCE_LABEL when more than one instance is
declared — see Configuration Options.
claude mcp add elasticsearch7 \
--env ES_HOST=https://your-cluster:9200 \
--env ES_API_KEY=your-api-key \
--env ES_ADMIN_TOOLS=true \
-- npx -y @agrica/elasticsearch7-mcpThen /mcp in a session lists the server and its tools.
Two details that are easy to get wrong:
Everything after -- is the command that runs the server; without it, Claude
Code would try to parse -y as one of its own flags.
Do not put the server name straight after --env — the CLI reads it as
another KEY=value pair and rejects it. Above, the name comes first, which is
why it works.
The server is added at local scope, so it loads in the current project only. Add
--scope user to get it everywhere, or --scope project to write it into
.mcp.json and share it with your team — mind that a committed .mcp.json
would carry your API key, so prefer user scope for credentials.
Edit claude_desktop_config.json — Settings > Developer > Edit Config opens
it, or find it at %APPDATA%\Claude\ on Windows and
~/Library/Application Support/Claude/ on macOS:
{
"mcpServers": {
"elasticsearch7": {
"command": "npx",
"args": ["-y", "@agrica/elasticsearch7-mcp"],
"env": {
"ES_HOST": "https://your-cluster:9200",
"ES_API_KEY": "your-api-key",
"ES_ADMIN_TOOLS": "true"
}
}
}
}Restart Claude Desktop afterwards; it only reads that file at startup.
codex mcp add elasticsearch7 \
--env ES_HOST=https://your-cluster:9200 \
--env ES_API_KEY=your-api-key \
-- npx -y @agrica/elasticsearch7-mcpOr write it into ~/.codex/config.toml by hand. Note that Codex spells the
table mcp_servers with an underscore, and that the environment goes in its own
sub-table rather than inline:
[mcp_servers.elasticsearch7]
command = "npx"
args = ["-y", "@agrica/elasticsearch7-mcp"]
[mcp_servers.elasticsearch7.env]
ES_HOST = "https://your-cluster:9200"
ES_API_KEY = "your-api-key"
ES_ADMIN_TOOLS = "true"/mcp inside Codex confirms the server is loaded.
The server is a plain stdio MCP server, so anything on the
MCP client list works. It needs three
things: the command npx, the arguments -y @agrica/elasticsearch7-mcp, and the
ES_* variables in its environment. It never listens on a port, and writes
nothing but MCP protocol to stdout — diagnostics go to stderr.
The Elasticsearch MCP Server supports configuration options to connect to your Elasticsearch:
You must provide either an API key or both username and password for authentication.
Environment Variable | Description | Required |
| Your Elasticsearch instance URL(s) - supports single URL or comma-separated multiple URLs (also supports legacy | Yes |
| Elasticsearch API key for authentication (also supports legacy | No |
| Elasticsearch username for basic authentication (also supports legacy | No |
| Elasticsearch password for basic authentication (also supports legacy | No |
| Path to custom CA certificate for Elasticsearch SSL/TLS (also supports legacy | No |
| OAuth2 token endpoint. Setting it turns on OAuth2, which then takes precedence over the API key and basic auth. Must be | No |
| OAuth2 client id. Required once | No |
| OAuth2 client secret. Required once | No |
| Path to a file holding the secret, for a mounted Docker secret. Read and trimmed at startup. | No |
| Scope to request, if the provider needs one. | No |
| Audience to request. Auth0 needs it to issue a JWT; Keycloak and Azure AD use | No |
|
| No |
| Per-request timeout in milliseconds. Default | No |
| Retries per request. Default | No |
| Ceiling on one tool result. Default | No |
| Free-text name of this deployment, e.g. | No |
|
| No |
|
| No |
|
| No |
| Index pattern the ECS log tools query, e.g. | Only with |
ES_ADMIN_TOOLS, ES_ALLOW_DESTRUCTIVE and ES_ECS_TOOLS have no un-prefixed legacy alias,
unlike the connection variables above. That is deliberate: a bare ADMIN_TOOLS
or ALLOW_DESTRUCTIVE in an environment is far too easy to set by accident for
something that decides whether deletes are reachable.
Both accept true or 1; anything else, including an unset variable, means off.
Set ES_OAUTH_TOKEN_URL, ES_OAUTH_CLIENT_ID and ES_OAUTH_CLIENT_SECRET and
the server obtains a client_credentials token, renews it before it expires, and
sends it as Authorization: Bearer … on every request. It takes precedence over
ES_API_KEY and ES_USERNAME/ES_PASSWORD, and says so on stderr at startup if
those are still set — so you can see which identity is really talking to the
cluster.
What it is for. An Elasticsearch 7.x cluster cannot validate a third-party
OAuth2 token itself: the JWT realm arrived in 8.2, and the 7.x OIDC realm needs a
platinum licence and a browser. So this is for a cluster reached through a
gateway that validates the token and forwards the request. Point ES_HOST at
the gateway.
Keep the secret out of the config file. A project .mcp.json is checked into
version control, so reference the secret instead of pasting it:
{
"mcpServers": {
"elasticsearch": {
"command": "npx",
"args": ["-y", "@agrica/elasticsearch7-mcp"],
"env": {
"ES_HOST": "https://es-gateway.internal",
"ES_OAUTH_TOKEN_URL": "https://idp.internal/realms/data/protocol/openid-connect/token",
"ES_OAUTH_CLIENT_ID": "mcp-elasticsearch",
"ES_OAUTH_CLIENT_SECRET": "${ES_OAUTH_CLIENT_SECRET}",
"ES_OAUTH_SCOPE": "es:read"
}
}
}
}${VAR} is expanded from your own environment. The alternatives are a
user-scoped server entry (claude mcp add --scope local, stored outside the
repository) or ES_OAUTH_CLIENT_SECRET_FILE pointing at a mounted file.
Ask for the scope you can use. If the deployment runs without
ES_ALLOW_DESTRUCTIVE, request a read-only scope: a write scope buys nothing
when no write tool is registered, and widens what the secret is worth if it
leaks. When the gateway refuses a request for want of a scope, the error names
the one it asked for.
A tool result is capped at 32 KB (ES_MAX_RESULT_BYTES). This matters on a
logging cluster: before the cap, one list_shards call over a year of daily
indices returned 385 KB — around 96 000 tokens — in a single answer, which is
more than most sessions can hold.
When a result is trimmed it says so, says how much went, and says how to ask a smaller question. Three tools shape their answers around it:
list_indices and list_shards return a readable summary; the same rows as
text are behind verbose.
search caps size at 100 per call and tells you the from to page with.
get_mappings lists the fields first and the raw mapping second, so a
thousand-field index still answers the question it was asked.
Four tools — list_indices, list_shards, get_index_settings and
get_mappings — also return their answer as typed structured output, so a
client can read the rows instead of parsing the text. It is assembled from
whatever room the readable answer left, and reports returned against total
so a partial listing is visible as a number.
Run pnpm run measure against the built output to see the current figures for
your own configuration.
Most setups declare this server more than once — one entry per cluster. The
entries are otherwise identical, so a client shows two servers with the same
name and nothing to tell them apart. ES_INSTANCE_LABEL becomes the server's
display title, and it is the natural place to say which environment an entry
reaches:
{
"mcpServers": {
"es7-prod": {
"command": "npx",
"args": ["-y", "@agrica/elasticsearch7-mcp"],
"env": {
"ES_HOST": "https://es-prod:9200",
"ES_API_KEY": "prod-key",
"ES_INSTANCE_LABEL": "production",
"ES_ADMIN_TOOLS": "true"
}
},
"es7-staging": {
"command": "npx",
"args": ["-y", "@agrica/elasticsearch7-mcp"],
"env": {
"ES_HOST": "https://es-staging:9200",
"ES_API_KEY": "staging-key",
"ES_INSTANCE_LABEL": "staging",
"ES_ADMIN_TOOLS": "true",
"ES_ALLOW_DESTRUCTIVE": "true"
}
}
}
}That pair is the intended shape: diagnostics on both, deletes only on staging. Production keeps the tools that explain an unhealthy index and never exposes one that can remove data — the model cannot call what was never registered.
The label is also printed to stderr at startup, which is where to look when a client reports a connection but you cannot tell which cluster answered.
You can configure multiple Elasticsearch nodes for high availability and load balancing:
{
"mcpServers": {
"elasticsearch7-mcp": {
"command": "npx",
"args": [
"-y",
"@agrica/elasticsearch7-mcp"
],
"env": {
"ES_HOST": "https://es-node1:9200,https://es-node2:9200,https://es-node3:9200",
"ES_API_KEY": "your-api-key"
}
}
}
}The client will automatically handle failover and load balancing between the configured nodes.
Each release publishes a multi-arch image (linux/amd64, linux/arm64) to the
GitHub Container Registry:
docker pull ghcr.io/agrica/elasticsearch7-mcp:latestThe server speaks stdio, so the container needs an interactive stdin and no published port. In an MCP client:
{
"mcpServers": {
"elasticsearch7-mcp": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "ES_HOST",
"-e", "ES_API_KEY",
"ghcr.io/agrica/elasticsearch7-mcp:latest"
],
"env": {
"ES_HOST": "your-elasticsearch-host",
"ES_API_KEY": "your-api-key"
}
}
}
}Like the npm package, the image lives in GitHub Packages: pulling it requires a
token with theread:packages scope, even though the repository is public.
The image needs no port published and no volume: it speaks stdio, and the MCP client owns its stdin and stdout.
Here are some natural language queries you can try with your MCP Client.
"What is the health status of my Elasticsearch cluster?"
"How many active nodes are in my cluster?"
"What indices do I have in my Elasticsearch cluster?"
"Create a new index called 'users' with 3 shards and 1 replica."
"Reindex data from 'old_index' to 'new_index'."
"Show me the field mappings for the 'products' index."
"Add a keyword type field called 'tags' to the 'products' index."
"Find all orders over $500 from last month."
"Which products received the most 5-star reviews?"
"Bulk import these customer records into the 'customers' index."
"Create an index template for logs with pattern 'logs-*'."
"Show me all my index templates."
ES_ADMIN_TOOLS=true)"The 'logs-2026' index is yellow — why are its shards unassigned?"
"Is any node close to a disk watermark?"
"Is the cluster rejecting writes, or spending its time in garbage collection?"
"Which of my indices is the largest, and how much of it is deleted documents?"
"Has anyone disabled shard allocation on this cluster?"
"Is a reindex still running?"
ES_ECS_TOOLS=true)"What errors has the billing service logged in the last hour?"
"When did the 5xx spike start, and is it still going?"
"Which hosts are producing these timeouts?"
"What log levels does this cluster actually index?"
"Follow request aowQJmtrwvjJOWI3TyL_SAAAAA4 — which service did it fail in?"
"How many errors on the billing service in acceptance, not counting the other environments?"
ES_ALLOW_DESTRUCTIVE=true)"Delete the 'smoke-test-source' index."
"Remove every document older than 2024 from 'logs-archive'."
Symptom | Cause |
| No GitHub Packages token in your user-level |
|
|
| An |
| The token endpoint could not be reached, or refused the credentials. The message carries the provider's own |
| The gateway wants a scope the token does not carry. Add it to |
The client connects, but a diagnostic or delete tool is missing | That set is gated. Set |
|
|
Every tool times out, and | The client asks for the cluster root at the prefix without a trailing slash — |
| A keyword filter did not match the indexed spelling. |
| Aggregations need a keyword. Try |
| Working as intended: destructive tools take one concrete index name, never a pattern, even with the flag on. |
A connection error mentioning the product check | The cluster is 8.x, or unreachable. This build talks to 7.x only. |
Found a bug or want a tool that is missing? Open an issue on the GitHub repository. To work on the code, start from CONTRIBUTING.md.
Show the terms a text is broken into, which is what a query must produce to match. Pass field with index to use the analyzer that index really applies to that field; that is the form that explains a search returning nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Text to analyze | |
| field | No | Use this field's analyzer, taken from the index mapping. | |
| index | No | Index whose analyzers to use. Required with field. | |
| analyzer | No | Named analyzer to test instead, e.g. standard, french. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive, so no safety disclosure is missing. The description adds semantic behavior: output is the token terms a query must match, and using field/index routes to the real per-field analyzer. It neither contradicts annotations nor reveals side-effect caveats beyond that, so a mid score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, the first states the core function and the second adds the key usage nuance. No filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only diagnostic with one required parameter, the description plus schema covers what the tool does, how to choose a real-field analyzer, and why it matters for debugging searches. No output schema exists, but the description directly states the observable result ('terms a text is broken into'). It doesn't discuss response shape details, but they are unnecessary for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameter basics are already documented. The description adds the important combination rule (field must be paired with index) and explains that the analyzer is taken from the index mapping, which is value beyond individual property docs. It earns an above-baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete operation — showing the tokenized terms produced from text — and ties it to query matching, so an agent understands what analyze returns. It also distinguishes the field/index form from a standalone analyzer test. This goes well beyond the vague title.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit guidance on the field-index combination as the way to use the actual analyzer applied by the index, and states this is the form that explains an empty search result. It doesn't explicitly enumerate alternatives or when to use the analyzer parameter, but the context is sufficient for a user to choose sensibly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Index up to 1000 documents in one call. The index is refreshed by default, so they are searchable immediately; per-document failures are reported without failing the call.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Target index | |
| idField | No | Field whose value becomes the document _id. Omit to let Elasticsearch generate ids. | |
| refresh | No | Defaults to true, making documents searchable at once. Set false when loading many batches: forcing a refresh per batch is the expensive part. | |
| documents | Yes | Documents to index, at most 1000. Send more in successive batches. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral detail beyond the annotations: the index is refreshed by default so documents are immediately searchable, and per-document failures are reported without failing the whole call. This meaningfully informs the agent about side effects and error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences deliver the key information without redundancy: the action, the batch limit, the refresh behavior, and the failure handling. It is front-loaded with the most important operational constraint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a complete input schema, a moderate number of parameters, and annotations covering the read/write profile, the description covers the important behavioral nuances—immediate searchability and partial failures. No critical information for invoking the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well documented in the schema. The description reinforces the 1000-document limit and the default refresh behavior, but adds little semantic value beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Index'), a concrete resource ('documents'), and a clear constraint ('up to 1000 documents in one call'). This clearly separates it from siblings like create_index, create_mapping, and reindex, which target different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes when bulk indexing is appropriate: when you have up to 1000 documents to index in a single call. It also explains the default refresh behavior, which helps an agent decide when to override it. It does not explicitly name alternatives, but the batching context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cluster name, Elasticsearch version and build flavour. The version decides which query DSL features exist.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful context about the returned fields and the role of the version, but it does not disclose additional behavioral traits like response structure, authentication needs, or whether values are cached.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences: the first front-loads the exact fields returned, and the second gives a brief reason the version matters. There is no filler or redundant restating of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, read-only metadata tool without an output schema, the description adequately covers what the agent gets (name, version, flavour) and why version is useful. It could be slightly richer by noting the response is a flat JSON object, but that is a minor omission for such a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is no parameter burden on the description. The schema is effectively empty and the baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (cluster identity: name, version, build flavour), but it uses a noun phrase rather than a specific verb like 'returns' or 'lists'. It is distinguishable from siblings by its focus on cluster metadata, yet it never explicitly differentiates itself from elasticsearch_health or other info tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The statement 'The version decides which query DSL features exist' implies when this tool is relevant: checking version-dependent DSL feature support. However, it does not explicitly say when to use it versus alternatives, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Count the documents matching a query, without transferring any. Cheaper than search when only the number matters.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Index to count in | |
| query | No | Query DSL. Omit to count every document. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond annotations: no documents are transferred and this operation is cheaper than search. This is meaningful information without contradicting 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no redundant words. The core action is front-loaded and the benefit/alternative is stated in the second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only counting tool, the description, schema, and annotations together cover the required parameters, the optional query behavior, the safety profile, and the use case. The return value (a count) is obvious from the tool's purpose, so no output schema is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents index and query, including that omitting query counts every document. The description does not add further parameter-level meaning but does not need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pairing ('Count the documents matching a query') and immediately differentiates from the sibling search tool by noting it transfers no documents. An agent can tell exactly what operation this performs and how it differs from search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the condition for choosing count over search: 'when only the number matters,' and notes it is 'Cheaper than search.' The phrase 'without transferring any' also implies that search should be used when actual documents are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new index. Fails if it already exists — use create_mapping to add fields to an existing one.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Index name | |
| mappings | No | Field mappings, e.g. { properties: { title: { type: 'text' } } } | |
| settings | No | Index settings, e.g. number_of_shards, number_of_replicas |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a valuable behavioral detail beyond the annotations: the operation fails rather than overwriting when the index already exists. This complements the annotations, which already indicate a non-read-only, non-idempotent write operation. It does not elaborate on all side effects, but the conflict behavior is the key operational trait.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. It leads with the core action, then immediately states the failure condition and the correct alternative. Every sentence serves a distinct purpose and the structure makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, together with the fully documented schema and annotations, provides enough context for correct invocation: required parameter, optional mapping/settings parameters, and the failure mode. It does not mention the create_index_template sibling, but that is not essential for invoking this specific tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are already documented in the input schema, including examples for mappings and settings, so schema coverage is 100%. The description does not add additional parameter-level meaning, but it does not need to; the schema carries that burden effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Create a new index.' It also differentiates itself from the closest sibling, create_mapping, by explicitly saying to use that tool for adding fields to an existing index. The purpose is immediately clear and not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: use this tool for creating a new index. It also gives an explicit when-not-to-use and alternative: 'Fails if it already exists — use create_mapping to add fields to an existing one.' This leaves little ambiguity about which tool to select.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update a composable index template (Elasticsearch 7.8+). It applies only to indices created after it, never to existing ones.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Template name | |
| version | No | Version number, for your own tracking | |
| priority | No | Precedence when several templates match; higher wins | |
| template | Yes | What to apply: { settings, mappings, aliases } | |
| indexPatterns | Yes | Index wildcards the template applies to, e.g. ['logs-*'] |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a mutating, idempotent, non-destructive operation. The description adds important behavior beyond the annotations: the Elasticsearch 7.8+ requirement and the non-retroactive nature of the template. No contradiction exists between description and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence communicates the action, resource, version constraint, and the most important behavioral caveat with no filler. The key scoping limitation is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool with 5 parameters, a nested template object, and no output schema, the description covers the decisive behavioral constraint and version compatibility while relying on the fully documented schema for parameter details. It does not mention the response format, but that is a minor gap for a create/update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters already have inline documentation. The description does not add substantial parameter-level meaning beyond the schema, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Create or update') and a specific resource ('composable index template'), which clearly distinguishes it from sibling tools like create_index or create_mapping. The version qualifier and 'applies only to indices created after it' add further precision about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this tool is for defining templates that affect future indices only, and it explicitly states it never affects existing indices. It does not name alternative tools for existing-index changes, but the exclusion is clear enough for an agent to reason about when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add or update fields on an index, creating the index if it does not exist. Elasticsearch cannot change the type of an existing field.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Index name | |
| mappings | Yes | Mapping to apply, e.g. { properties: { tags: { type: 'keyword' } } } |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent, non-read-only, and non-destructive behavior. The description adds valuable constraints beyond annotations, especially the critical limitation that 'Elasticsearch cannot change the type of an existing field', which helps agents anticipate failures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences. The first conveys the core action and index-creation behavior, and the second adds the most important caveat. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with a clear schema, the description covers the main behavioral caveat and typical usage. It does not describe the response shape, but given no output schema and the simplicity of the operation, the description is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters documented well; the mappings parameter even includes an example shape. The description itself adds no additional parameter-level detail, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Add or update') and resource ('fields on an index') and clarifies that it can create the index if needed. This clearly differentiates it from sibling tools like get_mappings or create_index.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this tool to mutate mappings, including when the index does not yet exist. It does not explicitly name alternatives or state when not to use it, but the operational scope is clear 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.
Cluster health: status, node counts and shard counts.
| Name | Required | Description | Default |
|---|---|---|---|
| includeIndices | No | Add per-index health detail |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the description does not need to re-establish safety. The description does add useful information about the return content (status, node counts, shard counts), which is helpful because there is no output schema. It does not add deeper behavioral context such as whether includeIndices changes response structure substantially, but that is partially covered by the parameter description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short, front-loaded sentence: 'Cluster health: status, node counts and shard counts.' Every word earns its place, and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with zero required parameters and a well-documented optional parameter, the description covers the essential return content. The annotations cover the safety profile, and the schema covers the parameter. It is only missing explicit guidance for distinguishing it from cluster_info, which is already penalized under usage guidelines.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the only parameter, includeIndices, already has a meaningful description: 'Add per-index health detail'. The tool description adds no additional parameter semantics beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the exact resource ('cluster health') and the specific output areas (status, node counts, shard counts), which makes the tool's purpose reasonably clear. It lacks an explicit verb like 'get', but the noun-phrase style with tool name 'elasticsearch_health' is sufficient. It is distinguishable from index-focused siblings like list_indices and get_mappings, though cluster_info could overlap without more detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. With sibling cluster_info likely covering similar cluster-level information, the absence of a routing note is a real gap. Any usage guidance is only implied by the name and the word 'health'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Which fields exist across an index pattern and whether each is searchable and aggregatable. Takes a wildcard, unlike get_mappings, and is the only way to see a field mapped as two different types across indices — which makes an aggregation over it silently partial rather than failing.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Index, alias or wildcard, e.g. logs-app-* | |
| fields | No | Field name or wildcard to ask about, e.g. log.* — comma-separated for several. Defaults to every field. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: wildcard acceptance, cross-index type conflict visibility, and the non-obvious consequence that aggregations over such fields become silently partial rather than failing. This is exactly the kind of behavioral warning an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the first delivers the core purpose, the second adds the distinguishing behavior and its operational warning. Every clause earns its place, and the most decision-relevant information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter, read-only tool, the description covers the essential facts: what it returns, how it differs from its sibling, and a critical edge-case consequence. The schema and annotations carry the remaining details, so nothing an agent needs 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters clearly, including wildcard behavior and defaults, giving 100% schema description coverage. The description does not substantially add parameter-level meaning beyond that, so the baseline of 3 is appropriate; it reinforces the wildcard theme but introduces no new parameter detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise statement of what the tool returns: fields across an index pattern plus whether each is searchable and aggregatable. It further distinguishes itself from get_mappings by calling out wildcard support and the special case of fields mapped as two different types, making the tool's identity unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names get_mappings as the alternative and gives a concrete differentiator ('Takes a wildcard, unlike get_mappings'). It also establishes a strong when-to-use condition: it is the only way to detect a field mapped as two different types. It does not spell out the reverse case ('use get_mappings when...'), but the intended routing is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List which aliases point to which indices. A name you query may be an alias, which changes what get_mappings returns.
| Name | Required | Description | Default |
|---|---|---|---|
| index | No | Index or wildcard. Omit for the whole cluster. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive behavior. The description adds behavioral context by warning that aliases affect get_mappings results, which is useful beyond the annotations. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The core purpose is front-loaded, and the second sentence adds valuable contextual information without unnecessary length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter and no output schema, the description provides sufficient guidance. It could mention what the response contains, but the annotations and sibling context cover most operational concerns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the optional 'index' parameter is already documented. The description doesn't add parameter-level detail beyond what the schema states, which matches the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List which aliases point to which indices.' It clearly communicates the tool's purpose and implicitly distinguishes it from sibling tools like list_indices and get_mappings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete context for when this tool matters: when a queried name may be an alias and alters what get_mappings returns. It does not explicitly name alternatives or exclusion criteria, but the usage context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one document by its _id. Reports that it is absent rather than failing.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document _id | |
| index | Yes | Index holding the document |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds a meaningful behavioral trait beyond those annotations: it reports that a document is absent rather than failing. This tells the agent how missing documents are handled, which is useful for interpreting results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no wasted words. The core action is front-loaded, and the second sentence adds a useful behavioral note. It is concise without sacrificing important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id tool with two fully documented parameters and strong annotations, the description is largely complete. It does not specify the exact return shape or concrete absent representation, such as null or an empty result, but 'Fetch one document' and 'Reports that it is absent rather than failing' cover the essential behavior an agent needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in the schema. The description adds little beyond the schema, aside from referring to '_id' in a way that maps to the id parameter. Baseline 3 is appropriate because the schema carries the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Fetch one document by its _id.' It clearly distinguishes this from sibling tools like search or get_index_template by narrowing scope to a single document identified by _id. The additional detail about reporting absence rather than failing reinforces its unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage context: use this tool when you need exactly one document by its _id. It does not explicitly name alternatives or exclusions, but the stated single-document-by-id behavior is enough to imply the appropriate scenario and separate it from broader search or listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get composable index templates. Omit name to list all.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Template name. Omit to list every template. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety semantics. The description adds the list-all behavior when name is omitted, but does not disclose output shape, errors, or other runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short, purposeful sentences with no filler. The main operation is front-loaded, and the optional-name behavior is expressed efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, optional-parameter, read-only tool with strong annotations, the description is nearly complete. It could mention the return format or that it returns template definitions, but an agent has enough information to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains that 'name' is optional and that omitting it lists every template. The description restates this without adding new semantic details, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation ('Get'), the resource ('composable index templates'), and the key behavior ('Omit name to list all'). This makes the tool's purpose immediately obvious and distinguishes it from create_index_template and other read-only sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear guidance on omitting the name to list all templates, but it does not explicitly discuss when to choose this tool over alternatives such as get_mappings or create_index_template. Usage context is mostly implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the fields of one index as dotted paths with their types, nested fields included, then the raw mapping. Give a concrete index name: an alias or a wildcard returns nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Index name |
| Name | Required | Description |
|---|---|---|
| found | Yes | |
| index | Yes | |
| total | Yes | |
| fields | Yes | |
| omitted | Yes | |
| returned | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond annotations by specifying the output format (dotted paths with types, then raw mapping) and the alias/wildcard caveat, which is exactly the kind of context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences front-load the tool's output behavior and then give the critical input constraint. Every sentence earns its place, with no filler or repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter schema, the presence of an output schema, and annotations covering safety, the description is complete. It explains what the response contains, when a call will succeed, and when it will return nothing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the single 'index' parameter with 100% coverage, so the baseline is 3. The description adds real semantic value by requiring a concrete index and warning that aliases and wildcards yield no results, which is not inferable from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List the fields of one index as dotted paths with their types') and a concrete resource ('one index'), and it distinguishes the tool by noting nested fields are included and the raw mapping follows. This separates get_mappings from siblings like get_index_template or field_caps without requiring the agent to inspect schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear operational guidance: pass a concrete index name, and avoid aliases or wildcards because they return nothing. It does not explicitly name alternative sibling tools, but the precondition and failure mode are actionable enough for an agent to decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check an asynchronous task, such as the one reindex returns: progress, completion and failure.
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | Task id as returned by reindex, e.g. node-1:428 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds that the task reports progress, completion, and failure, but it does not explain response format or polling behavior; this is modest added value beyond 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence that names the action, the resource, the source of the task id, and the relevant outcomes. Every phrase earns its place with no redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter polling tool with rich annotations, the description is complete: it says what to check, where the task id comes from, and what aspects are reported. No output schema exists, but the description names the key result dimensions well enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for taskId, including its meaning and an example. The description only reinforces that the task id comes from reindex, adding no new parameter semantics beyond what the schema already supplies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks an asynchronous task and identifies the specific scenario (tasks returned by reindex). It names the observable outcomes (progress, completion, failure), making the purpose unambiguous, though it does not explicitly differentiate from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context: use this after an asynchronous operation such as reindex that returns a task id. It does not state when-not-to-use or name alternatives, but the context is concrete enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List indices, one compact line each: name, health, status, document count and size in bytes. Large results are trimmed and say so.
| Name | Required | Description | Default |
|---|---|---|---|
| pattern | No | Elasticsearch wildcard, e.g. `logs-*`. Not a regex. Defaults to `*`. | |
| verbose | No | Also repeat the rows as JSON text, for a client that does not read structured output. |
| Name | Required | Description |
|---|---|---|
| total | Yes | |
| indices | Yes | |
| omitted | Yes | |
| pattern | Yes | |
| returned | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the read-only and idempotent annotations by disclosing the compact per-line format and the important trimming behavior for large results. This prevents an agent from assuming the output is always complete. Safety is already covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences front-load the purpose and output shape, then add the trimming caveat. Every phrase earns its place and there is no boilerplate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only two optional parameters, a full output schema, and annotations covering safety and idempotence, the description supplies the key behavioral caveat (trimming) and output fields. An agent has everything needed to invoke list_indices correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters at 100% coverage, including the wildcard-vs-regex distinction for pattern and the purpose of verbose. The description adds no parameter-level detail, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific operation ('List indices') and defines the exact output fields (name, health, status, document count, size in bytes), making it immediately distinguishable from sibling tools like get_mappings or field_caps. It clearly identifies the resource and the compact representation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The output description clearly implies its use case: obtaining a compact overview of indices with health and size information. It does not explicitly name sibling alternatives or state exclusions, so it falls just short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Copy documents between indices. Asynchronous: returns a task id at once and the copy is still running on return — poll it with GET _tasks/.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Query DSL selecting which documents to copy. Omit to copy all. | |
| script | No | Transform each document while copying | |
| destIndex | Yes | Destination index, created if absent | |
| sourceIndex | Yes | Source index |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by disclosing the crucial asynchronous behavior: it returns a task id immediately while the copy continues, and it tells the caller how to poll progress. Annotations already cover read/write/destructive aspects, and the description adds meaningful operational context 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the first states the action clearly, and the second adds the key behavioral caveat and how to follow up. No filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with nested parameters and no output schema, the description explains the main return signal (task id) and the continuation mechanism. It is sufficient for an agent to select and invoke the tool correctly, though it does not detail edge cases or result formats beyond the task id.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents sourceIndex, destIndex, query, and script with meaningful descriptions. The tool description adds no parameter-specific detail, but the schema carries that burden fully, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource pair: 'Copy documents between indices.' This clearly distinguishes reindex from read-only search, single-document get, and indexing/bulk operations, and the title reinforces the same intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when documents must be copied between indices. However, it does not explicitly explain when not to use it or mention alternatives such as bulk for direct writes or search for read-only queries. The async polling hint gives practical usage context, but no explicit routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search one index with a query DSL body. Matching text fields are highlighted. Paging goes inside queryBody (size, from); size is capped at 100 per call, so page with from for more.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Index to search | |
| queryBody | Yes | Query DSL body: query, size, from, sort, aggs, _source. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide safety signals (readOnly, idempotent, non-destructive). The description adds valuable behavioral details beyond those: highlighting behavior and the hard cap on `size`. This is meaningful operational context that the annotations do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each contributing necessary information: scope, highlighting behavior, and paging constraints. The most important usage constraint is front-loaded. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description sufficiently covers scope, input, highlighting, and paging constraints. There is no output schema, and the description does not detail the response structure, but the core behavior and critical operational details are present. Slight gap around return format, but not severe for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema documents both parameters well. The description adds extra semantic value by explaining how paging works inside queryBody and the size limit, which is not obvious from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Search one index') and resource ('one index') with a query DSL body, clearly distinguishing it from sibling tools like count, get_document, and list_indices. The scope is precise and immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete usage guidance on paging, including the size cap of 100 and how to use `from` for more results. It does not explicitly compare to alternatives like count or get_document, but the 'one index' scoping and query DSL focus provide clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.4.1analyzebulkcluster_infocountcreate_indexcreate_index_templatecreate_mappingelasticsearch_healthfield_capsget_aliasesget_documentget_index_templateget_mappingsget_tasklist_indicesreindexsearchScored across 17 tools
Each tool targets a distinct operation or resource: field inspection is split cleanly between get_mappings and field_caps, with explicit notes about wildcard vs concrete index behavior. create_index, create_mapping, bulk, and reindex are also clearly differentiated, so an agent should not confuse them.
Most tools use get_, list_, or create_ prefixes, but bare nouns and verbs like bulk, count, reindex, field_caps, cluster_info, and elasticsearch_health break the verb_noun pattern. Naming is readable and consistently snake_case, but the conventions are mixed.
17 tools is on the heavy side for a single server and makes agent tool selection slightly harder. Each tool does map to a real Elasticsearch operation, so the count is not excessive, but it is borderline.
The surface covers health, mappings, search, indexing, and templates, but lacks delete/update operations for documents and indices, and has no deletion for aliases or templates. This creates significant dead ends for common lifecycle workflows.
Agent-driven search: build, import, tune, search, and score result quality — all over MCP.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
MCP server for searching Airweave collections with natural language queries.
Official Microsoft MCP Server to query Microsoft Entra data using natural language
