Allows AI assistants to interact with OpenSearch clusters, providing tools for searching indices, retrieving mappings, managing shards, and other cluster 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., "@OpenSearch MCP Server Search the 'logs' index for documents with status:error"
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.
opensearch-mcp-server-py is a Model Context Protocol (MCP) server for OpenSearch that enables AI assistants to interact with OpenSearch clusters. It provides a standardized interface for AI models to perform operations like searching indices, retrieving mappings, and managing shards through both stdio and streaming (SSE/Streamable HTTP) protocols.
Key features:
Seamless integration with AI assistants and LLMs through the MCP protocol
Support for both stdio and streaming server transports (SSE and Streamable HTTP)
Built-in tools for common OpenSearch operations
Easy integration with Claude Desktop and LangChain
Secure authentication using basic auth, IAM roles, header-based auth, and OpenSearch mTLS
For detailed setup, including Kubernetes deployment and mTLS configuration, see the User Guide.
Related MCP server: TianGong-AI-MCP
Opensearch-mcp-server-py can be installed from PyPI via pip:
pip install opensearch-mcp-server-pyBy default, only core tools are enabled to provide essential OpenSearch functionality:
Core tools are grouped under the core_tools category and can be disabled at once using OPENSEARCH_DISABLED_CATEGORIES=core_tools. Avoid creating custom categories with this name as they will override the built-in category.
ListIndexTool: Lists all indices in OpenSearch with full information including docs.count, docs.deleted, store.size, etc. If an index parameter is provided, returns detailed information about that specific index.
IndexMappingTool: Retrieves index mapping and setting information for an index in OpenSearch.
SearchIndexTool: Searches an index using a query written in query domain-specific language (DSL) in OpenSearch.
GetShardsTool: Gets information about shards in OpenSearch.
ClusterHealthTool: Returns basic information about the health of the cluster.
CountTool: Returns number of documents matching a query.
ExplainTool: Returns information about why a specific document matches (or doesn't match) a query.
MsearchTool: Allows to execute several search operations in one request.
[GenericOpenSearchApiTool]: A flexible tool that can call any OpenSearch API endpoint with custom paths, methods, query parameters, and request bodies. Reduces tool explosion by providing a single interface for all OpenSearch APIs.
The following tools are available but disabled by default. To enable them, see the Tool Filter section in the User Guide.
GetClusterStateTool: Gets the current state of the cluster including node information, index settings, and more.
GetSegmentsTool: Gets information about Lucene segments in indices, including memory usage, document counts, and segment sizes.
CatNodesTool: Gets information about nodes in the OpenSearch cluster, including system metrics like CPU usage, memory, disk space, and node roles.
GetNodesTool: Gets detailed information about nodes in the OpenSearch cluster, including static information like host system details, JVM info, processor type, node settings, thread pools, installed plugins, and more.
GetIndexInfoTool: Gets detailed information about an index including mappings, settings, and aliases. Supports wildcards in index names.
GetIndexStatsTool: Gets statistics about an index including document count, store size, indexing and search performance metrics.
GetQueryInsightsTool: Gets query insights from the /_insights/top_queries endpoint, showing information about query patterns and performance.
GetNodesHotThreadsTool: Gets information about hot threads in the cluster nodes from the /_nodes/hot_threads endpoint.
GetAllocationTool: Gets information about shard allocation across nodes in the cluster from the /_cat/allocation endpoint.
GetLongRunningTasksTool: Gets information about long-running tasks in the cluster, sorted by running time in descending order.
Search Relevance Workbench tools are grouped under the search_relevance category and can be enabled at once using OPENSEARCH_ENABLED_CATEGORIES=search_relevance or by adding enabled_categories: [search_relevance] or explicitly adding individual tools to their config file. See the Tool Filter section in the User Guide for additional information about how to filter tools.
CreateSearchConfigurationTool: Creates a search configuration consisting of a name, a query body (a query in OpenSearch query domain-specific language), and the target index.
GetSearchConfigurationTool: Retrieves a search configuration by ID.
DeleteSearchConfigurationTool: Deletes a search configuration by ID.
CreateQuerySetTool: Creates a query set consisting of a name, a description, and a list of queries.
SampleQuerySetTool: Samples a query set based on UBI data with different statistical sampling techniques.
GetQuerySetTool: Retrieves a query set by ID.
DeleteQuerySetTool: Deletes a query set by ID.
CreateJudgmentListTool: Creates a judgment list with judgments originating from an external process.
CreateLLMJudgmentListTool: Creates a judgment list by using an LLM.
CreateUBIJudgmentListTool: Creates a judgment list based on implicit feedback (User Behavior Insights data).
GetJudgmentListTool: Retrieves a judgment list by ID.
DeleteJudgmentListTool: Deletes a judgment list by ID.
CreateExperimentTool: Creates a search relevance experiment. Supports PAIRWISE_COMPARISON (compares 2 search configurations), POINTWISE_EVALUATION (evaluates 1 configuration against judgment lists), and HYBRID_OPTIMIZER (optimizes 1 configuration using judgment lists).
GetExperimentTool: Retrieves an experiment by ID.
DeleteExperimentTool: Deletes an experiment by ID.
SearchQuerySetsTool: Searches query sets using OpenSearch query DSL. Defaults to match_all if no query body is provided.
SearchSearchConfigurationsTool: Searches search configurations using OpenSearch query DSL. Defaults to match_all if no query body is provided.
SearchJudgmentsTool: Searches judgments using OpenSearch query DSL. Defaults to match_all if no query body is provided.
SearchExperimentsTool: Searches experiments using OpenSearch query DSL. Defaults to match_all if no query body is provided.
Advanced analysis tools for data analysis and troubleshooting.
DataDistributionTool: Analyzes data distribution patterns and field value frequencies within OpenSearch indices. Supports both single dataset analysis and comparative analysis between two time periods to identify distribution changes.
LogPatternAnalysisTool: Detects anomalous log patterns and sequences through comparative analysis between baseline and selection time ranges. Supports log sequence analysis with trace correlation, log pattern difference analysis, and log insights analysis for error detection.
ListIndexTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
index (optional): The name of the index to get detailed information for. If provided, returns detailed information about this specific index instead of listing all indices.
IndexMappingTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
index (required): The name of the index to retrieve mappings for
SearchIndexTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
index (required): The name of the index to search in
query_dsl (required): The search query in OpenSearch Query DSL format
format (optional): The format of SearchIndexTool response. options are csv and json
size (optional): The size of SearchIndexTool response. Default is 10, maximum is 100 (configurable). To change the maximum limit, set max_size_limit via CLI arguments or config file. See Tool Customization for details.
GetShardsTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
index (required): The name of the index to get shard information for
ClusterHealthTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
index (optional): Limit health reporting to a specific index
CountTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
index (optional): The name of the index to count documents in
body (optional): Query in JSON format to filter documents
ExplainTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
index (required): The name of the index to retrieve the document from
id (required): The document ID to explain
body (required): Query in JSON format to explain against the document
MsearchTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
index (optional): Default index to search in
body (required): Multi-search request body in NDJSON format
GetClusterStateTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
metric (optional): Limit the information returned to the specified metrics. Options include: _all, blocks, metadata, nodes, routing_table, routing_nodes, master_node, version
index (optional): Limit the information returned to the specified indices
GetSegmentsTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
index (optional): Limit the information returned to the specified indices. If not provided, returns segments for all indices
CatNodesTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
metrics (optional): A comma-separated list of metrics to display. Available metrics include: id, name, ip, port, role, master, heap.percent, ram.percent, cpu, load_1m, load_5m, load_15m, disk.total, disk.used, disk.avail, disk.used_percent
GetNodesTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
node_id (optional): A comma-separated list of node IDs or names to limit the returned information. Supports node filters like _local, _master, master:true, data:false, etc. Defaults to _all.
metric (optional): A comma-separated list of metric groups to include in the response. Options include: settings, os, process, jvm, thread_pool, transport, http, plugins, ingest, aggregations, indices. Defaults to all metrics.
GetIndexInfoTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
index (required): The name of the index to get detailed information for. Wildcards are supported.
GetIndexStatsTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
index (required): The name of the index to get statistics for. Wildcards are supported.
metric (optional): Limit the information returned to the specified metrics. Options include: _all, completion, docs, fielddata, flush, get, indexing, merge, query_cache, refresh, request_cache, search, segments, store, warmer, bulk
GetQueryInsightsTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
GetNodesHotThreadsTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
GetAllocationTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
GetLongRunningTasksTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
limit (optional): The maximum number of tasks to return. Default is 10.
DataDistributionTool
index (required): Target OpenSearch index name.
selectionTimeRangeStart (required): Start time for analysis target period.
selectionTimeRangeEnd (required): End time for analysis target period.
timeField (required): Date/time field for filtering.
baselineTimeRangeStart (optional): Start time for baseline period.
baselineTimeRangeEnd (optional): End time for baseline period.
size (optional): Maximum number of documents to analyze. Default is 1000.
LogPatternAnalysisTool
index (required): Target OpenSearch index name containing log data.
logFieldName (required): Field containing raw log messages to analyze.
selectionTimeRangeStart (required): Start time for analysis target period.
selectionTimeRangeEnd (required): End time for analysis target period.
timeField (required): Date/time field for time-based filtering.
traceFieldName (optional): Field for trace/correlation ID.
baseTimeRangeStart (optional): Start time for baseline comparison period.
baseTimeRangeEnd (optional): End time for baseline comparison period.
More tools coming soon. Click here
For detailed usage instructions, configuration options, and examples, please see the User Guide.
Interested in contributing? Check out our:
Development Guide - Setup your development environment
Contributing Guidelines - Learn how to contribute
This project has adopted the Amazon Open Source Code of Conduct. For more information see the Code of Conduct FAQ, or contact opensource-codeofconduct@amazon.com with any additional questions or comments.
This project is licensed under the Apache v2.0 License.
Copyright 2020-2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
Returns basic information about the health of the cluster.
| Name | Required | Description | Default |
|---|---|---|---|
| index | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should fully disclose behavioral traits. It only says it returns information, omitting critical details such as whether it requires special permissions, if it is read-only, or what side-effects (if any) exist. This is insufficient for safe invocation.
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, concise sentence with no wasted words. However, it may be too terse, sacrificing completeness for brevity.
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 tool's simplicity (one optional parameter, no output schema), the description should at least cover the parameter's role and what 'basic information' entails. It fails to do so, making it incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (index) with 0% description coverage, and the description does not mention or explain it. The parameter's purpose and expected values are entirely undocumented, adding no value beyond the schema itself.
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 it returns basic cluster health information, using a specific verb (returns) and resource (cluster health). However, it does not differentiate from sibling tools like ListIndexTool or ExplainTool, which could also provide health-related data.
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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or when not to use it, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns number of documents matching a query.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Request body | |
| index | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears the full burden of behavioral disclosure. It only states that it returns a count, without addressing read-only nature, authentication, rate limits, side effects, or the query's impact. The description is insufficient for an agent to understand the tool's 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 a single concise sentence with no wasted words. However, it omits critical information that could be added without sacrificing conciseness, such as parameter guidance or query format hints.
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 tool's simplicity, lack of annotations, 50% schema coverage, no output schema, and multiple sibling tools, the description is too brief. It fails to explain the expected query structure in 'body', how to specify the index, or the return format (e.g., integer). This leaves the agent underinformed.
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 50% (only the 'body' parameter has a vague description, 'index' has none). The tool description adds no parameter details, leaving the agent to guess the expected structure for 'body' and the role of 'index'. This is insufficient, especially given the lack of enum or output schema.
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 that the tool returns the number of documents matching a query, which aligns with the tool name 'CountTool'. It distinguishes itself from sibling tools like SearchIndexTool by focusing on count rather than document retrieval, but could be more specific about the query format (e.g., JSON query).
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?
No guidance is provided on when to use this tool versus alternatives such as SearchIndexTool or ExplainTool. There is no mention of prerequisites, when not to use it, or how it compares to sibling tools, leaving the agent without decision-making support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyzes data distribution patterns and field value frequencies within OpenSearch indices. Supports both single dataset analysis for understanding data characteristics and comparative analysis between two time periods to identify distribution changes. Automatically detects useful fields, calculates value distributions, groups numeric data, and computes divergence metrics. Useful for anomaly detection, data quality assessment, and trend analysis. We can use this tool to analyze the distribution of failures over time
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Target OpenSearch index name | |
| selectionTimeRangeStart | Yes | Start time for analysis period | |
| selectionTimeRangeEnd | Yes | End time for analysis period | |
| timeField | Yes | Date/time field for filtering(requied) | |
| baselineTimeRangeStart | No | Start time for baseline period (optional) | |
| baselineTimeRangeEnd | No | End time for baseline period (optional) | |
| size | No | Maximum number of documents to analyze |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must handle transparency. It notes automatic field detection, value distribution calculation, and numeric grouping, but does not specify side effects or read-only nature. Some behavioral context is provided.
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 relatively concise with a few sentences covering key points. It could be slightly more structured, but it is clear and 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?
No output schema exists, and the description does not explain return values or output format. It covers the tool's purpose and capabilities but leaves gaps in what the agent can expect as result.
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 baseline is 3. The description adds context about single vs. comparative analysis (mapping to selectionTimeRange and baselineTimeRange) but does not explain parameters beyond schema.
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 analyzes data distribution patterns and field value frequencies in OpenSearch indices, distinguishing it from siblings like CountTool or SearchIndexTool. It specifies both single and comparative analysis modes.
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 mentions use cases (anomaly detection, data quality, trend analysis) and gives a concrete example (failures over time). However, it lacks explicit guidance on when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns information about why a specific document matches (or doesn't match) a query.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | ||
| id | Yes | ||
| body | Yes | Request body containing the query to explain. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral traits but only states it returns information. It does not disclose whether the tool is read-only, requires existing documents, or any side effects, which is insufficient for a reliable selection.
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, concise sentence that front-loads the core purpose without unnecessary words or structure.
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?
Despite having 3 required parameters and no output schema, the description is too brief. It lacks details on output format, constraints, or how the tool complements siblings, leaving the agent underinformed.
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 only 33% (body described). The tool description adds no extra meaning for index and id parameters beyond the schema, missing an opportunity to clarify their roles in the explanation context.
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 returns information about why a document matches or doesn't match a query, using specific verb and resource. It distinguishes from sibling tools like SearchIndexTool which returns documents rather than explanations.
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?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, context, or exclusions, leaving the agent without information on appropriate usage conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A flexible tool for calling any OpenSearch API endpoint. Supports all HTTP methods with custom paths, query parameters, request bodies, and headers. Use this when you need to access OpenSearch APIs that don't have dedicated tools, or when you need more control over the request. Leverages your knowledge of OpenSearch API documentation to construct appropriate requests.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The API endpoint path (e.g., "/_search", "/_cat/indices", "/my_index/_doc/1"). Should start with "/". | |
| method | No | HTTP method to use (GET, POST, PUT, DELETE, HEAD, PATCH) | GET |
| query_params | No | Query parameters to include in the request URL as key-value pairs | |
| body | No | Request body for GET/POST/PUT requests. Can be a JSON object, string, or None | |
| headers | No | Additional HTTP headers to include in the request |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It states the tool is flexible and supports all HTTP methods, but doesn't disclose potential side effects, idempotency, or rate limits. The mention of leveraging knowledge of API documentation implies the agent must understand those details, which is acceptable for a generic tool.
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 concise with four sentences, front-loaded with purpose, and uses clear language. Every sentence adds value without 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?
Given the tool is generic with no output schema, the description adequately covers its purpose, usage, and parameter expectations. It mentions leveraging the agent's API knowledge, which compensates for the lack of detailed behavior. The schema coverage is high, making the description complete enough.
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 baseline is 3. The description provides a high-level overview of supported components (path, method, query params, body, headers) but doesn't add significant meaning beyond the schema descriptions. The examples in the schema complement this.
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 it is for calling any OpenSearch API endpoint, lists supported HTTP methods, and distinguishes from siblings by specifying when to use it (when dedicated tools don't exist, or for more control).
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?
Explicitly tells the agent when to use this tool: 'Use this when you need to access OpenSearch APIs that don't have dedicated tools, or when you need more control.' This provides clear guidance and implicitly suggests using other tools when available.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gets information about shards in OpenSearch
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | The name of the index to get shard information for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It does not state whether the operation is read-only, what error behavior occurs for missing indices, or any side effects. The minimal description provides almost no transparency.
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 sentence that is front-loaded and to the point. It is efficient, but could be expanded with useful details without becoming verbose.
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 no output schema and no annotations, the description is too sparse. It does not explain the nature of the shard information (e.g., allocation, health, routing), what the return data looks like, or any prerequisites. This is insufficient for an agent to use the tool confidently.
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%, and the parameter 'index' already has a descriptive label ('The name of the index to get shard information for'). The description adds no additional meaning beyond the schema, so baseline score 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 clearly states the verb ('gets') and resource ('information about shards in OpenSearch'). It is specific enough to distinguish from sibling tools like ClusterHealthTool or SearchIndexTool, though it could be more precise about what shard information is returned.
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?
No guidance on when to use this tool versus alternatives. The description does not mention when it is appropriate or when to avoid it, leaving the agent to infer solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves index mapping and setting information for an index in OpenSearch
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | The name of the index to get mapping information for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behaviors. Only states retrieval, but does not mention read-only nature, needed permissions, or if it has side effects. Minimal transparency.
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?
Single sentence, no unnecessary words. Front-loaded with action verb 'Retrieves'. Highly concise.
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?
Adequate for a simple retrieval tool with one parameter and no output schema. But could mention that output includes both mapping and settings, and lacks any usage tips or examples.
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 covers 100% of the single parameter with a clear description. Tool description adds no extra detail beyond the schema, so baseline score 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?
Clearly states the tool retrieves index mapping and setting information for an OpenSearch index, specifying verb, resource, and context. Distinct from siblings like ListIndexTool or SearchIndexTool.
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?
No guidance on when to use this tool versus alternatives, such as ListIndexTool for listing indices or SearchIndexTool for searching. Lacks context on prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists indices in the OpenSearch cluster. If an index name or pattern is specified, return only information about the provided index or index pattern. The include_detail flag controls output: if False, returns only index name(s); if True (default), returns full metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| index | No | The name of the index or index pattern to get information for. | |
| include_detail | No | Whether to include detailed information. If False, returns only index name(s). If True, returns full metadata. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility. It discloses the effect of each parameter on the output, and implies a read-only, non-destructive operation. No side effects are mentioned, but none are expected for a listing tool.
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 efficiently cover the tool's purpose, optional filtering, and parameter behavior. No wasted words, front-loaded with main action.
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 tool is simple with two optional parameters and no output schema, the description is sufficient. It explains both parameters and the output format. Could elaborate on 'full metadata' but not necessary for tool selection.
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%, baseline is 3. The description adds value by explaining how the 'index' parameter filters results and how 'include_detail' controls output verbosity, going beyond the schema descriptions.
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?
Clearly states the tool lists indices in the OpenSearch cluster, mentions optional filtering by name/pattern, and explains the include_detail flag. Distinguishes itself from sibling tools like SearchIndexTool by its specific resource (indices) and listing action.
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?
Provides context on when to use parameterized calls (filtering by index/pattern) and default behavior. Does not explicitly mention alternatives or when not to use, but the purpose is clear enough to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Intelligent log pattern analysis tool for troubleshooting and anomaly detection in application logs. Use this tool when you need to: analyze error patterns in logs, identify unusual log sequences, compare log patterns between time periods, find root causes of system issues, detect anomalous behavior in application traces, or investigate performance problems. The tool automatically extracts meaningful patterns from raw log messages, groups similar patterns, identifies outliers, and provides insights for debugging. Essential for log-based troubleshooting, incident analysis, and proactive monitoring of system health.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Target OpenSearch index name containing log data | |
| logFieldName | Yes | Field containing raw log messages to analyze | |
| selectionTimeRangeStart | Yes | Start time for analysis target period | |
| selectionTimeRangeEnd | Yes | End time for analysis target period | |
| timeField | Yes | Date/time field for time-based filtering(requied) | |
| traceFieldName | No | Field for trace/correlation ID (optional) | |
| baseTimeRangeStart | No | Start time for baseline comparison period (optional) | |
| baseTimeRangeEnd | No | End time for baseline comparison period (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must convey behavioral traits. It states the tool 'automatically extracts meaningful patterns, groups similar patterns, identifies outliers, and provides insights for debugging.' This covers core behavior but lacks detail on potential side effects, data volume limits, or authentication requirements. The description is adequate but not exhaustive.
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 moderately concise, with each sentence adding value. It front-loads the purpose and lists use cases efficiently. A minor reduction could be made by removing the marketing adjective 'Intelligent,' but overall it is well-structured and not overly verbose.
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 tool's complexity (8 parameters, 5 required, no output schema), the description is incomplete. It does not explain the output format or results, nor does it describe the optional parameters like baseTimeRangeStart/End for baseline comparison. The description would benefit from specifying what the tool returns and how to interpret results.
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 each parameter already has a description. The tool description adds no additional meaning beyond the schema; it reiterates the purpose but does not provide format details or usage hints beyond what the schema offers. Therefore, 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 identifies the tool as an intelligent log pattern analysis tool for troubleshooting and anomaly detection. It lists specific use cases like analyzing error patterns, identifying unusual log sequences, and comparing patterns between time periods. This distinguishes it from sibling tools like SearchIndexTool or GenericOpenSearchApiTool, which are more general-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 explicitly states when to use the tool: for analyzing error patterns, identifying anomalies, comparing patterns, finding root causes, etc. It also calls it 'essential for log-based troubleshooting, incident analysis, and proactive monitoring.' However, it does not provide explicit guidance on when not to use it or mention alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Allows to execute several search operations in one request.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | Request body as NDJSON format: alternating lines of header and query objects ending with \n. Alternatively, pass a JSON array [header, query, header, query, ...] and the tool will convert it to NDJSON for you. | |
| index | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Minimal behavioral disclosure beyond what the schema provides; lacks details on request limits, error handling, or output format.
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?
Single sentence is concise but could benefit from more detail without becoming verbose.
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 complexity of batch search and lack of output schema/annotations, the description is incomplete; missing response format, limitations, and prerequisites.
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?
Body parameter description adds value by explaining NDJSON format and JSON array alternative, but index parameter lacks any description.
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?
Description clearly states it executes several search operations in one request, distinguishing it from single-search tools like SearchIndexTool.
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?
No guidance on when to use this tool vs. alternatives like SearchIndexTool or other batch operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches an index using a query written in query domain-specific language (DSL) in OpenSearch. PREREQUISITE: You need to know the mappings of the index before constructing queries.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | The name of the index to search in | |
| query_dsl | Yes | The search query in OpenSearch query DSL format. For keyword-type fields (mapping shows "type": "keyword"), use field name DIRECTLY - do NOT add .keyword suffix. For text-type fields with .keyword subfields, use the .keyword suffix for exact matches. For date/time range queries, MUST include "format" parameter (commonly "format": "strict_date_optional_time||epoch_millis"), e.g. {"range": {"timestamp": {"gte": "2025-12-29T17:15:12Z", "lte": "2025-12-30T08:15:12Z", "format": "strict_date_optional_time||epoch_millis"}}}; if using non-ISO formats, adjust "format" accordingly. | |
| format | No | Output format: "json" or "csv" | json |
| size | No | Number of search results to return. The maximum allowed value is 100, unless overridden by configuration. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool searches using DSL but does not disclose any behavioral traits such as read-only nature, authentication needs, rate limits, error handling, or side effects. This is minimal transparency.
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, concise and front-loaded with the action. No unnecessary words. It efficiently communicates the core purpose and a prerequisite.
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 no output schema and no annotations, the description is incomplete. It does not explain the output format (despite the 'format' parameter), error behavior, or how results are returned. The prerequisite is useful but the overall context for an agent to correctly invoke the tool is lacking.
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 has 100% description coverage, so the baseline is 3. The tool description does not add meaning beyond the schema; it only reiterates the prerequisite. The query_dsl parameter has detailed hints in the schema but not in the description.
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 verb 'Searches' and the resource 'an index using a query written in query DSL in OpenSearch.' It differentiates from siblings like CountTool or ExplainTool by focusing on search with DSL, but does not explicitly distinguish from MsearchTool (multi-search). The prerequisite adds context.
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 prerequisite ('You need to know the mappings of the index before constructing queries') which implies proper usage, but it does not specify when to use this tool versus alternatives (e.g., use IndexMappingTool to get mappings first). No explicit when-not or alternative recommendations.
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.9.0ClusterHealthToolCountToolDataDistributionToolExplainToolGenericOpenSearchApiToolGetShardsToolIndexMappingToolListIndexToolLogPatternAnalysisToolMsearchToolSearchIndexToolScored across 11 tools
Most tools have distinct purposes, but CountTool and SearchIndexTool both involve queries and could be confused without careful reading. The GenericOpenSearchApiTool is a catch-all that overlaps with all other tools, but it's intended for unsupported APIs.
All tool names use CamelCase and the 'Tool' suffix, but the verb/noun order is inconsistent: some start with verbs (GetShards, ListIndex, SearchIndex), others with nouns (ClusterHealth, DataDistribution), and some are generic (CountTool, ExplainTool). This mix reduces predictability.
With 11 tools, the server covers the main OpenSearch operations (cluster health, indexing, searching, analysis) without being overwhelming. The count is well-scoped for a search engine MCP server.
Core operations like listing indices, searching, counting, and explaining are covered. Missing dedicated tools for index creation/deletion and bulk operations, but the GenericOpenSearchApiTool fills these gaps, making the surface fairly complete.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
The OpenRouter MCP server plugs OpenRouter into the AI tools you already use. Once connected, your assistant can pull live OpenRouter data (models, prices, your credits, rankings, and docs) and send quick test messages, all without leaving your editor.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
