Skip to content

Update HTTP/MCP descriptions and examples. #2604

Open
1 of 1 issue completed
Open

Description

@Hazel-Datastax

What to do

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

    @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](
      @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:
    • OpenAPI. findAndRerank is missing from the request body list; add it with examples ([CollectionResource.java#L127-L147](
      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

  1. self-assigned this
    on Oct 6, 2026
  2. erichare commented on Nov 19, 2026

    @erichare
    Contributor

    Two tool schemas still describe an argument incorrectly after #2658. Both are from tools/list on 3467041f7.

    createTable lists accessOrder, loadFactor, and threshold as the properties of definition.columns. Those are fields of LinkedHashMap, which ColumnsDescContainer extends. The description text is correct, but the generated properties tell a model to send those three fields instead of column names.

    "columns": {"type": "object", "properties": {"accessOrder": {"type": "boolean"}, "loadFactor": {"type": "number"}, "threshold": {"type": "integer"}}}

    createIndex types definition.column as an object with columnName and mapComponent. 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions