Update HTTP/MCP descriptions and examples. #2604

What to do

• The problem today. The MCP tool input schema is generated from Java fields ([CollectionCommandTools.java#L151-L164](

  data-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);
  	}

  ), [McpSchemaDescriptionCustomizer.java](https://github.com/stargate/data-api/blob/02d0423347cb2c382c9b7535903a54d2c5e143f6/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpSchemaDescriptionCustomizer.java)). For findAndRerank:
  • sort is advertised as the internal fields {vectorizeSort, lexicalSort, vectorSort, commandFeatures};
  • options shows rerankServiceOverride, but the JSON name is rerank;
  • hybridLimits shows {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 @JsonProperty names, and hide CommandFeatures.
  • Write the definitions by hand for types with custom deserializers: FindAndRerankSort, HybridLimits, SortDefinition and FilterDefinition.
  • Add a contract test: every schema example must parse with the real deserializer.

• 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".
  • @Schema descriptions and examples. Today's examples cover $hybrid only, and they are malformed: wrapped in a $sort key, 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_ON and MISSING_RERANK_QUERY_TEXT only describe $hybrid ([errors.yaml#L286](

      data-api/src/main/resources/errors.yaml

      Line 286 in 02d0423

      code: MISSING_RERANK_ON

      ), [#L304](

      data-api/src/main/resources/errors.yaml

      Line 304 in 02d0423

      code: MISSING_RERANK_QUERY_TEXT

      ));
    • UNSUPPORTED_RERANKING_COMMAND says 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. findAndRerank is 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 October 23, 2026

PR #2619 merged on October 23 with Part 1. The filter, sort, findAndRerank sort, hybrid limits and rerank override schemas now describe the JSON clients send, and contract tests check each schema against the real parser. Update syntax is next in PR #2651 for #2631. PR #2658 starts Part 2. Every MCP tool argument gets a description, and a test parses each example those descriptions carry. The tool descriptions, @Schema examples, error messages and OpenAPI entry still wait on single-leg retrieval in #2602 and on filter retrieval.