This HTTP-based Cosmos DB MCP server has three read-only tools with schemas present but significant gaps in descriptions, parameter documentation, and output schema clarity. Tool naming follows verb_noun conventions (query_documents, read_document, get_container_statistics), which is good. However, descriptions are minimal (12-35 chars for tools; 'Get statistics about the container' is vague), and parameter descriptions are sparse or missing context. The `parameters` field in query_documents is poorly explained (what format? what do these objects contain?), and no output schemas are documented. Error handling guidance is absent. Resource support is present but underdeveloped. This server would benefit from substantial documentation improvements before production use.

• Expand tool descriptions to 100-200 characters, stating WHAT (query Cosmos DB documents), WHEN (to fetch filtered results vs. single documents), and prerequisites (database connection required). Example: 'Execute a parameterized SQL query against Cosmos DB documents. Use when you need filtered results; for a single document by ID, use read_document. Returns up to 100 documents; paginate with OFFSET/LIMIT.'
• Document the 'parameters' array schema. Define the expected object structure inline: 'parameters: array of {name: string, value: any}, e.g., [{"name": "@status", "value": "active"}]'.
• Add output schema documentation for each tool. Example for read_document: 'Returns: {id, partition_key, data: {...}}' or link to Cosmos DB document structure. For query_documents: 'Returns: {documents: [...], count: number, next_cursor?: string}'.
• Add pagination and result limits to query_documents description: 'Results are capped at 100 documents per call. Use OFFSET/LIMIT in the SQL query or provide a cursor parameter for pagination.'
• Add error handling guidance to each tool description. Example: 'On invalid SQL, returns error with suggestion to check syntax. On partition key mismatch, suggests valid partition keys. On 404, returns available containers.'
• Warn about cross_partition=true cost in the description: 'Setting cross_partition to true may incur high RU costs for large containers. Default is true; set to false if partition key is known.'
• Expand resource descriptions. For cosmosdb://documents, explain: 'Returns a sample of the first 10 documents for discovery. Use query_documents for filtered or paginated results.'

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry