Add schema discovery command and read-only MCP tool (#160)

[mkrueger]

Summary

Implements the M4 schema / describe discovery tool from the Agentic & Automation Roadmap.

Adds a read-only schema command (and matching read-only MCP tool) that returns a cheap, bounded discovery summary of a Cosmos DB container so agents and users can understand a container's structure without repeatedly re-sampling or guessing field names.

For the current container (or --database/--container), schema returns:

• Partition key path(s)
• Indexing policy summary (mode, automatic flag, included/excluded path counts, composite/spatial/vector index counts)
• Estimated document count — read cheaply from the x-ms-resource-usage quota header, no scan
• Inferred field types from a bounded sample of documents — dot notation for nested objects, the distinct JSON types observed per field (string, number, boolean, object, array, null), and how many sampled documents contained each field

--sample <n> selects how many documents to sample and is clamped to 1-100 (default 20) so the single discovery query always stays bounded and read-only.

Sample output

{
  "database": "MyDB",
  "container": "Products",
  "partitionKeyPaths": ["/category"],
  "documentCountEstimate": 1280,
  "sampleSize": 20,
  "sampledDocuments": 20,
  "indexingPolicy": {
    "indexingMode": "consistent",
    "automatic": true,
    "includedPaths": 1,
    "excludedPaths": 1,
    "compositeIndexes": 0,
    "spatialIndexes": 0,
    "vectorIndexes": 0
  },
  "fields": [
    { "path": "id", "types": ["string"], "presence": 20 },
    { "path": "category", "types": ["string"], "presence": 20 },
    { "path": "price", "types": ["number"], "presence": 18 }
  ]
}

Acceptance criteria

• Command and MCP tool — [CosmosCommand("schema")] with [McpAnnotation(ReadOnly = true, Idempotent = true, OpenWorld = true)], auto-exposed as a read-only tool
• Bounded / read-only — single SELECT * FROM c capped at MaxItemCount, sample size clamped to 1-100; document count comes from the quota header (no scan)
• Structured output — JSON result for both the shell and MCP
• Docs + tests — README, docs/commands.md, CHANGELOG, and unit tests for the sample-clamping and type-inference helpers

Testing

• dotnet build CosmosDBShell/CosmosDBShell.csproj — 0 warnings, 0 errors
• dotnet build CosmosDBShell.Tests/CosmosDBShell.Tests.csproj
• dotnet test — 630 passed, 15 skipped (integration tests requiring a live account), 0 failed, including 12 new SchemaCommandTests

Fixes #160

[github-code-quality]

Code Coverage Overview

Languages: C#

C# / code-coverage/dotnet

The overall coverage in commit 30a075e in the dev/mkrueger/schema-... branch remains at 61%, unchanged from commit 4573ab3 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 4573ab3	dev/mkrueger/schema-... 30a075e	+/-
D:\a\CosmosDBSh...chemaCommand.cs	0%	33%	+33%

---

_{Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[Copilot]

Pull request overview

This PR adds a new schema discovery command (and matching read-only MCP tool) to provide a bounded, structured JSON summary of a Cosmos DB container—partition key paths, indexing policy summary, estimated document count, and inferred field types from a small sample—supporting agentic workflows that need fast, low-risk container introspection.

Changes:

• Introduces SchemaCommand with bounded sampling (--sample clamped to 1–100) and JSON schema inference (dot-notation paths + type sets + per-field presence).
• Adds unit tests covering sample clamping and schema/type inference helpers.
• Updates user-facing docs/help text (README, docs/commands.md, localization strings, CHANGELOG).

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
README.md	Adds schema to the feature list and describes its discovery output at a high level.
docs/commands.md	Documents schema usage, options, examples, and sample output JSON.
CosmosDBShell/lang/en.ftl	Adds localized descriptions for the schema command and its options.
CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/SchemaCommand.cs	Implements the new schema command and MCP annotation; includes sample clamping + field inference logic.
CosmosDBShell.Tests/CommandTests/SchemaCommandTests.cs	Adds unit tests for command registration and helper behaviors (clamping + inference).
CHANGELOG.md	Records the new schema command/tool as a new feature.