chore: improvements on documentation

Author: kmruiz

src/tools/mongodb/read/aggregate.ts

@@ -26,7 +26,7 @@ const VectorSearchStage = z.object({
                 .describe(
                     "When true, uses an ENN algorithm, otherwise uses ANN. Using ENN is not compatible with numCandidates, in that case, numCandidates must be left empty."
                 ),
-            index: z.string().describe("Name of the index, as retrieved from the collection-indexes tool."),
+            index: z.string().describe("Name of the index, as retrieved from the `collection-indexes` tool."),
             path: z
                 .string()
                 .describe(
@@ -35,18 +35,20 @@ const VectorSearchStage = z.object({
             queryVector: z
                 .union([z.string(), z.array(z.number())])
                 .describe(
-                    "The content to search for. If a string, the embeddingModel is mandatory, if not, the embeddingModel is ignored."
+                    "The content to search for. The embeddingParameters field is mandatory if the queryVector is a string."
                 ),
             numCandidates: z
                 .number()
                 .int()
                 .positive()
                 .optional()
-                .describe("Number of candidates for the ANN algorithm. Only valid when exact is false."),
+                .describe("Number of candidates for the ANN algorithm. Mandatory when exact is false."),
             limit: z.number().int().positive().optional().default(10),
             filter: zEJSON()
                 .optional()
-                .describe("MQL filter that can only use pre-filter fields from the index definition."),
+                .describe(
+                    "MQL filter that can only use pre-filter fields from the index definition. Note to LLM: If unsure, use the `collection-indexes` tool to learn which fields can be used for pre-filtering."
+                ),
             embeddingParameters: zSupportedEmbeddingParameters
                 .optional()
                 .describe(
@@ -252,9 +254,9 @@ export class AggregateTool extends MongoDBToolBase {
                     inputType: "query",
                 });
 
-                // $vectorSearch.queryVector can be a BSON.Binary, which is neither a number nor an array.
-                // It's not exactly valid from the LLM perspective. That's why we overwrite the
-                // stage in an untyped way, as what we expose and what we can use are different.
+                // $vectorSearch.queryVector can be a BSON.Binary: that it's not either number or an array.
+                // It's not exactly valid from the LLM perspective (they can't provide binaries).
+                // That's why we overwrite the stage in an untyped way, as what we expose and what LLMs can use is different.
                 vectorSearchStage.queryVector = embeddings as number[];
             }
         }