Repository navigation
Description
What to do
-
The problem today. The MCP tool input schema is generated from Java fields ([CollectionCommandTools.java#L151-L164](
), [McpSchemaDescriptionCustomizer.java](https://github.com/stargate/data-api/blob/02d0423347cb2c382c9b7535903a54d2c5e143f6/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpSchemaDescriptionCustomizer.java)). Fordata-api/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/CollectionCommandTools.java
Lines 151 to 164 in 02d0423
@Tool( description = "Finds documents using using vector and lexical sorting, then reranks the results.") public Uni<ToolResponse> findAndRerank( @ToolArg(description = "Name of the keyspace") String keyspace, @ToolArg(description = "Name of the collection/table") String collection, @ToolArg(description = "filter", required = false) FilterDefinition filter, @ToolArg(description = "projection", required = false) JsonNode projection, @ToolArg(description = "sort", required = false) FindAndRerankSort sort, @ToolArg(description = "options", required = false) FindAndRerankCommand.Options options) { var command = new FindAndRerankCommand(filter, projection, sort, options); return mcpResource.processCollectionCommand(keyspace, collection, command); } findAndRerank:sortis advertised as the internal fields{vectorizeSort, lexicalSort, vectorSort, commandFeatures};optionsshowsrerankServiceOverride, but the JSON name isrerank;hybridLimitsshows{vectorLimit, lexicalLimit, commandFeatures}.
An agent that follows this schema sends requests that fail.
-
Part 1: fix schema generation. It has no dependencies, so it is good for gaps between reviews.
- Use the
@JsonPropertynames, and hideCommandFeatures. - Write the definitions by hand for types with custom deserializers:
FindAndRerankSort,HybridLimits,SortDefinitionandFilterDefinition. - Add a contract test: every schema example must parse with the real deserializer.
- Use the
-
Part 2: the text that agents and users read. Do this after Single-leg retrieval and Filter retrieval are done.
- Tool and argument descriptions. Today the tool says "Finds documents using using vector and lexical sorting, then reranks the results.", and the arguments are described only as "sort" and "options".
@Schemadescriptions and examples. Today's examples cover$hybridonly, and they are malformed: wrapped in a$sortkey, with an extra brace ([FindAndRerankSort.java#L21-L29]()).data-api/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/sort/FindAndRerankSort.java
Lines 21 to 29 in 02d0423
@Schema( type = SchemaType.OBJECT, implementation = Map.class, examples = """ {"$sort" : {"$hybrid" : "Same query for vectorize and bm25 sorting"}}} {"$sort" : {"$hybrid" : {"$vectorize" : "vectorize sort query" , "$lexical": "lexical sort" }}} {"$sort" : {"$hybrid" : {"$vector" : [1,2,3] , "$lexical": "lexical sort" }}} """) - Error messages:
MISSING_RERANK_ONandMISSING_RERANK_QUERY_TEXTonly describe$hybrid([errors.yaml#L286](), [#L304](data-api/src/main/resources/errors.yaml
Line 286 in 02d0423
code: MISSING_RERANK_ON ));data-api/src/main/resources/errors.yaml
Line 304 in 02d0423
code: MISSING_RERANK_QUERY_TEXT UNSUPPORTED_RERANKING_COMMANDsays vector, lexical and rerank must all be configured, which is no longer true once the filter leg exists ([errors.yaml#L265]()).data-api/src/main/resources/errors.yaml
Line 265 in 02d0423
code: UNSUPPORTED_RERANKING_COMMAND
- OpenAPI.
findAndRerankis missing from the request body list; add it with examples ([CollectionResource.java#L127-L147]()).data-api/src/main/java/io/stargate/sgv2/jsonapi/api/v1/CollectionResource.java
Lines 127 to 147 in 02d0423
anyOf = { CountDocumentsCommand.class, DeleteOneCommand.class, DeleteManyCommand.class, FindOneCommand.class, FindCommand.class, FindOneAndDeleteCommand.class, FindOneAndReplaceCommand.class, FindOneAndUpdateCommand.class, EstimatedDocumentCountCommand.class, InsertOneCommand.class, InsertManyCommand.class, UpdateManyCommand.class, UpdateOneCommand.class, // Table Only commands AlterTableCommand.class, CreateIndexCommand.class, CreateTextIndexCommand.class, CreateVectorIndexCommand.class, ListIndexesCommand.class }), - MCP ITs for single-leg and filter tool calls.
Status on November 19, 2026
PR #2619 merged the clause schemas, #2651 merged the update syntax, and #2658 merged the argument descriptions. The remaining tool descriptions, schema examples, error messages, and OpenAPI entry depend on single-leg and filter retrieval.
One test follow-up remains from #2658. The description check lowercases only the description. A bare camel-case argument name such as indexName can pass. Compare both strings without regard to case when checking for name-only descriptions.
Activity
erichare commentedon Nov 19, 2026
Two tool schemas still describe an argument incorrectly after #2658. Both are from
tools/liston3467041f7.createTablelistsaccessOrder,loadFactor, andthresholdas the properties ofdefinition.columns. Those are fields ofLinkedHashMap, whichColumnsDescContainerextends. The description text is correct, but the generated properties tell a model to send those three fields instead of column names.createIndextypesdefinition.columnas an object withcolumnNameandmapComponent. The command accepts a plain column name, and{"column": "age"}created the index in my run. The schema should allow the string form, which is the common case.