Skip to main content
Glama
opensearch-project

opensearch-mcp-server-py

Official
by opensearch-project
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

OpenSearch logo

OpenSearch MCP Server

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

  • Dynamic per-call connection parameters for targeting different clusters without server reconfiguration

  • 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: OpenSearch MCP Server

Installing opensearch-mcp-server-py

Opensearch-mcp-server-py can be installed from PyPI via pip:

pip install opensearch-mcp-server-py

Zero-Config Setup

The server can be started with no environment variables at all. Agents provide connection details dynamically on each tool call:

{
  "mcpServers": {
    "opensearch": {
      "command": "uvx",
      "args": ["opensearch-mcp-server-py"]
    }
  }
}

With this setup, agents pass opensearch_url and authentication parameters directly when calling any tool. This is useful when agents discover endpoints from a knowledge base, runbook, or SOP, or when a single agent needs to work with multiple clusters in one session. See Dynamic Connection Parameters for details.

Available Tools

By default, only core tools are enabled to provide essential OpenSearch functionality:

Core Tools (Enabled by Default)

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.

Additional Tools (Disabled by Default)

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.

Agentic Memory Tools (Disabled by Default)

The following tools expose the OpenSearch Agentic Memory API — a server-side memory system built into OpenSearch itself. The OpenSearch cluster manages memory containers, sessions, and inference (LLM-based extraction of facts from conversations). These tools require OpenSearch 3.3.0 or later.

When to use: You want OpenSearch to own the full memory lifecycle — including LLM-based inference to extract facts from raw conversations, structured memory types (sessions, working, long-term, history), and server-managed namespacing. Best for production agentic pipelines where memory management should be centralized and not depend on the MCP client.

Setup: You must create a memory container in OpenSearch before using these tools (one-time admin operation requiring LLM connector and embedding model configuration). See Agentic Memory Tools in the Agent Memory Guide.

Enable with OPENSEARCH_ENABLED_CATEGORIES=agentic_memory. When memory_container_id is configured via the agentic_memory config section or OPENSEARCH_MEMORY_CONTAINER_ID environment variable, it is automatically pre-filled in all tool calls.

Observability Tools (Disabled by Default)

Observability tools are grouped under the observability category and can be enabled using OPENSEARCH_ENABLED_CATEGORIES=observability or by adding enabled_categories: [observability] to the config file. Alternatively, enable the analytics category to get both observability and skills tools at once.

  • PPLQueryTool: Executes a PPL (Piped Processing Language) query against OpenSearch. PPL provides a pipe-based syntax for querying data (source=<index> | <command> | <command>), supporting filtering, aggregation, sorting, deduplication, and field selection. Supports jdbc, csv, and raw output formats.

Search Relevance Workbench Tools (Disabled by Default)

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.

Skills Tools (Disabled by Default)

Skills tools are grouped under the skills category and can be enabled at once using OPENSEARCH_ENABLED_CATEGORIES=skills or by adding enabled_categories: [skills] to the config file. Alternatively, enable the analytics category to get both skills and observability tools at once. See the Tool Filter section in the User Guide for additional information about how to filter tools.

  • 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.

  • MetricChangeAnalysisTool: Compares percentile distributions (P50, P90) of all numeric fields between a baseline and a selection time range, then returns the top fields ranked by change score. Useful for identifying which numeric metrics shifted most during an anomaly window.

Memory Tools (Opt-in)

Memory tools give the MCP agent itself persistent, cross-session memory backed by OpenSearch. The agent decides what to save as plain-text statements; OpenSearch stores and semantically indexes them. Enable with MEMORY_TOOLS_ENABLED=true. See the Agent Memory Guide for full setup instructions.

When to use: You want a lightweight, agent-driven memory layer that works with any MCP-compatible IDE (Kiro, Claude Code, Cursor). The agent controls what gets remembered — no LLM connectors or embedding models to configure on the OpenSearch side. Requires Amazon OpenSearch Service (managed domain 2.19+ or Serverless) for automatic semantic enrichment. See the Agent Memory Guide for full setup instructions.

  • SaveMemoryTool: Saves facts, decisions, and preferences to persistent storage with automatic semantic enrichment.

  • SearchMemoryTool: Searches memories using natural language with recency-aware ranking.

  • DeleteMemoryTool: Removes outdated or incorrect memories by document ID.

Tool Parameters

All tools accept the following optional connection parameters that override the server's environment variable configuration on a per-call basis. When all are omitted, the server uses its configured environment variables or cluster config as usual. When you supply opensearch_url, the credentials must come from that same call: the server will not use its own credentials against a URL a caller chose, unless the operator sets OPENSEARCH_ALLOW_AMBIENT_AWS_FALLBACK=true to share its AWS credentials.

Parameter

Type

Description

opensearch_url

string

OpenSearch endpoint URL. Overrides OPENSEARCH_URL.

opensearch_username

string

Username for basic auth. Overrides OPENSEARCH_USERNAME.

