feat(explain): Add support for custom verbosity to the explain plan tool

[kmruiz]

Proposed changes

While queryPlanner is a good default, there are scenarios where we need more verbose outputs to understand why a query is not acting as expected. For example, executionStats can be useful to see rw locks, disk usage and flow throttling.

I'm not sure how good are models understanding the whole executionPlan, and maybe we need to remove information that might not be relevant for debugging to reduce the context usage, but this is a decent first approach and we can improve later.

This implements the feature request from #527

Checklist

• I have signed the MongoDB CLA

[Copilot]

Pull Request Overview

Adds support for custom verbosity levels to the MongoDB explain plan tool, allowing users to request different levels of detail in query execution plans. The default verbosity remains "queryPlanner" but users can now specify "executionStats" or other verbosity levels for more detailed performance analysis.

Key Changes

• Added a new optional verbosity parameter to the explain tool with support for all MongoDB verbosity levels
• Updated tool description and response messages to include verbosity information
• Enhanced test coverage to verify both default and custom verbosity behaviors

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/tools/mongodb/metadata/explain.ts	Added verbosity parameter with enum validation, removed static default constant, and integrated verbosity into explain operations
tests/integration/tools/mongodb/metadata/explain.test.ts	Added comprehensive test cases for different verbosity levels and updated existing tests to verify verbosity-specific behavior

Comments suppressed due to low confidence (1)

src/tools/mongodb/metadata/explain.ts:1

• The import for ExplainVerbosity from mongodb is removed but the enum values in the Zod schema should be validated against the actual MongoDB driver constants to ensure they remain in sync. Consider importing and using ExplainVerbosity enum values instead of hardcoded strings.

import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";

[github-actions]

📊 Accuracy Test Results

📈 Summary

Metric	Value
Commit SHA	19d559bdaefb2bd6378aac6d6b5be4785e4e71b3
Run ID	c767df24-8880-4cb7-ac5c-2340f136b0eb
Status	done
Total Prompts Evaluated	60
Models Tested	1
Average Accuracy	92.1%
Responses with 0% Accuracy	4
Responses with 75% Accuracy	3
Responses with 100% Accuracy	53

📊 Baseline Comparison

Metric	Value
Baseline Commit	d1d26e6baafb3a1b40407c477e3af7da2b5c0fa5
Baseline Run ID	0bb210c9-043c-4da3-a60f-06a572d851cf
Baseline Run Status	done
Responses Improved	2
Responses Regressed	5

---

📎 Download Full HTML Report - Look for the accuracy-test-summary artifact for detailed results.

Report generated on: 9/19/2025, 12:07:02 PM