Skip to main content
Glama
hendrickcastro

MCP CosmosDB

by hendrickcastro
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

MCP CosmosDB - Azure CosmosDB MCP Server

License: MIT npm version Downloads Node.js Version TypeScript GitHub stars GitHub issues GitHub forks Build Status Coverage Status Azure CosmosDB MCP Protocol Claude Desktop Cursor IDE Trae AI

A comprehensive Model Context Protocol (MCP) server for Azure CosmosDB database operations. This server provides 13 powerful tools for document database analysis, container discovery, data querying, and CRUD operations through the MCP protocol.

✨ Features

  • 🔗 Multi-Connection Support: Manage multiple CosmosDB accounts/databases from a single MCP instance

  • 🔒 Security First: Write operations disabled by default

  • ⚡ High Performance: Connection caching and optimized queries

  • 📊 13 Tools: Complete set of database operations

Related MCP server: Filesystem MCP Server

🚀 Quick Start

Prerequisites

  • Node.js 18+ and npm

  • Azure CosmosDB database with connection string

  • MCP-compatible client (Claude Desktop, Cursor IDE, etc.)

⚙️ Configuration

Configuration Priority

The server supports three configuration methods (in order of priority):

Priority

Method

Environment Variable

Description

1️⃣

External File

COSMOS_CONNECTIONS_FILE

Path to JSON file with connections array

2️⃣

JSON String

COSMOS_CONNECTIONS

Inline JSON array of connections

3️⃣

Single Connection

COSMOS_CONNECTION_STRING + COSMOS_DATABASE_ID

Legacy single connection mode

🔒 Security Configuration

Variable

Description

Default

DB_ALLOW_MODIFICATIONS

Enable/disable write operations (create, update, delete, upsert)

false

⚠️ IMPORTANT: By default, all write operations are DISABLED for safety. Set DB_ALLOW_MODIFICATIONS=true only when you need to perform write operations.

📦 Installation Options

Option 1: Multi-Connection with External File (Recommended) ✅

Create a connections file (e.g., cosmos-connections.json):

[
  {
    "id": "production",
    "connectionString": "AccountEndpoint=https://myapp-prod.documents.azure.com:443/;AccountKey=...;",
    "databaseId": "ProductionDB",
    "allowModifications": false,
    "description": "Production database (read-only)"
  },
  {
    "id": "development",
    "connectionString": "AccountEndpoint=https://myapp-dev.documents.azure.com:443/;AccountKey=...;",
    "databaseId": "DevDB",
    "allowModifications": true,
    "description": "Development database"
  },
  {
    "id": "analytics",
    "connectionString": "AccountEndpoint=https://analytics.documents.azure.com:443/;AccountKey=...;",
    "databaseId": "AnalyticsDB",
    "allowModifications": false,
    "description": "Analytics database"
  }
]

Configure your MCP client:

{
  "mcpServers": {
    "cosmosdb": {
      "command": "npx",
      "args": ["-y", "mcpcosmosdb@latest"],
      "env": {
        "COSMOS_CONNECTIONS_FILE": "/path/to/cosmos-connections.json"
      }
    }
  }
}

Option 2: Multi-Connection with Inline JSON

{
  "mcpServers": {
    "cosmosdb": {
      "command": "npx",
      "args": ["-y", "mcpcosmosdb@latest"],
      "env": {
        "COSMOS_CONNECTIONS": "[{\"id\":\"prod\",\"connectionString\":\"AccountEndpoint=https://...\",\"databaseId\":\"ProdDB\",\"allowModifications\":false},{\"id\":\"dev\",\"connectionString\":\"AccountEndpoint=https://...\",\"databaseId\":\"DevDB\",\"allowModifications\":true}]"
      }
    }
  }
}

Option 3: Single Connection (Legacy)

Read-Only Mode (Default - Safe):

{
  "mcpServers": {
    "cosmosdb": {
      "command": "npx",
      "args": ["-y", "mcpcosmosdb@latest"],
      "env": {
        "COSMOS_CONNECTION_STRING": "AccountEndpoint=https://your-cosmos-account.documents.azure.com:443/;AccountKey=your-account-key-here;",
        "COSMOS_DATABASE_ID": "your-database-name"
      }
    }
  }
}