opensearch_password

string

Password for basic auth. Overrides OPENSEARCH_PASSWORD.

opensearch_no_auth

boolean

Connect without authentication. Overrides OPENSEARCH_NO_AUTH.

aws_region

string

AWS region. Overrides AWS_REGION.

aws_iam_arn

string

IAM role ARN. Overrides AWS_IAM_ARN.

aws_profile

string

AWS profile name. Overrides AWS_PROFILE.

aws_opensearch_serverless

boolean

Use OpenSearch Serverless. Overrides AWS_OPENSEARCH_SERVERLESS.

opensearch_ssl_verify

boolean

Set true to require SSL certificate verification. A false value is ignored, since only OPENSEARCH_SSL_VERIFY may disable it.

opensearch_timeout

integer

Connection timeout in seconds. Overrides OPENSEARCH_TIMEOUT.

This allows agents to dynamically target different clusters per tool call without reconfiguring the server (single mode only). Credentials must come from the same call as the URL, unless OPENSEARCH_ALLOW_AMBIENT_AWS_FALLBACK=true lets the server sign caller-supplied URLs with its own AWS credentials. OPENSEARCH_SSRF_GUARD=true restricts caller-supplied URLs to public HTTPS addresses. See Dynamic Connection Parameters in the User Guide for details and examples.

In addition to the common connection parameters above, each tool accepts its own specific parameters:

Note: The opensearch_url parameter listed under individual tools below is part of the common connection parameters described above. All common connection parameters (opensearch_username, opensearch_password, aws_region, etc.) are available on every tool but are not repeated in each tool's parameter list for brevity.

  • 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.

  • CreateAgenticMemorySessionTool

    • memory_container_id (auto-populated): The ID of the memory container where the session will be created. Automatically set when configured via agentic_memory config or OPENSEARCH_MEMORY_CONTAINER_ID env var. (Path Parameter)

    • session_id (optional): A custom session ID. If not provided, a random ID is generated. (Body Parameter)

    • summary (optional): A session summary or description. (Body Parameter)

    • metadata (optional): Additional metadata for the session provided as key-value pairs. (Body Parameter)

    • namespace (optional): Namespace information for organizing the session. (Body Parameter)

  • AddAgenticMemoriesTool

    • memory_container_id (auto-populated): The ID of the memory container to add the memory to. Automatically set when configured. (Path Parameter)

    • messages (conditional): A list of messages. Required when payload_type is conversational. (Body Parameter)

    • structured_data (conditional): Structured data content. Required when payload_type is data. (Body Parameter)

    • binary_data (optional): Binary data content encoded as a Base64 string for binary payloads. (Body Parameter)

    • payload_type (required): The type of payload. Valid values are conversational or data. See Payload types. (Body Parameter)

    • namespace (optional): The namespace context for organizing memories (for example, user_id, session_id, or agent_id). If session_id is not specified in the namespace field and disable_session: false (default is true), a new session with a new session ID is created. (Body Parameter)

    • metadata (optional): Additional metadata for the memory (for example, status, branch, or custom fields). (Body Parameter)

    • tags (optional): Tags for categorizing memories. (Body Parameter)

    • infer (optional): Whether to use an LLM to extract key information (default: false). When true, the LLM extracts key information from the original text and stores it as a memory. See Inference mode. (Body Parameter)

  • GetAgenticMemoryTool

    • memory_container_id (auto-populated): The ID of the memory container from which to retrieve the memory. Automatically set when configured. (Path Parameter)

    • type (required): The memory type. Valid values are sessions, working, long-term, and history. (Path Parameter)

    • id (required): The ID of the memory to retrieve. (Path Parameter)

  • SearchAgenticMemoryTool

    • memory_container_id (auto-populated): The ID of the memory container. Automatically set when configured. (Path Parameter)

    • type (required): The memory type. Valid values are sessions, working, long-term, and history. (Path Parameter)

    • query (required): The search query using OpenSearch query DSL. (Body Parameter)

    • sort (optional): Sort specification for the search results. (Body Parameter)

  • UpdateAgenticMemoryTool

    • memory_container_id (auto-populated): The ID of the memory container. Automatically set when configured. (Path Parameter)

    • type (required): The memory type (sessions, working, or long-term).(Path Parameter)

    • id (required): The ID of the memory to update.(Path Parameter)

    • Session memory request fields:

      • summary (optional): The summary of the session. (Body Parameter)

      • metadata (optional): Additional metadata for the memory (for example, status, branch, or custom fields). (Body Parameter)

      • agents (optional): Additional information about the agents. (Body Parameter)

      • additional_info (optional): Additional metadata to associate with the session. (Body Parameter)

    • Working memory request fields

      • messages (optional): Updated conversation messages (for conversation type). (Body Parameter)

      • structured_data (optional): Updated structured data content (for data memory payloads). (Body Parameter)

      • binary_data (optional): Updated binary data content (for data memory payloads). (Body Parameter)

      • tags (optional): Updated tags for categorization. (Body Parameter)

      • metadata (optional): Additional metadata for the memory (for example, status, branch, or custom fields). (Body Parameter)

    • Long-term memory request fields

      • memory (optional): The updated memory content. (Body Parameter)

      • tags (optional): Updated tags for categorization. (Body Parameter)

  • DeleteAgenticMemoryByIDTool

    • memory_container_id (auto-populated): The ID of the memory container from which to delete the memory. Automatically set when configured. (Path Parameter)

    • type (required): The type of memory to delete. Valid values are sessions, working, long-term, and history. (Path Parameter)

    • id (required): The ID of the specific memory to delete. (Path Parameter)

  • DeleteAgenticMemoryByQueryTool

    • memory_container_id (auto-populated): The ID of the memory container from which to delete the memory. Automatically set when configured. (Path Parameter)

    • type (required): The type of memory to delete. Valid values are sessions, working, long-term, and history. (Path Parameter)

    • query (required): The OpenSearch DSL query to match memories for deletion. (Body Parameter)

  • 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.

  • MetricChangeAnalysisTool

    • index (required): Target OpenSearch index name.

    • selectionTimeRangeStart (required): Start of the selection (anomaly) period.

    • selectionTimeRangeEnd (required): End of the selection (anomaly) period.

    • baselineTimeRangeStart (required): Start of the baseline period.

    • baselineTimeRangeEnd (required): End of the baseline period (should be at or before selectionTimeRangeStart).

    • timeField (required): Date/time field for filtering.

    • topN (optional): Number of top fields to return, ranked by change score. Default is 10.

    • size (optional): Maximum number of documents to analyze. Default is 1000.

