MCP CosmosDB

Server Quality Checklist

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

Latest release: v1.0.1
Disambiguation5/5
Every tool has a clearly distinct purpose, from schema analysis to CRUD operations to listing resources. Even the two query tools (mcp_get_documents and mcp_cosmos_query) are well-differentiated by complexity, with descriptions guiding appropriate use.
Naming Consistency5/5
All tools follow a consistent mcp_verb_noun pattern with snake_case, making it easy to predict tool names. The naming convention is uniform across all 13 tools, with no mixing of styles.
Tool Count5/5
With 13 tools, the set is well-scoped for a CosmosDB service. It covers all essential operations (CRUD, schema analysis, container info, list resources) without unnecessary bloat or gaps.
Completeness4/5
The tool surface covers the core CRUD lifecycle, schema analysis, container configuration, and statistics. Minor gaps like batch operations or container creation/deletion are absent but acceptable for a typical usage scope.
Average 4.2/5 across 13 of 13 tools scored. Lowest: 3.3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- Last stable release on July 31, 2025
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It misses key details: what happens if the id already exists (error?), whether the document is returned upon creation, and any side effects. The uniqueness constraint is mentioned, but behavior on violation is not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact with a clear structure: a one-liner purpose, a bulleted list of requirements, and an example. Every part serves a purpose without redundancy.
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 no output schema, the description should explain what the tool returns (e.g., the created document or a success indicator). It also doesn't cover error cases or default behavior for connection_id. For a data-modifying tool, these are significant 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 coverage is 100%, so baseline is 3. The description adds some value by stressing that 'id' must be unique within the partition and giving an example, but it largely restates schema info. No additional semantics for partition_key or connection_id beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new document in a CosmosDB container', which is a specific verb and resource. It differentiates from sibling tools like mcp_delete_document, mcp_update_document, and mcp_upsert_document by focusing exclusively on creation.
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 requirements and an example of when to use the tool, but it does not explicitly compare it to alternatives like mcp_upsert_document. An agent would benefit from knowing when to choose create over upsert or update.
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?
No annotations provided, so description carries full burden. It warns that the operation is irreversible and permanent, which is crucial behavioral context. However, it omits details like permission requirements, error handling (e.g., document not found), or idempotency.
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?
Extremely concise: one sentence for purpose, one for warning, and one example. No filler; every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers the essential action and provides a usage example. However, it lacks guidance on handling non-existent documents, error responses, or potential side effects beyond irreversibility.
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 has 100% description coverage for all 4 parameters, so description adds limited value. The example illustrates parameter usage but does not explain any nuance beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete a document') and the target resource ('from a CosmosDB container'), distinguishing it from sibling tools like mcp_create_document or mcp_update_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes a strong warning about irreversibility, which guides appropriate usage. However, it does not explicitly state when to use vs. alternatives (e.g., soft deletion) nor what to do if the document doesn't exist.
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?
No annotations are provided, so the description carries the full burden. It explains that the tool samples documents and discovers field names, data types, and frequency. It does not disclose whether the operation is read-only (likely safe), potential side effects, or edge cases (e.g., empty container). The behavioral disclosure is adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. It front-loads the action ('Analyze the schema/structure of documents') and efficiently adds behavioral context (sampling) and usage guidance. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description implies return values by mentioning 'field names, data types, and frequency.' This is sufficient for the agent to understand what to expect. It does not describe the exact format, but for a schema analysis tool, this level of completeness is good. The description covers purpose, behavior, and usage context.
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 baseline is 3. The description does not add parameter-specific details beyond what the schema already provides. It mentions 'samples documents' which relates to sample_size, but this is already described in the schema. No additional semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Analyze the schema/structure of documents in a container' and explains the sampling mechanism. It distinguishes from sibling tools like mcp_cosmos_query (which queries data) and mcp_create_document (which creates). The verb 'analyze' and resource 'schema/structure' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool before writing queries: 'Use this to understand the data model before writing queries.' This provides clear context. It does not mention when not to use or name alternatives, but the guidance is strong.
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?
No annotations provided, and the description does not explicitly state read-only or safety. However, the name 'get' and the description imply a read operation, which is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise paragraph with an example, no fluff. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description explains what the tool returns (partition key, indexing policy, throughput) despite no output schema. For a 2-parameter tool, this is complete.
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?
Input schema has 100% description coverage, so the description adds little beyond the schema. The example usage provides some extra context for parameter values.
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 tool gets detailed configuration of a specific container, listing specific items like partition key, indexing policy, and throughput. It distinguishes from sibling tools like mcp_list_containers and mcp_get_container_stats by focusing on a single container's detailed config.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this to understand the container structure before writing queries', providing clear context. Does not explicitly mention when not to use or alternatives, but the purpose is well-scoped.
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?
No annotations provided, so description carries full burden. It discloses the upsert behavior: 'If a document with the same id and partition key exists, it will be replaced. If it doesn't exist, a new document will be created.' This is adequate but lacks details on side effects, permissions, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise: two sentences of explanation plus an example. The first sentence states the purpose immediately. The example is useful without being verbose. Every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and a nested object parameter, the description explains the upsert semantics and provides an example. It does not describe return values or error handling, but for a basic upsert operation, the coverage is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, setting baseline at 3. The description adds an example that demonstrates parameter usage, such as matching partition_key to id, providing practical context beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create or update a document in a CosmosDB container (upsert operation)', specifying the verb (upsert) and resource (document in CosmosDB). It differentiates from siblings like mcp_create_document and mcp_update_document by clarifying the upsert behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use: to create or update a document, with conditional behavior based on existence. It provides context but does not explicitly exclude alternatives (e.g., when to use create or update separately), though the implied logic is clear given sibling tools.
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 adds some behavioral context: it notes that higher sample_size is 'more accurate but slower'. But it omits details like read-only nature, authentication requirements, or potential impact on container performance. This is a marginal improvement over no description.
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 concise sentences plus a helpful example. Every sentence adds necessary information with no filler or repetition. Front-loaded with purpose, then usage, then example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description lists the statistical outputs (document count, estimated size, partition key distribution), which adequately informs about return values. It could mention the return format (JSON) but is sufficient for a tool this simple.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all parameters (100% coverage). The description adds value by providing an example with sample_size=500 and an additional note on the trade-off between accuracy and speed for sample_size. This goes beyond the schema's default description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('get') and resources ('statistical information about a container') and lists concrete metrics (document count, estimated size, partition key distribution). It clearly distinguishes from sibling tools like mcp_analyze_schema or query tools by focusing on stats for capacity planning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use this for capacity planning and performance analysis', providing a clear use case. However, it does not mention when not to use it or point to alternative tools (e.g., mcp_analyze_schema for schema details).
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?
No annotations provided, so description carries burden. It states it returns IDs, timestamps, and ETags, but does not mention permissions, rate limits, or default behavior for connection_id.
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 purpose, no wasted words. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage guidance, and return values. Lacks mention of default connection behavior and any pagination, but adequate for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description of connection_id. The tool description adds value by referencing mcp_list_connections to find available connections.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all databases in a CosmosDB account, distinct from sibling tools like mcp_list_containers and mcp_list_connections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this to discover available databases before querying containers', providing clear context for when to use it. Does not explicitly exclude alternatives but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses important performance implications like timeouts and high RU consumption for SELECT *. No annotations exist, so the description carries the full burden. Could mention pagination or error scenarios, but covers key behaviors.
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?
Well-structured with a concise opening, bolded warnings, and clear examples. Some redundancy in examples but overall efficient for the depth of information provided.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers syntax, parameters, warnings, and example queries. Without an output schema, the description provides sufficient context for correct usage, though it could mention result format briefly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by providing examples of parameter usage and showing the @paramName syntax, which complements the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Execute a CosmosDB SQL query against a container' and distinguishes itself from sibling tools by specifying it's for 'complex queries with JOINs, aggregations, or custom SQL syntax'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use (complex queries) and includes strong warnings against SELECT * and recommends TOP N and field projection. However, it does not directly mention alternative tools for simpler operations.
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?
No annotations provided, so description carries full burden. It describes the operation as a point read and gives constraints, but does not disclose what happens on missing document (e.g., null vs error), nor any permissions or rate limits. Basic behavior is covered but lacks detail on outcomes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two short paragraphs and a code example. It front-loads the core purpose, then provides crucial usage notes, and ends with an illustrative example. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is largely complete given the tool's simplicity and the presence of a full input schema. However, it lacks any mention of the return format (e.g., the document object), which is relevant since there is no output schema. This is a minor gap for a retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds significant value: it explains the importance of partition_key type matching, that both ID and partition key are required for a point read, and provides a concrete example. This enriches understanding beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single document by its ID and partition key.' It uses specific verb ('get') and resource ('document'), and differentiates from siblings by noting it is the 'most efficient way to retrieve a specific document,' contrasting with query or list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly requires both document_id and partition_key for a point read, and notes the partition_key type must match the container's key type. It provides an example. While it doesn't explicitly state when not to use it, the conditions for correct usage are clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states each connection points to a different account/database, which is helpful. However, it does not disclose any other behavioral traits like read-only or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The purpose is front-loaded and the description is perfectly concise for a simple list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description is complete. It explains what the tool lists and how to use the outputs (connection_id values). No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so the description adds meaning by explaining what the tool does. Baseline for 0 parameters is 4, and the description provides clear context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all CosmosDB connections, distinguishing it from sibling tools like mcp_list_databases (which lists databases) and other query tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells agents to use this to discover connection_id values, providing clear context. Does not mention when not to use, but for a simple list tool this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses return types (container IDs, partition key paths, indexing policies) and implies a safe read operation. It does not mention auth or rate limits, but given the nature of the tool, this is adequate.
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 consists of exactly two sentences, with the essential purpose in the first sentence. Every word earns its place, and there is no fluff or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (single optional parameter, no output schema), the description fully covers what the tool does, when to use it, and what it returns. No gaps remain for an agent to misinterpret.
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 coverage is 100%, so the schema already describes the optional connection_id parameter. The description does not add further meaning to this parameter, but it adds value by explaining the overall return structure and purpose of the results.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all containers') and the resource ('connected CosmosDB database'), and it distinguishes itself from siblings like mcp_get_container_definition and mcp_list_databases by specifying scope ('all containers') and mention of partition key configurations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Use this to discover available containers and their partition key configurations before querying data.' It does not explicitly state when not to use it or name alternatives, but the context is clear and sufficient for most cases.
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?
No annotations are provided, so the description carries full burden. It implies a read operation but does not explicitly state side effects, idempotency, or cost implications. However, it does not mislead and accurately describes the tool's capabilities.
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 well-structured: a brief purpose statement, followed by a bulleted list of when to use, then two illustrative examples. No redundant sentences, and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters and no output schema, the description covers the tool's use cases well, including examples for key scenarios. However, it omits mention of return format or pagination, which could be helpful for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds value by providing concrete examples, explaining '_ts' for timestamp ordering, and showing filter_conditions usage. It goes beyond schema by contextualizing parameters in real queries.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it gets documents with simple filters/ordering, and explicitly contrasts with mcp_cosmos_query for complex SQL queries. The verb 'get' and resource 'documents' are precise, and examples reinforce the purpose.
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?
Explicitly tells when to use (simple queries, equality filters, partition key filtering, ordering) and when not to (complex queries, directing to mcp_cosmos_query). Provides best-use scenarios in a bulleted list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states 'full document replacement' and that all fields must be included. However, it does not mention what happens if the document doesn't exist or other side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: a clear purpose statement, a note about replacement behavior, and an example. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully explains the tool's behavior, prerequisites (get document for partial updates), and all required parameters. It references relevant sibling tools for context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds value by explaining the full replacement nature and need to include all fields, plus an example demonstrating usage, which is beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates (replaces) an existing document in a CosmosDB container. It distinguishes from sibling tools like mcp_create_document, mcp_delete_document, and mcp_upsert_document by specifying it's a full replacement.
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?
Provides explicit guidance: 'For partial updates, first get the document with mcp_get_document_by_id, modify it, then update.' This tells the agent when to use this tool versus alternatives and includes an example.
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:

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

Score Badge

Copy to your README.md:

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

Latest Blog Posts

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

MCP directory API

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

curl -X GET 'https://glama.ai/api/mcp/v1/servers/hendrickcastro/MCPCosmosDB'

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