With Write Operations Enabled:

{
  "mcpServers": {
    "cosmosdb": {
      "command": "npx",
      "args": ["-y", "mcpcosmosdb@latest"],
      "env": {
        "COSMOS_CONNECTION_STRING": "AccountEndpoint=https://your-cosmos-account.documents.azure.com:443/;AccountKey=your-account-key-here;",
        "COSMOS_DATABASE_ID": "your-database-name",
        "DB_ALLOW_MODIFICATIONS": "true"
      }
    }
  }
}

Option 4: NPX from GitHub

{
  "mcpServers": {
    "cosmosdb": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/MCPCosmosDB"],
      "env": {
        "COSMOS_CONNECTION_STRING": "AccountEndpoint=https://...;AccountKey=...;",
        "COSMOS_DATABASE_ID": "your-database-name"
      }
    }
  }
}

Option 5: Local Development

git clone https://github.com/hendrickcastro/MCPCosmosDB.git
cd MCPCosmosDB
npm install && npm run build
{
  "mcpServers": {
    "cosmosdb": {
      "command": "node",
      "args": ["path/to/MCPCosmosDB/dist/server.js"],
      "env": {
        "COSMOS_CONNECTIONS_FILE": "/path/to/cosmos-connections.json"
      }
    }
  }
}

🛠️ Available Tools (13 Total)

🔗 Connection Management

Tool

Description

mcp_list_connections

List all configured connections with their status

📖 Read Operations (Always Available)

Tool

Description

mcp_list_databases

List all databases in the CosmosDB account

mcp_list_containers

List all containers in the current database

mcp_get_container_definition

Get detailed container configuration (partition key, indexing policy, throughput)

mcp_get_container_stats

Get container statistics (document count, size, partition distribution)

mcp_cosmos_query

Execute SQL queries with parameters and performance metrics

mcp_get_documents

Retrieve documents with optional filtering

mcp_get_document_by_id

Get a specific document by ID and partition key

mcp_analyze_schema

Analyze document schema structure in containers

✏️ Write Operations (Require allowModifications: true)

Tool

Description

mcp_create_document

Create a new document in a container

mcp_update_document

Update (replace) an existing document

mcp_delete_document

Delete a document from a container

mcp_upsert_document

Create or update a document (upsert operation)

🛡️ Security Note: Write operations are blocked by default. Set allowModifications: true in the connection config or DB_ALLOW_MODIFICATIONS=true for single connection mode.

📋 Usage Examples

Multi-Connection Usage

// List all available connections
const connections = await mcp_list_connections();
// Returns: { connections: [{id: "prod", databaseId: "ProdDB", isConnected: true}, ...] }

// Query specific connection using connection_id
const prodData = await mcp_cosmos_query({
  connection_id: "production",
  container_id: "users",
  query: "SELECT TOP 10 c.id, c.name FROM c ORDER BY c._ts DESC"
});

const devData = await mcp_cosmos_query({
  connection_id: "development",
  container_id: "users",
  query: "SELECT TOP 10 c.id, c.name FROM c ORDER BY c._ts DESC"
});

Container Analysis

// List all containers (uses default connection if connection_id not specified)
const containers = await mcp_list_containers({
  connection_id: "production"
});

// Get container definition
const containerDef = await mcp_get_container_definition({ 
  connection_id: "production",
  container_id: "users" 
});

// Get container statistics
const stats = await mcp_get_container_stats({ 
  connection_id: "production",
  container_id: "users",
  sample_size: 1000
});

Querying Data

⚠️ IMPORTANT: Always use TOP N and specify fields. NEVER use SELECT * - it causes timeouts and high RU consumption in large containers.

// ✅ CORRECT: Using TOP and specific fields
const result = await mcp_cosmos_query({
  connection_id: "production",
  container_id: "products",
  query: "SELECT TOP 50 c.id, c.name, c.price FROM c WHERE c.category = @category",
  parameters: { category: "electronics" }
});

// ❌ WRONG: SELECT * without TOP (will timeout on large containers)
// query: "SELECT * FROM c WHERE c.category = @category"