More tools coming soon. Click here

User Guide

For detailed usage instructions, configuration options, and examples, please see the User Guide.

Agent Memory

The OpenSearch MCP server includes two distinct memory systems. Both use OpenSearch as the storage backend but differ in who controls the memory lifecycle and what infrastructure they require.

Choosing the right approach

Memory Tools (MEMORY_TOOLS_ENABLED)

Agentic Memory Tools (agentic_memory category)

Who stores memories

The MCP agent decides what to save as plain-text statements

OpenSearch processes raw conversations and extracts facts via LLM inference

Setup complexity

Low — index is auto-created on first use

High — requires creating a memory container with LLM connector and embedding model

OpenSearch version

Amazon OpenSearch Service 2.19+ or Serverless

OpenSearch 3.3.0+

Semantic search

Yes, via AWS automatic semantic enrichment

Yes, via configured embedding model

Memory structure

Flat — each memory is a plain-text statement

Structured — sessions, working, long-term, and history types

LLM inference

No — agent writes exactly what it wants to remember

Optional (infer: true) — OpenSearch uses an LLM to extract facts from conversations

Best for

IDE agents (Kiro, Claude Code, Cursor) that need quick setup and cross-session continuity

Production agentic pipelines where memory management should be centralized and server-owned

Use Memory Tools when you want a lightweight, agent-driven memory layer that works out of the box with any MCP-compatible IDE. The agent controls what gets remembered. See the Agent Memory Guide for setup.

Use Agentic Memory Tools when you want OpenSearch to own the full memory lifecycle — including LLM-based extraction of facts from raw conversations, structured memory types, and server-managed namespacing. See the Agent Memory Guide for setup.

Contributing

Interested in contributing? Check out our:

Code of Conduct

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.

License

This project is licensed under the Apache v2.0 License.

Copyright

Copyright 2020-2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.

Available Tools

9 tools
ClusterHealthToolC

Returns basic information about the health of the cluster.

ParametersJSON Schema
NameRequiredDescriptionDefault
indexNo
aws_regionNoAWS region for IAM/Serverless authentication.
aws_iam_arnNoIAM role ARN for role-based authentication.
aws_profileNoAWS profile name for authentication.
opensearch_urlYesOpenSearch endpoint URL.
opensearch_no_authNoIf true, connect without authentication.
opensearch_timeoutNoConnection timeout in seconds.
opensearch_passwordNoPassword for basic authentication.
opensearch_usernameNoUsername for basic authentication.
opensearch_ssl_verifyNoSet true to require SSL certificate verification. A false value is ignored, since only the operator may disable verification.
aws_opensearch_serverlessNoIf true, use OpenSearch Serverless service.

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a read-only retrieval but does not explicitly state that it performs no mutation, whether authentication is required, what health dimensions are checked, or how failures or timeouts behave. A health-check tool should disclose at least that it is safe and read-only.

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

Conciseness5/5

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

The description is a single clear sentence with no filler or redundant information. It is appropriately sized and front-loaded with the core action and resource.

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

Completeness2/5

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

For a tool with 11 parameters, no annotations, and no output schema, this one-sentence description is insufficient. The agent is left without guidance on how authentication parameters interact, what the response contains, or what 'health' means in this context. The schema covers parameter names but not the tool's overall behavior or expected return shape.

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

Parameters3/5

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

Schema description coverage is 91%, so the input schema already documents most parameters, including auth-related fields and opensearch_url. The description itself adds no parameter-level meaning, 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.

Purpose4/5

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

The description states a specific verb ('Returns') and resource ('health of the cluster'), which clearly distinguishes it from sibling tools like ListIndexTool or SearchIndexTool. However, 'basic information' is somewhat vague about exactly what health data is returned.

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

Usage Guidelines2/5

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

The description gives no guidance on when to use this tool versus alternatives such as GenericOpenSearchApiTool or GetShardsTool. There is no mention of exclusions, prerequisites, or recommended contexts, leaving the agent to infer when cluster health is the appropriate call.

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

CountToolB

Returns number of documents matching a query.

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyNoRequest body
indexNo
aws_regionNoAWS region for IAM/Serverless authentication.
aws_iam_arnNoIAM role ARN for role-based authentication.
aws_profileNoAWS profile name for authentication.
opensearch_urlYesOpenSearch endpoint URL.
opensearch_no_authNoIf true, connect without authentication.
opensearch_timeoutNoConnection timeout in seconds.
opensearch_passwordNoPassword for basic authentication.
opensearch_usernameNoUsername for basic authentication.
opensearch_ssl_verifyNoSet true to require SSL certificate verification. A false value is ignored, since only the operator may disable verification.
aws_opensearch_serverlessNoIf true, use OpenSearch Serverless service.

TDQS

B3.2/5.0
Behavior2/5

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

With no annotations, the description carries the full behavioral burden, but it only states the return value. It does not disclose that this is read-only, how authentication is resolved across the many AWS/OpenSearch credential parameters, or what happens when no index or query 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.

Conciseness5/5

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

A single sentence that is front-loaded with the operation and contains no fluff. It does not repeat schema details and earns its place by stating the tool's core behavior plainly.

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

Completeness2/5

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

Although the schema richly documents parameters, the tool has 12 parameters, no annotations, and no output schema. The one-line description does not address how to form the query body, whether authentication is required, or what the count response looks like, leaving too much for the agent to infer.

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

Parameters3/5

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

Schema description coverage is high (92%), so the schema already documents the connection parameters and request body; the baseline of 3 applies. The phrase 'matching a query' adds slight meaning by implying the body should contain a query, but it does not explain query syntax or index/body interactions.

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

Purpose4/5

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

The description states a concrete operation ('Returns number') and a resource ('documents matching a query'), which distinguishes it from siblings like SearchIndexTool that return documents rather than counts. It does not explicitly name an alternative or endpoint, but the core purpose is unambiguous.

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

Usage Guidelines3/5

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

Usage is implied rather than explicit: the description suggests this tool is appropriate when a count of matching documents is needed. However, it does not provide when-not-to-use guidance or mention alternatives like SearchIndexTool or MsearchTool.

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

ExplainToolB

Returns information about why a specific document matches (or doesn't match) a query.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes
bodyYesRequest body containing the query to explain.
indexYes
aws_regionNoAWS region for IAM/Serverless authentication.
aws_iam_arnNoIAM role ARN for role-based authentication.
aws_profileNoAWS profile name for authentication.
opensearch_urlYesOpenSearch endpoint URL.
opensearch_no_authNoIf true, connect without authentication.
opensearch_timeoutNoConnection timeout in seconds.
opensearch_passwordNoPassword for basic authentication.
opensearch_usernameNoUsername for basic authentication.
opensearch_ssl_verifyNoSet true to require SSL certificate verification. A false value is ignored, since only the operator may disable verification.
aws_opensearch_serverlessNoIf true, use OpenSearch Serverless service.

TDQS

B3.1/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It is a single sentence that only restates the purpose and reveals nothing about return format, authentication requirements, read-only status, or side effects. For a tool with 13 parameters and zero annotation coverage, this is a significant transparency gap.

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

Conciseness4/5

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

The description is a single clean sentence with no filler or redundancy. However, it borders on under-specification rather than deliberate conciseness, since it is the entirety of the behavioral guidance for a complex 13-parameter tool. It earns a 4 for efficiency, not for completeness.

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

Completeness2/5

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

With 13 parameters, no annotations, and no output schema, the description must do substantial work to be complete. It explains neither the return value format (which the absence of an output schema makes necessary) nor usage context nor operational behavior. The schema covers parameters well, but the overall definition leaves an agent under-informed about what to expect from the call.

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

Parameters3/5

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

Schema description coverage is 85%, which is high (>80%), so the baseline of 3 applies. The schema already documents parameters like 'Request body containing the query to explain' and the authentication fields. The description adds no parameter-level detail beyond the schema, which is acceptable given the high coverage.

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

Purpose4/5

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

The description states a specific verb and resource: 'Returns information about why a specific document matches (or doesn't match) a query.' This clearly conveys the explain operation and inherently distinguishes it from siblings like SearchIndexTool (which returns matches) and CountTool (which counts matches). However, it doesn't explicitly name any sibling, so it stops short of a 5.

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

