explain
Read-only
Analyze MongoDB query execution plans to understand how the database processes find, aggregate, or count operations and identify optimization opportunities.
Instructions
Returns statistics describing the execution of the winning plan chosen by the query optimizer for the evaluated method
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| database | Yes | Database name | |
| collection | Yes | Collection name | |
| method | Yes | The method and its arguments to run | |
| verbosity | No | The verbosity of the explain plan, defaults to queryPlanner. If the user wants to know how fast is a query in execution time, use executionStats. It supports all verbosities as defined in the MongoDB Driver. | queryPlanner |
Implementation Reference
- The handler function that executes the 'explain' tool. It supports explaining 'aggregate', 'find', and 'count' operations with specified verbosity and returns formatted execution plan information.
protected async execute({ database, collection, method: methods, verbosity, }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> { const provider = await this.ensureConnected(); const method = methods[0]; if (!method) { throw new Error("No method provided. Expected one of the following: `aggregate`, `find`, or `count`"); } let result: Document; switch (method.name) { case "aggregate": { const { pipeline } = method.arguments; result = await provider .aggregate( database, collection, pipeline, {}, { writeConcern: undefined, } ) .explain(verbosity); break; } case "find": { const { filter, ...rest } = method.arguments; result = await provider.find(database, collection, filter as Document, { ...rest }).explain(verbosity); break; } case "count": { const { query } = method.arguments; result = await provider.runCommandWithCheck(database, { explain: { count: collection, query, }, verbosity, }); break; } } return { content: formatUntrustedData( `Here is some information about the winning plan chosen by the query optimizer for running the given \`${method.name}\` operation in "${database}.${collection}". The execution plan was run with the following verbosity: "${verbosity}". This information can be used to understand how the query was executed and to optimize the query performance.`, JSON.stringify(result) ), }; } - Zod schema defining the input shape for the 'explain' tool, including database/collection operations and verbosity.
protected argsShape = { ...DbOperationArgs, method: z .array( z.discriminatedUnion("name", [ z.object({ name: z.literal("aggregate"), arguments: z.object(getAggregateArgs(this.isFeatureEnabled("search"))), }), z.object({ name: z.literal("find"), arguments: z.object(FindArgs), }), z.object({ name: z.literal("count"), arguments: z.object(CountArgs), }), ]) ) .describe("The method and its arguments to run"), verbosity: z .enum(["queryPlanner", "queryPlannerExtended", "executionStats", "allPlansExecution"]) .optional() .default("queryPlanner") .describe( "The verbosity of the explain plan, defaults to queryPlanner. If the user wants to know how fast is a query in execution time, use executionStats. It supports all verbosities as defined in the MongoDB Driver." ), }; - src/tools/index.ts:7-11 (registration)Central registration of all tools, including MongoDB tools (MongoDbTools) which provide the ExplainTool.
export const AllTools: ToolClass[] = Object.values({ ...MongoDbTools, ...AtlasTools, ...AtlasLocalTools, }); - src/tools/mongodb/tools.ts:18-18 (registration)Export of the ExplainTool class for inclusion in MongoDB tools module.
export { ExplainTool } from "./metadata/explain.js"; - Class definition with tool name 'explain'.
export class ExplainTool extends MongoDBToolBase { public name = "explain";