Skip to content

improve: enhance tool descriptions for better LLM agent tool selection #37

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
spidershield-contrib wants to merge 2 commits into
base: main
Choose a base branch
from
Open

improve: enhance tool descriptions for better LLM agent tool selection #37

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
185d8eb
improve: enhance tool descriptions for better LLM agent tool selection
spidershield-contrib Mar 14, 2026
f435335
fix: complete missing parameters in tool descriptions and use templat…
spidershield-contrib Mar 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 45 additions & 8 deletions src/schemas/tools.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,11 @@ export async function handleListToolsRequest({
{
name: "query",
description:
"Execute a MongoDB query with optional execution plan analysis",
"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.",
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

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.`,

inputSchema: {
type: "object",
properties: {
Expand Down Expand Up @@ -57,7 +61,11 @@ export async function handleListToolsRequest({
{
name: "aggregate",
description:
"Execute a MongoDB aggregation pipeline with optional execution plan analysis",
"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.",
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

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.`,

inputSchema: {
type: "object",
properties: {
Expand Down Expand Up @@ -91,7 +99,12 @@ export async function handleListToolsRequest({
},
{
name: "update",
description: "Update documents in a MongoDB collection",
description:
"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.",
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

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.`,

inputSchema: {
type: "object",
properties: {
Expand Down Expand Up @@ -131,7 +144,11 @@ export async function handleListToolsRequest({
{
name: "serverInfo",
description:
"Get MongoDB server information including version, storage engine, and other details",
"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.",
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.`,

inputSchema: {
type: "object",
properties: {
Expand All @@ -145,7 +162,12 @@ export async function handleListToolsRequest({
},
{
name: "insert",
description: "Insert one or more documents into a MongoDB collection",
description:
"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.",
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

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.`,

inputSchema: {
type: "object",
properties: {
Expand Down Expand Up @@ -183,7 +205,12 @@ export async function handleListToolsRequest({
},
{
name: "createIndex",
description: "Create one or more indexes on a MongoDB collection",
description:
"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.",
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

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.`,

inputSchema: {
type: "object",
properties: {
Expand Down Expand Up @@ -249,7 +276,12 @@ export async function handleListToolsRequest({
},
{
name: "count",
description: "Count documents in a collection matching a query",
description:
"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.",
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

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.`,

inputSchema: {
type: "object",
properties: {
Expand Down Expand Up @@ -279,7 +311,12 @@ export async function handleListToolsRequest({
},
{
name: "listCollections",
description: "List all collections in the MongoDB database",
description:
"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.",
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

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.`,

inputSchema: {
type: "object",
properties: {
Expand Down