Usage Guidelines3/5

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

Usage is implied: the agent can infer this tool is for diagnosing match rationale. But there is no explicit statement of when to use it versus alternatives like SearchIndexTool or MsearchTool, no exclusions, and no mention of prerequisites (e.g., requiring an existing index/document). Guidance is left to inference.

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

GenericOpenSearchApiToolA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyNoRequest body for GET/POST/PUT requests. Can be a JSON object, string, or None
pathYesThe API endpoint path (e.g., "/_search", "/_cat/indices", "/my_index/_doc/1"). Should start with "/".
methodNoHTTP method to use (GET, POST, PUT, DELETE, HEAD, PATCH)GET
headersNoAdditional HTTP headers to include in the request
aws_regionNoAWS region for IAM/Serverless authentication.
aws_iam_arnNoIAM role ARN for role-based authentication.
aws_profileNoAWS profile name for authentication.
query_paramsNoQuery parameters to include in the request URL as key-value pairs
opensearch_urlYesOpenSearch endpoint URL.
opensearch_no_authNoIf true, connect without authentication.
opensearch_timeoutNoConnection timeout in seconds.
opensearch_passwordNoPassword for basic authentication.
opensearch_usernameNoUsername for basic authentication.
opensearch_ssl_verifyNoSet true to require SSL certificate verification. A false value is ignored, since only the operator may disable verification.
aws_opensearch_serverlessNoIf true, use OpenSearch Serverless service.

TDQS

A3.9/5.0
Behavior2/5

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It does not mention potential side effects (e.g., destructive operations), error handling, return format, or any special behaviors. The phrase 'any OpenSearch API endpoint' implies it could perform mutations, but this is not surfaced explicitly. The description adds little beyond the basic capability.

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

Conciseness5/5

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

The description is two sentences, front-loads the core purpose, and provides usage guidance without any fluff. Every sentence earns its place, and the structure is clear and efficient.

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

Completeness3/5

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

The tool is complex with 15 parameters and no output schema. The description does not state what the tool returns (e.g., raw API response), nor does it explain error behavior or how to interpret results. It relies on the agent's knowledge of OpenSearch API documentation, which is stated, but for a generic tool that can perform any operation, more clarity on expected output would be helpful. The description is adequate but leaves gaps.

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

Parameters3/5

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

Schema description coverage is 100%, so each parameter already has a clear description. The tool description mentions 'custom paths, query parameters, request bodies, and headers', which maps to a few parameters but adds no new meaning. It does not explain relationships between parameters (e.g., authentication options) or provide usage context beyond what the schema offers. Baseline 3 is appropriate.

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

Purpose5/5

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

The description clearly states a specific action: 'calling any OpenSearch API endpoint', and distinguishes itself from siblings by specifying it is for endpoints that 'don't have dedicated tools'. The verb and resource are explicit, and it tells the agent when to choose this tool over dedicated ones.

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

Usage Guidelines5/5

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

The description explicitly states when to use this tool: 'when you need to access OpenSearch APIs that don't have dedicated tools, or when you need more control over the request.' It implies that dedicated tools should be used for their specific endpoints, giving clear guidance on selection.

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

GetShardsToolB

Gets information about shards in OpenSearch

ParametersJSON Schema
NameRequiredDescriptionDefault
indexYesThe name of the index to get shard information for
aws_regionNoAWS region for IAM/Serverless authentication.
aws_iam_arnNoIAM role ARN for role-based authentication.
aws_profileNoAWS profile name for authentication.
opensearch_urlYesOpenSearch endpoint URL.
opensearch_no_authNoIf true, connect without authentication.
opensearch_timeoutNoConnection timeout in seconds.
opensearch_passwordNoPassword for basic authentication.
opensearch_usernameNoUsername for basic authentication.
opensearch_ssl_verifyNoSet true to require SSL certificate verification. A false value is ignored, since only the operator may disable verification.
aws_opensearch_serverlessNoIf true, use OpenSearch Serverless service.

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations, the description must carry the burden of behavioral disclosure, but it only says 'Gets information,' which implies read-only without detailing side effects, return shape, or failure behavior. It does not state what shard information is included or how authentication-related behaviors affect the call.

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

Conciseness4/5

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

The description is a single, front-loaded sentence with no redundant phrasing. It is appropriately terse, though it may err slightly on the side of under-specification rather than over-explaining.

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

Completeness2/5

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

This tool has 11 parameters and no output schema, and the description provides minimal context about what 'information about shards' means or what the caller should expect in return. For an agent to use it correctly, more detail on the shard data returned or typical use cases would be needed.

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

Parameters3/5

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

Schema description coverage is 100%, so the input schema fully documents each parameter, including index, endpoint, and authentication options. The description itself adds no extra parameter semantics beyond the context that the tool targets shards, maintaining the baseline score.

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

Purpose4/5

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

