opensearch-mcp-server-py
OfficialServer Quality Checklist
Latest release: v0.11.0
- Disambiguation5/5
Each tool targets a distinct OpenSearch operation (cluster health, count, explain, shards, mappings, list indices, search, msearch) with no overlap. The generic API tool is clearly positioned as a fallback for unsupported endpoints.
Naming Consistency5/5All tool names follow a consistent PascalCase pattern: <Action><Resource>Tool (e.g., ClusterHealthTool, SearchIndexTool). No deviations or mixed conventions.
Tool Count5/59 tools is well-scoped for an OpenSearch server, covering core operations (health, search, count, mappings, etc.) without being overwhelming or too sparse.
Completeness3/5Missing dedicated tools for index CRUD (create, delete, update) and document operations beyond search/count. The generic API tool can fill these gaps, but it requires manual API knowledge, making it less accessible.
Average 3.2/5 across 9 of 9 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- 33 of 36 community issues answered or closed in the last 6 months
- 29 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior but only says 'execute search operations'. It omits important details such as authentication requirements, return format, and error handling. The schema covers parameters, but the description adds minimal context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks substance. It could include more helpful information without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (12 parameters, no output schema, multiple authentication options), the description is far too minimal. It does not explain how to construct the NDJSON body, what the response looks like, or how it differs from similar tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 92%, so most parameters are well-documented. The tool description adds no extra meaning beyond what the schema provides, so it meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it executes several search operations in one request, which matches the name 'MsearchTool'. However, it does not differentiate from sibling tools 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 Guidelines2/5Does 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 that it is intended for batching multiple searches to reduce overhead, nor does it exclude single-search usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description alone must disclose behavioral traits. It only says 'Returns basic information', which gives no insight into safety (e.g., read-only), idempotency, required permissions, or what specific data is returned. This is insufficient for an agent to anticipate side effects or authorization needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is easy to parse. While it could include more detail without becoming verbose, the current length is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 11 parameters covering complex authentication scenarios and no output schema, the description is too brief. It does not explain the nature of the 'basic information' returned, how to select among authentication methods, or any context about cluster health checks, leaving significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has high coverage (91%) with descriptions for most parameters. The description adds no additional information beyond what the schema already provides, so it meets the baseline but does not surpass it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool returns 'basic information about the health of the cluster', which clearly indicates the purpose. However, it does not specify that it is an OpenSearch cluster, and 'basic information' is somewhat vague, leaving room for ambiguity compared to a more detailed purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 sibling tools such as ListIndexTool or SearchIndexTool. There is no mention of prerequisites, recommended context, or alternatives, leaving the agent without strategic selection cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description fails to disclose behavioral traits beyond returning a count. It does not mention that the operation is read-only or describe the impact of the 'body' parameter on the query. Critical details about authentication, timeouts, or error handling are omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at one sentence, but it could be improved by adding a brief note on usage or linking to the schema for parameter details. It is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 parameters, no output schema, and no annotations, the description is insufficient. It does not explain the 'body' parameter's role in the query, limitations like max count, or how to handle authentication parameters. The tool's complexity demands more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 most parameters. The description adds no additional context about parameter usage or how they relate to the count operation, such as the role of 'body' in defining the query.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a count of documents matching a query, which matches the tool name and distinguishes it from sibling document retrieval tools like SearchIndexTool. However, it does not explicitly differentiate from other sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 MsearchTool. The description lacks explicit when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- 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. It only states the high-level purpose without disclosing that this is a read-only operation, what the response format is, or any prerequisites like authentication handled via parameters. The description adds minimal behavioral context beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, no wasted words. It could incorporate more context without being verbose. It is efficiently concise but lacks details that would improve utility.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 13 parameters, no output schema, and no annotations, the description is incomplete. It does not mention that it executes an OpenSearch explain API, what the expected return structure is, or any usage caveats. Much context is missing for a tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 85%, so the schema already documents most parameters. The description does not add any meaning beyond the schema; it does not explain that 'id' is the document ID or 'body' is the query. 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns information about why a document matches or doesn't match a query. It uses specific verbs ('returns information') and resource ('specific document'). However, it does not differentiate from sibling tools like SearchIndexTool, which is a related but distinct function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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. It does not mention that it is for debugging scoring or that it requires an existing query. Sibling tools like SearchIndexTool have overlapping contexts, but no exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. However, it only says 'Gets information', implying a read operation, but does not state side effects, authentication requirements, or any other behavioral traits. The description fails to add value beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words, and the main action is front-loaded. However, the brevity sacrifices completeness and context, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 11 parameters including complex authentication options and no output schema. The description does not explain what 'information about shards' includes, the return format, or how the parameters relate to the operation. This is insufficient for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described. The description adds no additional meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Gets' and the resource 'information about shards in OpenSearch', which is specific and distinct from sibling tools like ClusterHealthTool or SearchIndexTool. The 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 Guidelines2/5Does 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 or when not to use it. The description lacks any contextual hints about appropriate use cases, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions it is a search operation, which implies read-only, but does not explicitly state whether it modifies data, requires specific permissions, or has rate limits. The behavioral disclosure 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and includes a prerequisite. It is concise and front-loaded with the core purpose. However, it could be slightly more structured with separate sections, but it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (14 parameters, 3 required, no output schema), the description is incomplete. It does not explain the return format, pagination, error handling, or how to use it in conjunction with sibling tools. The prerequisite is useful but insufficient for a comprehensive understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 significant value for the 'query_dsl' parameter with detailed instructions on .keyword suffix and date format, which goes beyond the schema's description. Other parameters mostly repeat schema info, but the query_dsl guidance elevates this score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches an index using OpenSearch query DSL, which is a specific verb and resource. However, it does not differentiate from sibling tools like CountTool or MsearchTool, which also operate on indices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a prerequisite about knowing index mappings, which provides some usage guidance. However, it does not mention when to use this tool versus alternatives like CountTool or ExplainTool, nor does it specify 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It states 'Retrieves,' implying a read-only operation, but does not disclose error handling (e.g., if index does not exist), authentication requirements beyond the schema, rate limits, or potential performance impact. This is insufficient for an agent to understand side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence of 12 words. It includes the verb, resource, and context with no extraneous information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters (mostly connection-related) and no output schema, the description is incomplete. It does not describe what the returned mapping/setting information looks like or that it includes both mapping and settings. The agent lacks detail on expected return structure, which is critical for using the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond what the schema already provides for the 11 parameters. It does not clarify how connection parameters map to different auth methods or that 'index' is required. No additional value over schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: retrieving index mapping and setting information for an OpenSearch index. The verb 'Retrieves' specifies the operation, and the resource 'index mapping and setting information' is precise. This distinguishes it from sibling tools like ClusterHealthTool (cluster-level) or SearchIndexTool (search queries).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives. While the purpose implies it is for inspecting index configuration, there is no mention of prerequisites (e.g., the index must exist) or common usage patterns. The description does not advise against use in write-heavy contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- 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. However, it does not disclose potential side effects, authentication requirements beyond what's in the schema, error handling, or rate limits. For a generic API tool that can perform destructive operations (e.g., DELETE), 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, comprising two well-structured sentences. It is front-loaded with the core purpose and immediately provides usage context. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (15 parameters, no output schema, no annotations), the description is incomplete. It does not address error handling, response format, or authentication workflow beyond parameter names. The examples in the schema partially compensate, but the description itself lacks completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already fully describes each parameter (e.g., path, method, body). The description adds no additional meaning beyond 'supports all HTTP methods' and 'custom paths,' which aligns with the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a flexible tool for calling any OpenSearch API endpoint, supporting all HTTP methods and custom paths. It explicitly differentiates from siblings by noting when to use it: for APIs without dedicated tools or when more control is needed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Use this when you need to access OpenSearch APIs that don't have dedicated tools, or when you need more control over the request.' It also mentions leveraging your knowledge of OpenSearch API documentation, which helps the agent understand the expected workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It explains behavior for listing all indices vs specific patterns and detail control, but does not disclose read-only nature, authentication prerequisites, or potential performance impacts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the purpose and dive into details. No redundant or missing words. Efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a listing tool with 12 params (mostly auth), the description covers core behavior well. It explains output format (names vs metadata) but omits error handling, required permissions, or connection setup. Still, it's fairly complete given the presence of schema descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description reiterates the include_detail and index parameters but adds no new meaning beyond what's in the schema descriptions. No enums or nested objects to clarify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists OpenSearch indices, optionally filtering by name/pattern, and controlling detail level with include_detail flag. This distinguishes it from sibling tools like SearchIndexTool and GetShardsTool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. The description implies use for listing indices but does not mention when not to use or compare to siblings like ClusterHealthTool or SearchIndexTool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/opensearch-project/opensearch-mcp-server-py'
If you have feedback or need assistance with the MCP directory API, please join our Discord server