Output schemas completely undocumented. No tool in the 42-tool suite documents what fields/structure it returns. LLMs cannot predict downstream data availability or plan tool chains.
connectswitch-connectionlist-collectionslist-databasesfindaggregateexportall Atlas and Atlas Local tools
Destructive operations (drop-database, drop-collection, delete-many) lack error recovery guidance and confirmation-before-execute patterns. Descriptions do not warn of irreversibility or suggest recovery steps.
Complex query/filter parameters (find, aggregate, update-many) have minimal schema guidance. Descriptions say 'Find documents' but don't explain expected query format (MongoDB BSON query syntax), required nesting, or common errors.
findaggregate
Recommendations
Document the complete output schema for every tool. For find, return: {documents: [{_id, ...fields}], count, limit, offset, hasMore}. For list-collections, return: {collections: [{name, type, stats}, ...], total, limit}. Use this to guide LLM understanding of downstream data availability.
Add explicit confirmation-before-execute pattern to drop-database, drop-collection, delete-many, delete-deployment. Descriptions should say: 'DESTRUCTIVE: permanently removes data. Agent must call confirm_drop_database({database, confirmationCode}) before executing. Return error if code does not match hash(database_name).ʼ
For complex query parameters (find.filter, aggregate.pipeline, update-many.filter, create-index.keys), add schema examples in descriptions: 'filter: MongoDB query syntax, e.g. {status: "active", age: {$gte: 18}}ʼ. Reference MongoDB query documentation or provide 2-3 realistic examples per tool.
Expand parameter descriptions to cover: (1) expected data type/format, (2) constraints (enum values, ranges, patterns), (3) dependencies on other parameters, (4) examples. E.g., 'collection: string, name of target collection in the connected database. Must exist or call create-collection first. Example: "users".ʼ
Add error recovery guidance to descriptions of mutating tools. Example for delete-many: 'Deletes documents matching filter. If network fails mid-operation, retry is safe, MongoDB is idempotent. If filter is wrong, no undo available, use database backup or call insert-many to restore deleted records.'
Parameter descriptions missing or extremely sparse across multiple tools. Visible schemas show database and collection params with descriptions, but many optional/complex params lack guidance (filter, pipeline, options, etc.).
No error classification or recovery guidance. Tools like delete-many, drop-database do not explain how retries work, what errors are retryable vs. fatal, or how to undo accidental operations.
No pagination support documented for list-* tools. list-collections, list-databases, list-clusters, list-projects, list-db-users, list-deployments, list-alerts, list-organizations all lack visible limit/offset/cursor parameters or documentation of result limits.
Schema documents visible for only ~50% of tools (mostly Atlas/Atlas Local tools). Many core MongoDB tools (connect, switch-connection, list-databases, logs, list-clusters, create-project, etc.) show no input schema at all, making validation and LLM planning impossible.
Split or clarify overlapping tools: find returns raw documents, aggregate runs a pipeline. Update descriptions: 'find: returns matching documents as-is; aggregate: applies transformation pipeline (group, project, match stages) and returns aggregated results. Use aggregate for analytics; find for simple retrieval.'
Add pagination to all list-* tools. Visible schemas should show limit (default 20, max 100), offset/cursor, and return {items: [...], total, hasMore, nextCursor}. Document in description: 'Returns up to 20 items. Pass nextCursor to fetch more.'
For tools with missing schemas (connect, logs, search-knowledge, etc.), add explicit input schemas: {type: 'object', properties: {...}, required: [...]}. Even minimal schemas (no parameters required) help LLMs understand invocation.
Add tool annotations to the MCP registration for each tool: readonly operations (find, list-*, describe-*, get-*) should include readOnlyHint=true; destructive operations (drop-*, delete-many) should include destructiveHint=true; idempotent operations (create-*, describe-*) should include idempotentHint=true. This guides agent safety reasoning.
Create a discovery/help tool: 'describe_tool(tool_name)' returns human-friendly descriptions of what each tool does, when to use it, and example calls. This lets agents self-serve when uncertain about tool choice.