The description uses a clear verb ('Gets') with a specific resource ('information about shards in OpenSearch'), which differentiates it from cluster-level or document-level sibling tools. It is slightly generic about what aspect of shards is returned, but it clearly identifies the tool's scope.

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

Usage Guidelines3/5

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

There is no explicit guidance about when to prefer this tool over siblings such as GenericOpenSearchApiTool or ClusterHealthTool. The use case is implied by the description: retrieve shard-level information for a named OpenSearch index. This is adequate but not instructive.

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

IndexMappingToolC

Retrieves index mapping and setting information for an index in OpenSearch

ParametersJSON Schema
NameRequiredDescriptionDefault
indexYesThe name of the index to get mapping information for
aws_regionNoAWS region for IAM/Serverless authentication.
aws_iam_arnNoIAM role ARN for role-based authentication.
aws_profileNoAWS profile name for authentication.
opensearch_urlYesOpenSearch endpoint URL.
opensearch_no_authNoIf true, connect without authentication.
opensearch_timeoutNoConnection timeout in seconds.
opensearch_passwordNoPassword for basic authentication.
opensearch_usernameNoUsername for basic authentication.
opensearch_ssl_verifyNoSet true to require SSL certificate verification. A false value is ignored, since only the operator may disable verification.
aws_opensearch_serverlessNoIf true, use OpenSearch Serverless service.

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of disclosing behavior. It only states the operation ('Retrieves') without mentioning that it is read-only, what happens if the index does not exist, whether settings are included in the response, or any authentication side effects. This is a significant gap for a tool with no annotation safety profile.

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

Conciseness4/5

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

The description is a single, front-loaded sentence with no wasted words. It effectively communicates the core operation in a compact form, though it may be overly terse given the tool's 11 parameters and lack of other context.

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

Completeness2/5

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

Given the tool's complexity (11 parameters, no output schema, no annotations), the description is inadequate. It does not clarify return values, error behavior, or how this tool relates to siblings. An agent would have to infer many important details solely from parameter names, leaving the description incomplete for safe and correct invocation.

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

Parameters3/5

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

The schema description coverage is 100%, so the baseline is 3. The description itself adds no parameter-level meaning beyond what the schema already provides, but since all parameters are documented individually in the schema, the tool is still usable without additional parameter explanation.

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

Purpose4/5

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

The description uses a specific verb ('Retrieves') and a clear resource ('index mapping and setting information for an index in OpenSearch'), which effectively distinguishes it from data-retrieval tools like SearchIndexTool. It does not explicitly name siblings, but the purpose is unambiguous and specific enough.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives such as ListIndexTool, SearchIndexTool, or GetShardsTool. There are no exclusions, prerequisites, or contextual hints beyond the implied use case of inspecting index metadata, so an agent receives no routing assistance.

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

ListIndexToolA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
indexNoThe name of the index or index pattern to get information for.
aws_regionNoAWS region for IAM/Serverless authentication.
aws_iam_arnNoIAM role ARN for role-based authentication.
aws_profileNoAWS profile name for authentication.
include_detailNoWhether to include detailed information. If False, returns only index name(s). If True, returns full metadata.
opensearch_urlYesOpenSearch endpoint URL.
opensearch_no_authNoIf true, connect without authentication.
opensearch_timeoutNoConnection timeout in seconds.
opensearch_passwordNoPassword for basic authentication.
opensearch_usernameNoUsername for basic authentication.
opensearch_ssl_verifyNoSet true to require SSL certificate verification. A false value is ignored, since only the operator may disable verification.
aws_opensearch_serverlessNoIf true, use OpenSearch Serverless service.

TDQS

A3.5/5.0
Behavior3/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does explain the output difference between include_detail True/False and filtering behavior, which is helpful. However, it omits any mention of read-only nature, potential errors, or behavior when no indices exist. For a simple list operation, this is adequate but not thorough.

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

Conciseness5/5

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

Two sentences, front-loaded with the primary action and key behavior. No redundant wording. The description efficiently conveys the tool's function and output control without fluff.

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

Completeness3/5

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

For a tool with 12 parameters (mostly authentication-related), the description focuses on the functional behavior and does not attempt to document each auth parameter, which is acceptable since the schema covers them. However, it lacks details on return format specifics (e.g., what 'full metadata' includes) and does not address potential edge cases. Given no output schema, slightly more detail on the output structure would improve completeness.

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

Parameters3/5

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

Schema description coverage is 100%, so all parameters are already documented. The description adds minimal extra meaning beyond the schema—it reiterates the include_detail behavior and adds the context of index/pattern filtering, but this is mostly redundant with the schema. Baseline 3 is appropriate since the schema carries the parameter semantics.

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

Purpose5/5

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

Description clearly states the verb 'Lists' and the resource 'indices in the OpenSearch cluster', and explicitly explains filtering by index/pattern and the include_detail flag behavior. This distinguishes it from sibling tools like SearchIndexTool or GetShardsTool by its specific function of listing index metadata.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention any sibling tool or condition for selection. The purpose is implied but there is no explicit 'use this when...' or 'instead of...' guidance, leaving the agent to infer usage.

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

