From documentdb
Optimizes Azure DocumentDB/MongoDB queries and indexes using explain plans, index stats, and schema analysis. Invoked for slow query diagnosis, index recommendations, and performance tuning.
How this skill is triggered — by the user, by Claude, or both
Slash command
/documentdb:query-optimizerThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Invoke **only** when the user wants:
Invoke only when the user wants:
Do not invoke for routine query authoring unless the user has requested help with optimization, slow queries, or indexing.
If the user is asking about a particular query:
list_indexes to get existing indexes on the collectionoptimize_find_query (for find queries) or explain_aggregate_query
(for aggregation pipelines) to get explain output with execution statsfind_documents with limit=1 to fetch a sample document to understand the
schemaThen make an optimization suggestion based on collected information and best practices from the reference files. Prefer creating an index that fully covers the query if possible.
If the user wants to examine slow queries or is looking for general performance suggestions (not regarding any particular query):
list_databases and get_db_info to understand the database structurecollection_stats to identify large collectionsindex_stats to check existing index usagecurrent_ops to see currently running operationsDatabase tools (for query optimization):
| Tool name (exact) | Description |
|---|---|
list_indexes | List all indexes on a collection — check if the query can use an existing index |
optimize_find_query | Run explain with executionStats for a find query, returning metrics, plan shape, index stats, and collection stats in one call |
explain_aggregate_query | Run explain with executionStats for an aggregation pipeline |
explain_find_query | Run explain for a find query (lower-level than optimize_find_query) |
explain_count_query | Run explain for a count query |
find_documents | Fetch sample documents to understand schema — use with limit=1 |
collection_stats | Get collection statistics (size, document count, storage) |
index_stats | Get index usage statistics ($indexStats) |
current_ops | Get currently running database operations |
create_index | Create a new index (only after user approval) |
drop_index | Drop an existing index (only after user approval) |
Before beginning diagnosis and recommendation, load reference files.
Always load:
references/core-indexing-principles.mdFor a specific query, run these tools (when MCP is connected):
list_indexes({ db_name: "<db>", collection_name: "<coll>" })
optimize_find_query({
db_name: "<db>",
collection_name: "<coll>",
query: <filter>,
options: { sort: <sort>, projection: <projection>, limit: <n> }
})
For aggregation pipelines:
explain_aggregate_query({
db_name: "<db>",
collection_name: "<coll>",
pipeline: <pipeline_array>
})
From the optimize_find_query / explain_aggregate_query response, extract:
totalKeysExamined, totalDocsExamined, nReturned,
executionTimeMillisKey ratios to evaluate:
| Metric | Good | Bad |
|---|---|---|
| keysExamined / nReturned | Close to 1 | >> 1 (poor selectivity) |
| docsExamined / nReturned | Close to 1 | >> 1 (scanning too many docs) |
| Plan stage | IXSCAN | COLLSCAN (no index) |
| Sort stage | In-memory: false | In-memory: true (blocking sort) |
Common issues and their root causes:
Follow the ESR Rule (Equality → Sort → Range) for compound index design:
$eq / exact match)sort specification)$gt, $lt, $gte, $lte, $in)Example:
Query: db.orders.find({status: 'shipped', region: 'US'}).sort({date: -1})
Recommended index: {status: 1, region: 1, date: -1}
(Two equality fields, then sort field)
After creating the recommended index, re-run the explain to confirm improvement:
optimize_find_query with the same queryUser: "Why is this query slow?
db.orders.find({status: 'shipped', region: 'US'}).sort({date: -1})"
If MCP connection is available, run steps 1–3:
Check existing indexes:
list_indexes with database=store, collection=orders{_id: 1}, {status: 1}, {date: -1}Run explain:
optimize_find_query with query={status: 'shipped', region: 'US'},
options={sort: {date: -1}}{status: 1} index, then in-memory SORT,
totalKeysExamined: 50000, nReturned: 100Fetch sample:
find_documents with limit=1 to understand the schemaDiagnose: This query targets 100 docs but scans 50K index entries (poor
selectivity: 0.002). In-memory sort adds overhead. The {status: 1} index
doesn't support both filter fields or sort.
Recommend: Create compound index {status: 1, region: 1, date: -1}
following ESR (two equality fields, then sort). This eliminates in-memory
sort and improves selectivity.
_id indexnpx claudepluginhub azure/documentdb-agent-kit --plugin documentdbProvides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.