improve: enhance tool descriptions for better LLM agent tool selection#37
improve: enhance tool descriptions for better LLM agent tool selection#37spidershield-contrib wants to merge 2 commits intokiliczsh:mainfrom
Conversation
Rewrite all 8 MCP tool descriptions using an action-verb-first format designed for LLM agent planning. Each description now includes: - What the tool does (action verb lead) - When to use it (concrete scenarios) - When NOT to use it (disambiguation with sibling tools) - Key parameters with examples - Error conditions This helps LLM agents select the correct tool on the first attempt, reducing tool selection errors in multi-step database workflows.
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the clarity and utility of MongoDB tool descriptions for LLM agents. By adopting a structured, action-verb-first format with detailed usage guidelines, the changes aim to minimize tool selection errors and improve the overall planning capabilities of AI systems interacting with MongoDB. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly improves the tool descriptions to aid LLM agent planning. The new detailed format is a great enhancement. My review focuses on ensuring the descriptions are complete and consistent. I've found that several tool descriptions are missing some of their available parameters, which could limit the LLM's ability to use them effectively. I've also suggested using template literals for multi-line strings to improve code readability and maintainability.
src/schemas/tools.ts
Outdated
| "Execute a MongoDB find query to retrieve documents from a collection, with optional execution plan analysis.\n\n" + | ||
| "Use when the user wants to read, search, or filter documents in a specific collection.\n" + | ||
| "Do not use when you need to perform multi-stage data transformations (use aggregate instead) or when you want to modify data (use update or insert instead).\n" + | ||
| "Accepts 'collection' (required), 'filter' (optional query object), 'projection' (optional field selection), 'limit' (optional, default 10), and 'explain' (optional, for query plan analysis).\n" + | ||
| "Raises an error if the collection does not exist or the filter syntax is invalid.", |
There was a problem hiding this comment.
The tool description is missing the objectIdMode parameter in the Accepts section. For the LLM to be aware of all available parameters, it's important to list them all.
Additionally, for better readability and maintainability, I suggest using a template literal for the multi-line description string instead of string concatenation.
`Execute a MongoDB find query to retrieve documents from a collection, with optional execution plan analysis.
Use when the user wants to read, search, or filter documents in a specific collection.
Do not use when you need to perform multi-stage data transformations (use aggregate instead) or when you want to modify data (use update or insert instead).
Accepts 'collection' (required), 'filter' (optional query object), 'projection' (optional field selection), 'limit' (optional, default 10), 'explain' (optional, for query plan analysis), and 'objectIdMode' (optional, default 'auto').
Raises an error if the collection does not exist or the filter syntax is invalid.`,
src/schemas/tools.ts
Outdated
| "Execute a MongoDB aggregation pipeline to perform multi-stage data transformations, grouping, joins, or analytics.\n\n" + | ||
| "Use when the user needs $group, $lookup, $unwind, $match chains, or any computation that goes beyond simple filtering.\n" + | ||
| "Do not use when a simple find query with filter and projection is sufficient (use query instead).\n" + | ||
| "Accepts 'collection' (required), 'pipeline' (required, array of stage objects), and 'explain' (optional, for execution plan analysis).\n" + | ||
| "Raises an error if the pipeline syntax is invalid or a stage operator is unrecognized.", |
There was a problem hiding this comment.
The tool description is missing the objectIdMode parameter in the Accepts section. For the LLM to be aware of all available parameters, it's important to list them all.
Additionally, for better readability and maintainability, I suggest using a template literal for the multi-line description string instead of string concatenation.
`Execute a MongoDB aggregation pipeline to perform multi-stage data transformations, grouping, joins, or analytics.
Use when the user needs $group, $lookup, $unwind, $match chains, or any computation that goes beyond simple filtering.
Do not use when a simple find query with filter and projection is sufficient (use query instead).
Accepts 'collection' (required), 'pipeline' (required, array of stage objects), 'explain' (optional, for execution plan analysis), and 'objectIdMode' (optional, default 'auto').
Raises an error if the pipeline syntax is invalid or a stage operator is unrecognized.`,
src/schemas/tools.ts
Outdated
| "Update one or more documents in a MongoDB collection using update operators ($set, $unset, $inc, etc.).\n\n" + | ||
| "Use when the user wants to modify existing documents — change field values, increment counters, or remove fields.\n" + | ||
| "Do not use when you need to add new documents (use insert instead) or when you need to read data (use query instead).\n" + | ||
| "Accepts 'collection' (required), 'filter' (required), 'update' (required, update operators), 'upsert' (optional), and 'multi' (optional, for updating multiple documents).\n" + | ||
| "Raises an error if the filter or update syntax is invalid.", |
There was a problem hiding this comment.
The tool description is missing the objectIdMode parameter in the Accepts section. For the LLM to be aware of all available parameters, it's important to list them all.
Additionally, for better readability and maintainability, I suggest using a template literal for the multi-line description string instead of string concatenation.
`Update one or more documents in a MongoDB collection using update operators ($set, $unset, $inc, etc.).
Use when the user wants to modify existing documents — change field values, increment counters, or remove fields.
Do not use when you need to add new documents (use insert instead) or when you need to read data (use query instead).
Accepts 'collection' (required), 'filter' (required), 'update' (required, update operators), 'upsert' (optional), 'multi' (optional, for updating multiple documents), and 'objectIdMode' (optional, default 'auto').
Raises an error if the filter or update syntax is invalid.`,
src/schemas/tools.ts
Outdated
| "Insert one or more new documents into a MongoDB collection.\n\n" + | ||
| "Use when the user wants to add new records, seed data, or create documents in a collection.\n" + | ||
| "Do not use when you need to modify existing documents (use update instead) or when you need to read data (use query instead).\n" + | ||
| "Accepts 'collection' (required), 'documents' (required, array of document objects), 'ordered' (optional), and 'writeConcern' (optional).\n" + | ||
| "Raises an error if the collection name is invalid or document validation fails.", |
There was a problem hiding this comment.
The tool description is missing the bypassDocumentValidation and objectIdMode parameters in the Accepts section. For the LLM to be aware of all available parameters, it's important to list them all.
Additionally, for better readability and maintainability, I suggest using a template literal for the multi-line description string instead of string concatenation.
`Insert one or more new documents into a MongoDB collection.
Use when the user wants to add new records, seed data, or create documents in a collection.
Do not use when you need to modify existing documents (use update instead) or when you need to read data (use query instead).
Accepts 'collection' (required), 'documents' (required, array of document objects), 'ordered' (optional), 'writeConcern' (optional), 'bypassDocumentValidation' (optional), and 'objectIdMode' (optional, default 'auto').
Raises an error if the collection name is invalid or document validation fails.`,
src/schemas/tools.ts
Outdated
| "Create one or more indexes on a MongoDB collection to improve query performance.\n\n" + | ||
| "Use when the user wants to add indexes for frequently queried fields, enforce uniqueness, or set up TTL expiration on documents.\n" + | ||
| "Do not use when you need to query or modify data (use query, update, or insert instead).\n" + | ||
| "Accepts 'collection' (required) and 'indexes' (required, array of index specs with key patterns). Each index supports options like 'unique', 'sparse', 'expireAfterSeconds', and 'partialFilterExpression'.\n" + | ||
| "Raises an error if the index key pattern is invalid or the collection does not exist.", |
There was a problem hiding this comment.
The tool description is missing the writeConcern, commitQuorum, and objectIdMode parameters in the Accepts section. The description of options for index specs is also incomplete. For the LLM to be aware of all available parameters, it's important to list them all.
Additionally, for better readability and maintainability, I suggest using a template literal for the multi-line description string instead of string concatenation.
`Create one or more indexes on a MongoDB collection to improve query performance.
Use when the user wants to add indexes for frequently queried fields, enforce uniqueness, or set up TTL expiration on documents.
Do not use when you need to query or modify data (use query, update, or insert instead).
Accepts 'collection' (required), 'indexes' (required, array of index specs), 'writeConcern' (optional), 'commitQuorum' (optional), and 'objectIdMode' (optional, default 'auto'). Each index spec requires a 'key' and supports options like 'name', 'unique', 'sparse', 'background', 'expireAfterSeconds', and 'partialFilterExpression'.
Raises an error if the index key pattern is invalid or the collection does not exist.`,
src/schemas/tools.ts
Outdated
| "Count the number of documents in a collection that match a query filter.\n\n" + | ||
| "Use when the user wants to know how many documents exist, check if data is present, or get collection statistics.\n" + | ||
| "Do not use when you need to retrieve the actual documents (use query instead) or perform aggregation counts with grouping (use aggregate instead).\n" + | ||
| "Accepts 'collection' (required), 'query' (optional filter), 'limit' (optional max count), and 'skip' (optional docs to skip).\n" + | ||
| "Raises an error if the collection does not exist or the query filter is invalid.", |
There was a problem hiding this comment.
The tool description is missing several parameters in the Accepts section: hint, readConcern, maxTimeMS, collation, and objectIdMode. For the LLM to be aware of all available parameters, it's important to list them all.
Additionally, for better readability and maintainability, I suggest using a template literal for the multi-line description string instead of string concatenation.
`Count the number of documents in a collection that match a query filter.
Use when the user wants to know how many documents exist, check if data is present, or get collection statistics.
Do not use when you need to retrieve the actual documents (use query instead) or perform aggregation counts with grouping (use aggregate instead).
Accepts 'collection' (required), 'query' (optional filter), 'limit' (optional max count), 'skip' (optional docs to skip), 'hint' (optional), 'readConcern' (optional), 'maxTimeMS' (optional), 'collation' (optional), and 'objectIdMode' (optional, default 'auto').
Raises an error if the collection does not exist or the query filter is invalid.`,
src/schemas/tools.ts
Outdated
| "List all collections in the connected MongoDB database.\n\n" + | ||
| "Use when the user wants to explore available collections before querying, or to verify a collection exists.\n" + | ||
| "Do not use when you already know the collection name and need to query its documents (use query instead).\n" + | ||
| "Accepts 'nameOnly' (optional boolean, returns only collection names for a compact listing) and 'filter' (optional, to filter collections by properties).\n" + | ||
| "Raises an error if the database connection is unavailable.", |
There was a problem hiding this comment.
The tool description is missing the objectIdMode parameter in the Accepts section. For the LLM to be aware of all available parameters, it's important to list them all.
Additionally, for better readability and maintainability, I suggest using a template literal for the multi-line description string instead of string concatenation.
`List all collections in the connected MongoDB database.
Use when the user wants to explore available collections before querying, or to verify a collection exists.
Do not use when you already know the collection name and need to query its documents (use query instead).
Accepts 'nameOnly' (optional boolean, returns only collection names for a compact listing), 'filter' (optional, to filter collections by properties), and 'objectIdMode' (optional, default 'auto').
Raises an error if the database connection is unavailable.`,
src/schemas/tools.ts
Outdated
| "Retrieve MongoDB server metadata including version, storage engine, host, and uptime.\n\n" + | ||
| "Use when the user wants to check the database server version, verify the storage engine, or diagnose server-level configuration.\n" + | ||
| "Do not use when you need to list collections (use listCollections instead) or query data (use query instead).\n" + | ||
| "Accepts 'includeDebugInfo' (optional boolean, includes additional diagnostic details).\n" + | ||
| "Raises an error if the server is unreachable.", |
There was a problem hiding this comment.
For consistency with other descriptions and for better readability, I suggest using a template literal for this multi-line description string instead of string concatenation.
`Retrieve MongoDB server metadata including version, storage engine, host, and uptime.
Use when the user wants to check the database server version, verify the storage engine, or diagnose server-level configuration.
Do not use when you need to list collections (use listCollections instead) or query data (use query instead).
Accepts 'includeDebugInfo' (optional boolean, includes additional diagnostic details).
Raises an error if the server is unreachable.`,…e literals Address code review feedback from Gemini Code Assist: - Add missing 'objectIdMode' parameter to all 7 tool descriptions - Add missing 'bypassDocumentValidation' to insert description - Add missing 'writeConcern', 'commitQuorum' to createIndex description - Add missing 'hint', 'readConcern', 'maxTimeMS', 'collation' to count description - Add missing 'filter' to listCollections description - Convert all descriptions from string concatenation to template literals
1 participant
What
Rewrote all 8 MCP tool descriptions using an action-verb-first format designed for LLM agent planning.
Why
MCP tool descriptions serve as planning hints — LLMs use them to select which tool to call and in what order. The current single-sentence descriptions (e.g., "Update documents in a MongoDB collection") don't help LLMs distinguish between query vs. aggregate, or update vs. insert, leading to tool selection errors.
Format applied
Each description now includes:
Example: query (before → after)
Before:
After:
Scope
src/schemas/tools.ts)npm run build✓), lint verified (npm run lint✓)🤖 Descriptions improved with spidershield — open-source MCP security & quality scanner.