MsearchToolB

Allows to execute several search operations in one request.

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyYesRequest 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.
indexNo
aws_regionNoAWS region for IAM/Serverless authentication.
aws_iam_arnNoIAM role ARN for role-based authentication.
aws_profileNoAWS profile name for authentication.
opensearch_urlYesOpenSearch endpoint URL.
opensearch_no_authNoIf true, connect without authentication.
opensearch_timeoutNoConnection timeout in seconds.
opensearch_passwordNoPassword for basic authentication.
opensearch_usernameNoUsername for basic authentication.
opensearch_ssl_verifyNoSet true to require SSL certificate verification. A false value is ignored, since only the operator may disable verification.
aws_opensearch_serverlessNoIf true, use OpenSearch Serverless service.

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only restates the core batch-search capability and reveals nothing about response aggregation, failure modes, request size limits, authentication behavior, or side effects, so transparency is minimal.

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

Conciseness4/5

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

The description is a single clear sentence with no filler or redundancy, making it efficient and easy to parse. It is slightly terse but still communicates the essential purpose without wasted words.

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

Completeness2/5

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

The tool has 12 parameters, no annotations, and no output schema, yet the description provides only a high-level purpose. It omits details about how to structure a multi-search request, what the response looks like, error behavior, or how this compares to sibling search tools, leaving substantial gaps for an agent to call it correctly.

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

Parameters3/5

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

Schema description coverage is high at 92%, and the body parameter is well described with NDJSON format details and an alternative array input option. The tool description itself adds no extra parameter meaning, 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.

Purpose4/5

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

The description states a clear verb and resource: execute several search operations in one request. It conveys the multi-search nature of the tool, but it does not explicitly differentiate it from siblings like SearchIndexTool or GenericOpenSearchApiTool.

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

Usage Guidelines3/5

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

The phrase 'several search operations in one request' implies the tool is intended for batched or multi-search scenarios, giving a basic usage hint. However, it provides no explicit guidance on when to prefer this tool over SearchIndexTool or when not to use it.

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

SearchIndexToolB

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
sizeNoNumber of search results to return. The maximum allowed value is 100, unless overridden by configuration.
indexYesThe name of the index to search in
formatNoOutput format: "json" or "csv"json
query_dslYesThe 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.
aws_regionNoAWS region for IAM/Serverless authentication.
aws_iam_arnNoIAM role ARN for role-based authentication.
aws_profileNoAWS profile name for authentication.
opensearch_urlYesOpenSearch endpoint URL.
opensearch_no_authNoIf true, connect without authentication.
opensearch_timeoutNoConnection timeout in seconds.
opensearch_passwordNoPassword for basic authentication.
opensearch_usernameNoUsername for basic authentication.
opensearch_ssl_verifyNoSet true to require SSL certificate verification. A false value is ignored, since only the operator may disable verification.
aws_opensearch_serverlessNoIf true, use OpenSearch Serverless service.

TDQS

B3.1/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action but does not mention authentication requirements (despite multiple auth parameters), output format (though schema has a 'format' param), pagination, error behavior, or that results are returned. The prerequisite about mappings hints at a precondition but is minimal. For a tool with 14 parameters including auth, this is a significant gap.

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

Conciseness4/5

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

The description is one concise sentence plus a prerequisite note. It is front-loaded with the core action and avoids redundancy. The prerequisite is clearly marked. No wasted words, though it could be slightly more structured with separate usage guidance sections.

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

Completeness2/5

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

This is a complex tool with 14 parameters covering multiple authentication methods, timeouts, and output formats, and it has no output schema. The description only mentions the action and a prerequisite, but does not guide the agent on which auth parameters to choose (e.g., when to set opensearch_no_auth vs. providing credentials), nor does it describe the return structure or pagination. Given the tool's complexity and absence of annotations/output schema, the description is insufficiently complete for an agent to call it correctly without additional investigation.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all parameters in detail, including the rich query_dsl parameter with examples and rules about keyword suffixes and date formats. The tool description adds the prerequisite about mappings, which is helpful context for query construction, but does not add further parameter semantics beyond what the schema provides. Baseline 3 is appropriate given high schema coverage.

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

Purpose4/5

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

The description clearly states the action: 'Searches an index using a query written in query DSL'. It is specific about the resource (index) and the method (query DSL). However, it does not explicitly differentiate from siblings like MsearchTool (multi-search) or CountTool (count only), relying on the tool name and basic phrasing to imply single-index search.

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

Usage Guidelines3/5

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