// Get documents with simple filters
const documents = await mcp_get_documents({
  connection_id: "production",
  container_id: "orders",
  filter_conditions: { status: "completed" },
  order_by: "_ts",
  order_direction: "DESC",
  limit: 100
});

Document Operations

// Get specific document by ID
const document = await mcp_get_document_by_id({
  connection_id: "production",
  container_id: "users",
  document_id: "user-123",
  partition_key: "user-123"
});

// Analyze schema
const schema = await mcp_analyze_schema({
  connection_id: "production",
  container_id: "products",
  sample_size: 500
});

CRUD Operations (Requires allowModifications: true)

// Create a new document
const created = await mcp_create_document({
  connection_id: "development",  // Use a connection with write access
  container_id: "users",
  document: {
    id: "user-456",
    email: "user@example.com",
    name: "John Doe",
    status: "active"
  },
  partition_key: "user-456"
});

// Update a document (full replacement)
const updated = await mcp_update_document({
  connection_id: "development",
  container_id: "users",
  document_id: "user-456",
  document: {
    id: "user-456",
    email: "newemail@example.com",
    name: "John Doe",
    status: "inactive"
  },
  partition_key: "user-456"
});

// Upsert a document (create or update)
const upserted = await mcp_upsert_document({
  connection_id: "development",
  container_id: "users",
  document: {
    id: "user-789",
    email: "another@example.com",
    name: "Jane Doe"
  },
  partition_key: "user-789"
});

// Delete a document
const deleted = await mcp_delete_document({
  connection_id: "development",
  container_id: "users",
  document_id: "user-456",
  partition_key: "user-456"
});

🔧 Connection File Schema

interface ConnectionConfig {
  id: string;                    // Unique identifier for the connection
  connectionString: string;      // CosmosDB connection string
  databaseId: string;            // Database ID to connect to
  allowModifications?: boolean;  // Enable write operations (default: false)
  description?: string;          // Optional description
}

Example cosmos-connections.json:

[
  {
    "id": "athlete",
    "connectionString": "AccountEndpoint=https://dbsqlcosmosathlete.documents.azure.com:443/;AccountKey=...;",
    "databaseId": "data",
    "allowModifications": false,
    "description": "Athlete data"
  },
  {
    "id": "events",
    "connectionString": "AccountEndpoint=https://dbsqlcosmosevents.documents.azure.com:443/;AccountKey=...;",
    "databaseId": "events",
    "allowModifications": false,
    "description": "Events data"
  }
]

🚨 Troubleshooting

Connection Issues:

  • Invalid connection string: Verify connection string format includes AccountEndpoint and AccountKey

  • Database not found: Check databaseId matches existing database

  • Request timeout: Increase COSMOS_MAX_RETRY_WAIT_TIME or check network

Query Issues:

  • Query timeout: Use TOP N to limit results, specify only needed fields, avoid SELECT *

  • Cross partition query required: Set enable_cross_partition: true in query parameters

  • Partition key required: Specify partition_key for single-partition operations

Multi-Connection Issues:

  • Connection not found: Use mcp_list_connections to see available connection IDs

  • Wrong database: Verify the connection_id parameter points to the correct connection

Write Operation Blocked:

  • Error: "Database modifications are disabled": Set allowModifications: true in connection config or DB_ALLOW_MODIFICATIONS=true

  • This is a safety feature - write operations are disabled by default

CosmosDB Emulator:

  1. Install Azure CosmosDB Emulator

  2. Start emulator on port 8081

  3. Use default emulator connection string

  4. Create database and containers for testing

🧪 Development

npm test          # Run tests
npm run build     # Build project
npm start         # Development mode

🏗️ Architecture

Project Structure:

src/
├── tools/                    # Tool implementations
│   ├── containerAnalysis.ts  # Container operations
│   ├── dataOperations.ts     # Data queries & CRUD
│   └── types.ts              # Type definitions
├── db.ts                     # CosmosDB connection & multi-connection management
├── server.ts                 # MCP server setup
└── tools.ts                  # Tool definitions

Key Features:

  • ⚡ Connection caching and pooling

  • 🔗 Multi-connection management

  • 🛡️ Comprehensive error handling

  • 🔒 Write operation protection per connection

  • 📊 Performance metrics and request charges

  • 🔧 Flexible configuration options

  • 📋 Intelligent schema analysis