The description provides a clear prerequisite: 'You need to know the mappings of the index before constructing queries.' This is useful guidance. However, it offers no comparison to alternative tools (e.g., when to use this vs. MsearchTool or CountTool) and no exclusions. The prerequisite is the only usage hint, leaving selection to the agent's inference.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 9 tool updatesv0.12.0
    • ChangedClusterHealthTool1 field changed
      • changedInput schema / properties / opensearch_ssl_verify / description
        Previous value: -"If false, disable SSL certificate verification."New value: +"Set true to require SSL certificate verification. A false value is ignored, since only the operator may disable verification."
    • ChangedCountTool1 field changed
      • changedInput schema / properties / opensearch_ssl_verify / description
        Previous value: -"If false, disable SSL certificate verification."New value: +"Set true to require SSL certificate verification. A false value is ignored, since only the operator may disable verification."
    • ChangedExplainTool1 field changed
      • changedInput schema / properties / opensearch_ssl_verify / description
        Previous value: -"If false, disable SSL certificate verification."New value: +"Set true to require SSL certificate verification. A false value is ignored, since only the operator may disable verification."
    • ChangedGenericOpenSearchApiTool1 field changed
      • changedInput schema / properties / opensearch_ssl_verify / description
        Previous value: -"If false, disable SSL certificate verification."New value: +"Set true to require SSL certificate verification. A false value is ignored, since only the operator may disable verification."
    • ChangedGetShardsTool1 field changed
      • changedInput schema / properties / opensearch_ssl_verify / description
        Previous value: -"If false, disable SSL certificate verification."New value: +"Set true to require SSL certificate verification. A false value is ignored, since only the operator may disable verification."
    • ChangedIndexMappingTool1 field changed
      • changedInput schema / properties / opensearch_ssl_verify / description
        Previous value: -"If false, disable SSL certificate verification."New value: +"Set true to require SSL certificate verification. A false value is ignored, since only the operator may disable verification."
    • ChangedListIndexTool1 field changed
      • changedInput schema / properties / opensearch_ssl_verify / description
        Previous value: -"If false, disable SSL certificate verification."New value: +"Set true to require SSL certificate verification. A false value is ignored, since only the operator may disable verification."
    • ChangedMsearchTool1 field changed
      • changedInput schema / properties / opensearch_ssl_verify / description
        Previous value: -"If false, disable SSL certificate verification."New value: +"Set true to require SSL certificate verification. A false value is ignored, since only the operator may disable verification."
    • ChangedSearchIndexTool1 field changed
      • changedInput schema / properties / opensearch_ssl_verify / description
        Previous value: -"If false, disable SSL certificate verification."New value: +"Set true to require SSL certificate verification. A false value is ignored, since only the operator may disable verification."
  2. 1 tool updatev0.11.0
    • ChangedExplainTool1 field changed
      • changedInput schema / required
        Previous value: -[
-  "body",
-  "index",
-  "id",
-  "opensearch_url"
-]New value: +[
+  "id",
+  "index",
+  "body",
+  "opensearch_url"
+]
  3. 9 tool updatesv0.9.0
    • First observedClusterHealthTool
    • First observedCountTool
    • First observedExplainTool
    • First observedGenericOpenSearchApiTool
    • First observedGetShardsTool
    • First observedIndexMappingTool
    • First observedListIndexTool
    • First observedMsearchTool
    • First observedSearchIndexTool
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored across 9 tools

Disambiguation4/5

Most tools target distinct actions such as listing indices, retrieving mappings, searching, counting, and checking cluster health. GenericOpenSearchApiTool intentionally overlaps with every dedicated tool, and MsearchTool overlaps somewhat with SearchIndexTool, but the descriptions provide enough guidance to choose correctly.

Naming Consistency4/5

All tool names use PascalCase with a Tool suffix, and most follow a Verb+Noun pattern like ListIndexTool, SearchIndexTool, and GetShardsTool. IndexMappingTool and ClusterHealthTool lack explicit action verbs, and MsearchTool uses an abbreviated name, so the pattern is not perfectly consistent.

Tool Count5/5

Nine tools is a well-scoped count for an OpenSearch server covering search, mappings, cluster health, shards, counts, and a generic API fallback. Each dedicated tool earns its place, and the count is comfortably within the ideal range.

Completeness4/5

The dedicated tools cover common read, search, and monitoring workflows well, and GenericOpenSearchApiTool provides an escape hatch for any unsupported endpoint. However, common operations like creating/deleting indices or document-level CRUD lack dedicated first-class tools, so coverage relies partly on the generic fallback.

Maintenance

ActivityNo data
ResponsivenessWithin a week

Resources

Related MCP Connectors

Related MCP Servers

  • OpenSearch MCP Server

    solanabughunter-glitch
    A
    license
    B
    quality
    D
    maintenance
    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.
    11
    Apache 2.0

  • OpenSearch MCP Server

    stackblaze
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI assistants to interact with OpenSearch clusters for searching indices, retrieving mappings, and managing shards through the MCP protocol.
    Apache 2.0

  • Elasticsearch MCP Server

    gpremo-re
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that enables AI assistants to directly interact with Elasticsearch for searching, aggregating, and retrieving documents from indices, supporting full-text search, semantic search, and various query modes.
    20 npm
    MIT