📝 Important Notes

  • Query Best Practices: Always use TOP N and specify fields - never use SELECT *

  • Container IDs: Use exact names as in CosmosDB

  • Partition Keys: Required for optimal performance and CRUD operations

  • Cross-Partition Queries: Can be expensive; use filters

  • Request Charges: Monitor RU consumption

  • Security: Store connection strings securely (use external file)

  • Write Protection: Enable only for connections that need it

🤝 Contributing

  1. Fork the repository

  2. Create feature branch (git checkout -b feature/name)

  3. Make changes and add tests

  4. Ensure tests pass (npm test)

  5. Commit changes (git commit -m 'Add feature')

  6. Push and open Pull Request

📄 License

MIT License - see LICENSE file for details.

🏷️ Tags & Keywords

Database: cosmosdb azure-cosmosdb nosql document-database database-analysis database-tools azure database-management database-operations data-analysis multi-database

MCP & AI: model-context-protocol mcp-server mcp-tools ai-tools claude-desktop cursor-ide anthropic llm-integration ai-database intelligent-database

Technology: typescript nodejs npm-package cli-tool database-client nosql-client database-sdk rest-api json-api database-connector

Features: container-analysis document-operations sql-queries schema-analysis query-execution database-search data-exploration database-insights partition-management throughput-analysis crud-operations document-crud multi-connection

Use Cases: database-development data-science business-intelligence database-migration schema-documentation performance-analysis data-governance database-monitoring troubleshooting automation

🙏 Acknowledgments

🎯 MCP CosmosDB provides comprehensive Azure CosmosDB database analysis through the Model Context Protocol. Perfect for developers and data analysts working with CosmosDB! 🚀

Available Tools

13 tools
mcp_analyze_schemaA

Analyze the schema/structure of documents in a container. Samples documents to discover field names, data types, and frequency. Use this to understand the data model before writing queries.

ParametersJSON Schema
NameRequiredDescriptionDefault
container_idYesThe ID/name of the container to analyze
sample_sizeNoNumber of documents to sample for analysis (default: 100)
connection_idNoID of the connection to use. Use mcp_list_connections to see available connections. If not specified, uses the default connection.

TDQS

A4/5.0
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.

mcp_cosmos_queryA

Execute a CosmosDB SQL query against a container. Use this for complex queries with JOINs, aggregations, or custom SQL syntax.

⚠️ IMPORTANT - AVOID SELECT *:

  • NEVER use SELECT * in large containers - it causes timeouts and high RU consumption

  • ALWAYS use TOP N to limit results: SELECT TOP 10 c.id, c.name FROM c

  • ALWAYS specify only the fields you need: SELECT c.id, c.name, c.email FROM c

COSMOSDB SQL SYNTAX EXAMPLES:

  • Basic: SELECT TOP 10 c.id, c.name FROM c WHERE c.status = @status

  • With projection: SELECT c.id, c.name, c.email FROM c

  • Aggregation: SELECT VALUE COUNT(1) FROM c

  • Array contains: SELECT TOP 20 c.id FROM c WHERE ARRAY_CONTAINS(c.tags, 'urgent')

  • Nested: SELECT TOP 10 c.id, c.address FROM c WHERE c.address.city = 'Madrid'

  • ORDER BY: SELECT TOP 10 c.id, c._ts FROM c ORDER BY c._ts DESC

PARAMETERS: Use @paramName syntax and provide values in the 'parameters' object. Example: query="SELECT TOP 10 c.id, c.type FROM c WHERE c.type = @type", parameters={type: "order"}

ParametersJSON Schema
NameRequiredDescriptionDefault
container_idYesThe ID/name of the container to query
queryYesCosmosDB SQL query. Use 'c' as the alias for the container. ALWAYS use TOP N and specify fields - NEVER use SELECT *. Example: 'SELECT TOP 10 c.id, c.name FROM c WHERE c.active = true'
parametersNoQuery parameters as key-value pairs (without @ prefix). Example: {status: 'active', limit: 10}
max_itemsNoMaximum number of items to return (default: 100, max recommended: 1000)
enable_cross_partitionNoEnable cross-partition queries. Set to true unless querying within a single partition key value.
connection_idNoID of the connection to use. Use mcp_list_connections to see available connections. If not specified, uses the default connection.

TDQS

A4.3/5.0
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.

mcp_create_documentB

Create a new document in a CosmosDB container.

REQUIREMENTS:

  • The document MUST have an 'id' field (string)

  • The document MUST have the partition key field with a value

  • The 'id' must be unique within the partition

Example: mcp_create_document({ container_id: 'users', document: {id: 'user-456', email: 'test@example.com', status: 'active'}, partition_key: 'user-456', connection_id: 'athlete' })

ParametersJSON Schema
NameRequiredDescriptionDefault
container_idYesThe ID/name of the container
documentYesThe document to create. Must include 'id' field and the partition key field.
partition_keyYesThe partition key value for the document
connection_idNoID of the connection to use. Use mcp_list_connections to see available connections. If not specified, uses the default connection.

TDQS

B3.3/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 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.

mcp_delete_documentA

Delete a document from a CosmosDB container.

WARNING: This operation is irreversible. The document will be permanently deleted.

Example: mcp_delete_document({ container_id: 'users', document_id: 'user-456', partition_key: 'user-456', connection_id: 'athlete' })

ParametersJSON Schema
NameRequiredDescriptionDefault
container_idYesThe ID/name of the container
document_idYesThe ID of the document to delete
partition_keyYesThe partition key value for the document
connection_idNoID of the connection to use. Use mcp_list_connections to see available connections. If not specified, uses the default connection.

TDQS

A3.9/5.0
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.

mcp_get_container_definitionA

Get detailed configuration of a specific container including partition key, indexing policy, and throughput settings. Use this to understand the container structure before writing queries. Example: mcp_get_container_definition({container_id: 'users', connection_id: 'athlete'})

ParametersJSON Schema
NameRequiredDescriptionDefault
container_idYesThe ID/name of the container (e.g., 'users', 'orders', 'products')
connection_idNoID of the connection to use. Use mcp_list_connections to see available connections. If not specified, uses the default connection.

TDQS

A4.1/5.0
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.

mcp_get_container_statsA

Get statistical information about a container including document count, estimated size, and partition key distribution. Use this for capacity planning and performance analysis. Example: mcp_get_container_stats({container_id: 'orders', sample_size: 500})

ParametersJSON Schema
NameRequiredDescriptionDefault
container_idYesThe ID/name of the container to analyze
sample_sizeNoNumber of documents to sample for statistics (default: 1000, higher = more accurate but slower)
connection_idNoID of the connection to use. Use mcp_list_connections to see available connections. If not specified, uses the default connection.

TDQS

A4.2/5.0
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.

mcp_get_document_by_idA

Get a single document by its ID and partition key. This is the most efficient way to retrieve a specific document.

IMPORTANT: Both document_id and partition_key are required for a point read in CosmosDB. The partition_key type must match your container's partition key type.

Example: mcp_get_document_by_id({container_id: 'users', document_id: 'user-123', partition_key: 'user-123', connection_id: 'athlete'})

ParametersJSON Schema
NameRequiredDescriptionDefault
container_idYesThe ID/name of the container
document_idYesThe unique ID of the document (the 'id' field value)
partition_keyYesThe partition key value for the document. Must match the container's partition key path value.
connection_idNoID of the connection to use. Use mcp_list_connections to see available connections. If not specified, uses the default connection.

TDQS

A4.3/5.0
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.

mcp_get_documentsA

Get documents from a container with simple filters and ordering. Use this for basic queries without complex SQL syntax.

FOR COMPLEX QUERIES: Use mcp_cosmos_query instead. THIS TOOL IS BEST FOR:

  • Getting all documents (with limit)

  • Simple equality filters on fields

  • Filtering by partition key for performance

  • Getting the most recent or oldest documents using order_by

Example: mcp_get_documents({container_id: 'users', limit: 10, order_by: '_ts', order_direction: 'DESC', connection_id: 'athlete'}) Example: mcp_get_documents({container_id: 'users', limit: 50, filter_conditions: {status: 'active'}})

ParametersJSON Schema
NameRequiredDescriptionDefault
container_idYesThe ID/name of the container to query
limitNoMaximum number of documents to return (default: 100)
partition_keyNoOptional partition key value to filter by. Improves performance significantly.
filter_conditionsNoSimple equality filters as key-value pairs. Example: {status: 'active', type: 'premium'}
order_byNoField name to order results by. Use '_ts' for timestamp ordering (most recent/oldest). Example: '_ts', 'creationDate', 'name'
order_directionNoSort direction: 'ASC' for ascending (oldest first), 'DESC' for descending (newest first). Default: 'ASC'ASC
connection_idNoID of the connection to use. Use mcp_list_connections to see available connections. If not specified, uses the default connection.

TDQS

A4.4/5.0
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.

mcp_list_connectionsA

List all available CosmosDB connections configured in this MCP server. Use this to discover which connection_id values you can use. Each connection points to a different CosmosDB account/database.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
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.

mcp_list_containersA

List all containers in the connected CosmosDB database. Use this to discover available containers and their partition key configurations before querying data. Returns container IDs, partition key paths, and indexing policies.

ParametersJSON Schema
NameRequiredDescriptionDefault
connection_idNoID of the connection to use. Use mcp_list_connections to see available connections. If not specified, uses the default connection.

TDQS

A4.3/5.0
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.

mcp_list_databasesA

List all databases in the CosmosDB account. Use this to discover available databases before querying containers. Returns database IDs, timestamps, and ETags.

ParametersJSON Schema
NameRequiredDescriptionDefault
connection_idNoID of the connection to use. Use mcp_list_connections to see available connections. If not specified, uses the default connection.

TDQS

A4.2/5.0
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.

mcp_update_documentA

Update (replace) an existing document in a CosmosDB container.

NOTE: This performs a full document replacement. Include ALL fields you want to keep. For partial updates, first get the document with mcp_get_document_by_id, modify it, then update.

Example: mcp_update_document({ container_id: 'users', document_id: 'user-456', document: {id: 'user-456', email: 'new@example.com', status: 'inactive'}, partition_key: 'user-456', connection_id: 'athlete' })

ParametersJSON Schema
NameRequiredDescriptionDefault
container_idYesThe ID/name of the container
document_idYesThe ID of the document to update
documentYesThe complete document with updated values. Must include 'id' field.
partition_keyYesThe partition key value for the document
connection_idNoID of the connection to use. Use mcp_list_connections to see available connections. If not specified, uses the default connection.

TDQS

A4.7/5.0
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.

mcp_upsert_documentA

Create or update a document in a CosmosDB container (upsert operation).

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.

Example: mcp_upsert_document({ container_id: 'users', document: {id: 'user-456', email: 'test@example.com', lastUpdated: '2024-01-15'}, partition_key: 'user-456', connection_id: 'athlete' })

ParametersJSON Schema
NameRequiredDescriptionDefault
container_idYesThe ID/name of the container
documentYesThe document to create or update. Must include 'id' field and the partition key field.
partition_keyYesThe partition key value for the document
connection_idNoID of the connection to use. Use mcp_list_connections to see available connections. If not specified, uses the default connection.

TDQS

A4.1/5.0
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.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
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.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Azure MCP Server

    mashriram
    A
    license
    A
    quality
    D
    maintenance
    This server implements the Model Context Protocol for seamless interaction with Azure Blob Storage and Cosmos DB, enabling automatic logging and audit tracking of operations.
    19
    5
    MIT

  • Filesystem MCP Server

    bsmi021
    A
    license
    Not graded
    quality
    F
    maintenance
    A Model Context Protocol server that provides file system operations, analysis, and manipulation capabilities through a standardized tool interface.
    6
    MIT

  • MCPQL

    hendrickcastro
    A
    license
    B
    quality
    C
    maintenance
    A comprehensive Model Context Protocol server for SQL Server database operations that provides 10 powerful tools for database analysis, object discovery, and data manipulation.
    11
    183
    15
    MIT

  • sql-mcp

    NakiriYuuzu
    A
    license
    Not graded
    quality
    C
    maintenance
    A Model Context Protocol server for interacting with MSSQL and PostgreSQL databases, offering tools for schema exploration and SQL execution. It features configurable query modes for safety and supports advanced authentication methods like Windows Auth and SSL.
    17
    MIT

Latest Blog Posts

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