diff --git a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/impl/FindEmbeddingProvidersCommand.java b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/impl/FindEmbeddingProvidersCommand.java
index 974574e154..d7df3ba304 100644
--- a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/impl/FindEmbeddingProvidersCommand.java
+++ b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/impl/FindEmbeddingProvidersCommand.java
@@ -20,7 +20,7 @@ public record Options(
@Nullable
@Schema(
description =
- "Optional filter to select models by required support status. If omitted, only SUPPORTED models are returned (ones which can be used when creating a new Collection or Table). Available values are SUPPORTED, DEPRECATED, and END_OF_LIFE (case-insensitive).",
+ "Optional filter to select models by required support status. If omitted, only SUPPORTED models are returned (ones which can be used when creating a new Collection or Table). Available values are SUPPORTED, DEPRECATED, and END_OF_LIFE (case-insensitive). Set to null or an empty string to return all models.",
type = SchemaType.STRING,
implementation = String.class)
@Pattern(regexp = "(?i)^(SUPPORTED|DEPRECATED|END_OF_LIFE)?$")
diff --git a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/table/definition/TableDefinitionDesc.java b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/table/definition/TableDefinitionDesc.java
index deda07338f..b484e90b51 100644
--- a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/table/definition/TableDefinitionDesc.java
+++ b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/table/definition/TableDefinitionDesc.java
@@ -14,13 +14,17 @@
*
Has the columns and the primary key definition, not the name of the table.
*/
public record TableDefinitionDesc(
- @Schema(description = "API table columns definitions", type = SchemaType.OBJECT)
+ @Schema(
+ description =
+ "Columns of the table, mapping each column name to its type, for example {\"id\": \"text\", \"title\": \"text\"}",
+ type = SchemaType.OBJECT)
@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonProperty(TableDescConstants.TableDefinitionDesc.COLUMNS)
ColumnsDescContainer columns,
@Valid
@Schema(
- description = "Primary key definition for the table",
+ description =
+ "Primary key of the table, either the name of one column or an object with partitionBy and partitionSort",
anyOf = {String.class, PrimaryKeyDesc.class})
@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonProperty(TableDescConstants.TableDefinitionDesc.PRIMARY_KEY)
diff --git a/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/CollectionCommandTools.java b/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/CollectionCommandTools.java
index efb89bf227..fa374343c7 100644
--- a/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/CollectionCommandTools.java
+++ b/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/CollectionCommandTools.java
@@ -22,6 +22,9 @@
* MCP tool provider for collection-level (and table-level) commands {@link
* io.stargate.sgv2.jsonapi.api.model.command.CollectionCommand}. These correspond to the {@link
* io.stargate.sgv2.jsonapi.api.v1.CollectionResource} REST endpoint.
+ *
+ *
The filter and sort arguments have no description here. A {@code @ToolArg} description would
+ * replace the one on their classes, which Swagger also uses.
*/
public class CollectionCommandTools {
@@ -31,7 +34,10 @@ public class CollectionCommandTools {
public Uni alterTable(
@ToolArg(description = "Name of the keyspace") String keyspace,
@ToolArg(description = "Name of the table") String table,
- @ToolArg(description = "The alter table operation") AlterTableOperation operation) {
+ @ToolArg(
+ description =
+ "Alters the schema of a Table, to add or drop columns or configure vectorization, for example {\"add\": {\"columns\": {\"rating\": \"int\"}}}")
+ AlterTableOperation operation) {
var command = new AlterTableCommand(operation);
return mcpResource.processCollectionCommand(keyspace, table, command);
@@ -41,7 +47,7 @@ public Uni alterTable(
public Uni countDocuments(
@ToolArg(description = "Name of the keyspace") String keyspace,
@ToolArg(description = "Name of the collection") String collection,
- @ToolArg(description = "filter", required = false) FilterDefinition filter) {
+ @ToolArg(required = false) FilterDefinition filter) {
var command = new CountDocumentsCommand(filter);
return mcpResource.processCollectionCommand(keyspace, collection, command);
@@ -51,7 +57,7 @@ public Uni countDocuments(
public Uni createIndex(
@ToolArg(description = "Name of the keyspace") String keyspace,
@ToolArg(description = "Name of the table") String table,
- @ToolArg(description = "Name of the new Index") String indexName,
+ @ToolArg(description = "Name of the new index") String indexName,
@ToolArg(description = "Definition of the index to create")
RegularIndexDefinitionDesc definition,
@ToolArg(
@@ -74,7 +80,7 @@ public Uni createIndex(
public Uni createTextIndex(
@ToolArg(description = "Name of the keyspace") String keyspace,
@ToolArg(description = "Name of the table") String table,
- @ToolArg(description = "Name of the new Index") String indexName,
+ @ToolArg(description = "Name of the new index") String indexName,
@ToolArg(description = "Definition of the index to create")
TextIndexDefinitionDesc definition,
@ToolArg(
@@ -95,7 +101,7 @@ public Uni createTextIndex(
public Uni createVectorIndex(
@ToolArg(description = "Name of the keyspace") String keyspace,
@ToolArg(description = "Name of the table") String table,
- @ToolArg(description = "Name of the new Index") String indexName,
+ @ToolArg(description = "Name of the new index") String indexName,
@ToolArg(description = "Definition of the index to create")
VectorIndexDefinitionDesc definition,
@ToolArg(
@@ -117,11 +123,8 @@ public Uni createVectorIndex(
"Command that finds documents based on the filter and deletes them from a collection")
public Uni deleteMany(
@ToolArg(description = "Name of the keyspace") String keyspace,
- @ToolArg(description = "Name of the collection/table") String collection,
- @ToolArg(
- description = "Filter clause based on which documents are identified",
- required = false)
- FilterDefinition filter) {
+ @ToolArg(description = "Name of the collection or table") String collection,
+ @ToolArg(required = false) FilterDefinition filter) {
var command = new DeleteManyCommand(filter);
return mcpResource.processCollectionCommand(keyspace, collection, command);
@@ -130,10 +133,9 @@ public Uni deleteMany(
@Tool(description = "Command that finds a single document and deletes it from a collection")
public Uni deleteOne(
@ToolArg(description = "Name of the keyspace") String keyspace,
- @ToolArg(description = "Name of the collection/table") String collection,
- @ToolArg(description = "Filter clause based on which documents are identified")
- FilterDefinition filter,
- @ToolArg(description = "Sort clause", required = false) SortDefinition sort) {
+ @ToolArg(description = "Name of the collection or table") String collection,
+ @ToolArg FilterDefinition filter,
+ @ToolArg(required = false) SortDefinition sort) {
var command = new DeleteOneCommand(filter, sort);
return mcpResource.processCollectionCommand(keyspace, collection, command);
@@ -152,8 +154,6 @@ public Uni estimatedDocumentCount(
public Uni findAndRerank(
@ToolArg(description = "Name of the keyspace") String keyspace,
@ToolArg(description = "Name of the collection") String collection,
- // filter and sort have no description here because it would replace the one on their
- // classes, which Swagger also uses.
@ToolArg(required = false) FilterDefinition filter,
@ToolArg(
description =
@@ -161,9 +161,7 @@ public Uni findAndRerank(
required = false)
JsonNode projection,
@ToolArg(required = false) FindAndRerankSort sort,
- @ToolArg(
- description = "Options for result limits, reranking, and what the response includes",
- required = false)
+ @ToolArg(description = "Options for the command.", required = false)
FindAndRerankCommand.Options options) {
var command = new FindAndRerankCommand(filter, projection, sort, options);
@@ -173,11 +171,16 @@ public Uni findAndRerank(
@Tool(description = "Command that finds JSON documents from a collection.")
public Uni find(
@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) SortDefinition sort,
- @ToolArg(description = "options", required = false) FindCommand.Options options) {
+ @ToolArg(description = "Name of the collection or table") String collection,
+ @ToolArg(required = false) FilterDefinition filter,
+ @ToolArg(
+ description =
+ "Fields to include or exclude in the returned documents, for example {\"title\": 1}",
+ required = false)
+ JsonNode projection,
+ @ToolArg(required = false) SortDefinition sort,
+ @ToolArg(description = "Options for the command.", required = false)
+ FindCommand.Options options) {
var command = new FindCommand(filter, projection, sort, options);
return mcpResource.processCollectionCommand(keyspace, collection, command);
@@ -188,10 +191,14 @@ public Uni find(
"Command that finds a single JSON document from a collection and deletes it. The deleted document is returned")
public Uni findOneAndDelete(
@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 = "sort", required = false) SortDefinition sort,
- @ToolArg(description = "projection", required = false) JsonNode projection) {
+ @ToolArg(description = "Name of the collection") String collection,
+ @ToolArg(required = false) FilterDefinition filter,
+ @ToolArg(required = false) SortDefinition sort,
+ @ToolArg(
+ description =
+ "Fields to include or exclude in the returned document, for example {\"title\": 1}",
+ required = false)
+ JsonNode projection) {
var command = new FindOneAndDeleteCommand(filter, sort, projection);
return mcpResource.processCollectionCommand(keyspace, collection, command);
@@ -202,12 +209,16 @@ public Uni findOneAndDelete(
"Command that finds a single JSON document from a collection and replaces it with the replacement document.")
public Uni findOneAndReplace(
@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 = "sort", required = false) SortDefinition sort,
- @ToolArg(description = "projection", required = false) JsonNode projection,
- @ToolArg(description = "replacement") ObjectNode replacement,
- @ToolArg(description = "options", required = false)
+ @ToolArg(description = "Name of the collection") String collection,
+ @ToolArg(required = false) FilterDefinition filter,
+ @ToolArg(required = false) SortDefinition sort,
+ @ToolArg(
+ description =
+ "Fields to include or exclude in the returned document, for example {\"title\": 1}",
+ required = false)
+ JsonNode projection,
+ @ToolArg(description = "Document that replaces the matching document") ObjectNode replacement,
+ @ToolArg(description = "Options for the command.", required = false)
FindOneAndReplaceCommand.Options options) {
var command = new FindOneAndReplaceCommand(filter, sort, projection, replacement, options);
@@ -219,12 +230,17 @@ public Uni findOneAndReplace(
"Command that finds a single JSON document from a collection and updates the values provided in the update clause.")
public Uni findOneAndUpdate(
@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) SortDefinition sort,
- @ToolArg(description = "update") UpdateClause update,
- @ToolArg(description = "options", required = false) FindOneAndUpdateCommand.Options options) {
+ @ToolArg(description = "Name of the collection") String collection,
+ @ToolArg(required = false) FilterDefinition filter,
+ @ToolArg(
+ description =
+ "Fields to include or exclude in the returned document, for example {\"title\": 1}",
+ required = false)
+ JsonNode projection,
+ @ToolArg(required = false) SortDefinition sort,
+ @ToolArg UpdateClause update,
+ @ToolArg(description = "Options for the command.", required = false)
+ FindOneAndUpdateCommand.Options options) {
var command = new FindOneAndUpdateCommand(filter, projection, sort, update, options);
return mcpResource.processCollectionCommand(keyspace, collection, command);
@@ -233,11 +249,16 @@ public Uni findOneAndUpdate(
@Tool(description = "Command that finds a single JSON document from a collection.")
public Uni findOne(
@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) SortDefinition sort,
- @ToolArg(description = "options", required = false) FindOneCommand.Options options) {
+ @ToolArg(description = "Name of the collection or table") String collection,
+ @ToolArg(required = false) FilterDefinition filter,
+ @ToolArg(
+ description =
+ "Fields to include or exclude in the returned document, for example {\"title\": 1}",
+ required = false)
+ JsonNode projection,
+ @ToolArg(required = false) SortDefinition sort,
+ @ToolArg(description = "Options for the command.", required = false)
+ FindOneCommand.Options options) {
var command = new FindOneCommand(filter, projection, sort, options);
return mcpResource.processCollectionCommand(keyspace, collection, command);
@@ -247,7 +268,7 @@ public Uni findOne(
public Uni listIndexes(
@ToolArg(description = "Name of the keyspace") String keyspace,
@ToolArg(description = "Name of the table") String table,
- @ToolArg(description = "Options for the `listIndexes` command.", required = false)
+ @ToolArg(description = "Options for the command.", required = false)
ListIndexesCommand.Options options) {
var command = new ListIndexesCommand(options);
@@ -257,9 +278,9 @@ public Uni listIndexes(
@Tool(description = "Command that inserts multiple JSON documents to a collection.")
public Uni insertMany(
@ToolArg(description = "Name of the keyspace") String keyspace,
- @ToolArg(description = "Name of the collection/table") String collection,
- @ToolArg(description = "JSON documents to insert") List documents,
- @ToolArg(description = "Options for inserting many documents", required = false)
+ @ToolArg(description = "Name of the collection or table") String collection,
+ @ToolArg(description = "Documents or rows to insert") List documents,
+ @ToolArg(description = "Options for the command.", required = false)
InsertManyCommand.Options options) {
var command = new InsertManyCommand(documents, options);
@@ -269,8 +290,8 @@ public Uni insertMany(
@Tool(description = "Command that inserts a single JSON document to a collection.")
public Uni insertOne(
@ToolArg(description = "Name of the keyspace") String keyspace,
- @ToolArg(description = "Name of the collection/table") String collection,
- @ToolArg(description = "JSON document to insert") JsonNode document) {
+ @ToolArg(description = "Name of the collection or table") String collection,
+ @ToolArg(description = "Document or row to insert") JsonNode document) {
var command = new InsertOneCommand(document);
return mcpResource.processCollectionCommand(keyspace, collection, command);
@@ -281,10 +302,11 @@ public Uni insertOne(
"Command that finds documents from a collection and updates it with the values provided in the update clause.")
public Uni updateMany(
@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 = "update") UpdateClause update,
- @ToolArg(description = "options", required = false) UpdateManyCommand.Options options) {
+ @ToolArg(description = "Name of the collection") String collection,
+ @ToolArg(required = false) FilterDefinition filter,
+ @ToolArg UpdateClause update,
+ @ToolArg(description = "Options for the command.", required = false)
+ UpdateManyCommand.Options options) {
var command = new UpdateManyCommand(filter, update, options);
return mcpResource.processCollectionCommand(keyspace, collection, command);
@@ -295,11 +317,12 @@ public Uni updateMany(
"Command that finds a single JSON document from a table or collection and updates the values provided in the update clause.")
public Uni updateOne(
@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 = "update") UpdateClause update,
- @ToolArg(description = "sort", required = false) SortDefinition sort,
- @ToolArg(description = "options", required = false) UpdateOneCommand.Options options) {
+ @ToolArg(description = "Name of the collection or table") String collection,
+ @ToolArg(required = false) FilterDefinition filter,
+ @ToolArg UpdateClause update,
+ @ToolArg(required = false) SortDefinition sort,
+ @ToolArg(description = "Options for the command.", required = false)
+ UpdateOneCommand.Options options) {
var command = new UpdateOneCommand(filter, update, sort, options);
return mcpResource.processCollectionCommand(keyspace, collection, command);
diff --git a/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/GeneralCommandTools.java b/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/GeneralCommandTools.java
index aaf01203ea..316545e8d0 100644
--- a/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/GeneralCommandTools.java
+++ b/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/GeneralCommandTools.java
@@ -22,8 +22,8 @@ public class GeneralCommandTools {
@Tool(description = "Command that creates a keyspace.")
public Uni createKeyspace(
- @ToolArg(description = "Required name of the new Keyspace") String name,
- @ToolArg(description = "Options for creating a new keyspace.", required = false)
+ @ToolArg(description = "Name of the new keyspace") String name,
+ @ToolArg(description = "Options for the command.", required = false)
CreateKeyspaceCommand.Options options) {
var command = new CreateKeyspaceCommand(name, options);
@@ -32,7 +32,7 @@ public Uni createKeyspace(
@Tool(description = "Command that deletes a Keyspace.")
public Uni dropKeyspace(
- @ToolArg(description = "Required name of the Keyspace to remove") @NotEmpty String name) {
+ @ToolArg(description = "Name of the keyspace to drop") @NotEmpty String name) {
var command = new DropKeyspaceCommand(name);
return mcpResource.processCommand(mcpResource.buildDatabaseContext(command), command);
@@ -47,10 +47,7 @@ public Uni findKeyspaces() {
@Tool(description = "Lists the available Embedding Providers for this database.")
public Uni findEmbeddingProviders(
- @ToolArg(
- description =
- "Optional model status filter: SUPPORTED, DEPRECATED, or END_OF_LIFE. If omitted, only SUPPORTED models are returned.",
- required = false)
+ @ToolArg(description = "Options for the command.", required = false)
FindEmbeddingProvidersCommand.Options options) {
var command = new FindEmbeddingProvidersCommand(options);
@@ -59,10 +56,7 @@ public Uni findEmbeddingProviders(
@Tool(description = "Lists the available Reranking Providers for this database.")
public Uni findRerankingProviders(
- @ToolArg(
- description =
- "Optional model status filter: SUPPORTED, DEPRECATED, or END_OF_LIFE. If omitted, only SUPPORTED models are returned.",
- required = false)
+ @ToolArg(description = "Options for the command.", required = false)
FindRerankingProvidersCommand.Options options) {
var command = new FindRerankingProvidersCommand(options);
diff --git a/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/KeyspaceCommandTools.java b/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/KeyspaceCommandTools.java
index faec415caa..2e2e5d6dcd 100644
--- a/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/KeyspaceCommandTools.java
+++ b/src/main/java/io/stargate/sgv2/jsonapi/api/v1/mcp/KeyspaceCommandTools.java
@@ -24,9 +24,9 @@ public class KeyspaceCommandTools {
*/
@Tool(description = "Command that creates a collection.")
public Uni createCollection(
- @ToolArg(description = "Name of the existing keyspace") String keyspace,
+ @ToolArg(description = "Name of the keyspace") String keyspace,
@ToolArg(description = "Name of the new collection") String collection,
- @ToolArg(description = "Configuration options for the collection", required = false)
+ @ToolArg(description = "Options for the command.", required = false)
CreateCollectionCommand.Options options) {
var command = new CreateCollectionCommand(collection, options);
@@ -35,8 +35,8 @@ public Uni createCollection(
@Tool(description = "Command that deletes a collection if one exists.")
public Uni deleteCollection(
- @ToolArg(description = "Name of the existing Keyspace") String keyspace,
- @ToolArg(description = "Name of the existing Collection") String collection) {
+ @ToolArg(description = "Name of the keyspace") String keyspace,
+ @ToolArg(description = "Name of the collection to delete") String collection) {
var command = new DeleteCollectionCommand(collection);
return mcpResource.processCommand(mcpResource.buildKeyspaceContext(keyspace, command), command);
@@ -44,8 +44,8 @@ public Uni deleteCollection(
@Tool(description = "Command that lists all available collections in a keyspace.")
public Uni findCollections(
- @ToolArg(description = "Name of the existing Keyspace") String keyspace,
- @ToolArg(description = "include collection properties.", required = false)
+ @ToolArg(description = "Name of the keyspace") String keyspace,
+ @ToolArg(description = "Options for the command.", required = false)
FindCollectionsCommand.Options options) {
var command = new FindCollectionsCommand(options);
@@ -57,11 +57,11 @@ public Uni findCollections(
*/
@Tool(description = "Command that alters a user defined type.")
public Uni alterType(
- @ToolArg(description = "Keyspace of the type to alter") String keyspace,
+ @ToolArg(description = "Name of the keyspace") String keyspace,
@ToolArg(description = "Name of the type to alter") String name,
- @ToolArg(description = "Operation to rename fields", required = false)
- RenameTypeFieldsDesc rename,
- @ToolArg(description = "Operation to add fields", required = false) TypeDefinitionDesc add) {
+ @ToolArg(description = "Fields to rename", required = false) RenameTypeFieldsDesc rename,
+ @ToolArg(description = "Fields to add to the type", required = false)
+ TypeDefinitionDesc add) {
var command = new AlterTypeCommand(name, rename, add);
return mcpResource.processCommand(mcpResource.buildKeyspaceContext(keyspace, command), command);
@@ -69,10 +69,10 @@ public Uni alterType(
@Tool(description = "Command that creates an API Table.")
public Uni createTable(
- @ToolArg(description = "Name of the existing keyspace") String keyspace,
- @ToolArg(description = "Name of the new Table") String table,
- @ToolArg(description = "Table definition") TableDefinitionDesc definition,
- @ToolArg(description = "Configuration options for the table", required = false)
+ @ToolArg(description = "Name of the keyspace") String keyspace,
+ @ToolArg(description = "Name of the new table") String table,
+ @ToolArg(description = "Definition of the new table") TableDefinitionDesc definition,
+ @ToolArg(description = "Options for the command.", required = false)
CreateTableCommand.Options options) {
var command = new CreateTableCommand(table, definition, options);
@@ -81,10 +81,10 @@ public Uni createTable(
@Tool(description = "Command that creates a user defined type.")
public Uni createType(
- @ToolArg(description = "Name of the existing keyspace") String keyspace,
- @ToolArg(description = "Name of the type to create") String name,
- @ToolArg(description = "Type definition") TypeDefinitionDesc definition,
- @ToolArg(description = "Configuration options for the command", required = false)
+ @ToolArg(description = "Name of the keyspace") String keyspace,
+ @ToolArg(description = "Name of the new type") String name,
+ @ToolArg(description = "Fields of the new type") TypeDefinitionDesc definition,
+ @ToolArg(description = "Options for the command.", required = false)
CreateTypeCommand.Options options) {
var command = new CreateTypeCommand(name, definition, options);
@@ -93,9 +93,9 @@ public Uni createType(
@Tool(description = "Command that drops an index for a column.")
public Uni dropIndex(
- @ToolArg(description = "Name of the existing keyspace") String keyspace,
- @ToolArg(description = "Name of the Index to remove") String name,
- @ToolArg(description = "Dropping index command option.", required = false)
+ @ToolArg(description = "Name of the keyspace") String keyspace,
+ @ToolArg(description = "Name of the index to drop") String name,
+ @ToolArg(description = "Options for the command.", required = false)
DropIndexCommand.Options options) {
var command = new DropIndexCommand(name, options);
@@ -104,9 +104,9 @@ public Uni dropIndex(
@Tool(description = "Command that drops a table if one exists.")
public Uni dropTable(
- @ToolArg(description = "Name of the existing keyspace") String keyspace,
- @ToolArg(description = "Name of the Table to remove") String table,
- @ToolArg(description = "Optional options for drop command", required = false)
+ @ToolArg(description = "Name of the keyspace") String keyspace,
+ @ToolArg(description = "Name of the table to drop") String table,
+ @ToolArg(description = "Options for the command.", required = false)
DropTableCommand.Options options) {
var command = new DropTableCommand(table, options);
@@ -115,9 +115,9 @@ public Uni dropTable(
@Tool(description = "Command that drops a user defined type if one exists.")
public Uni dropType(
- @ToolArg(description = "Name of the existing keyspace") String keyspace,
- @ToolArg(description = "Name of the Type to remove") String name,
- @ToolArg(description = "Options for drop command", required = false)
+ @ToolArg(description = "Name of the keyspace") String keyspace,
+ @ToolArg(description = "Name of the type to drop") String name,
+ @ToolArg(description = "Options for the command.", required = false)
DropTypeCommand.Options options) {
var command = new DropTypeCommand(name, options);
@@ -126,8 +126,8 @@ public Uni dropType(
@Tool(description = "Command that lists all available tables in a keyspace")
public Uni listTables(
- @ToolArg(description = "Name of the existing keyspace") String keyspace,
- @ToolArg(description = "Options for the `listTables` command.", required = false)
+ @ToolArg(description = "Name of the keyspace") String keyspace,
+ @ToolArg(description = "Options for the command.", required = false)
ListTablesCommand.Options options) {
var command = new ListTablesCommand(options);
@@ -136,8 +136,8 @@ public Uni listTables(
@Tool(description = "Command that lists all available types in a keyspace")
public Uni listTypes(
- @ToolArg(description = "Name of the existing keyspace") String keyspace,
- @ToolArg(description = "Options for the `listTypes` command.", required = false)
+ @ToolArg(description = "Name of the keyspace") String keyspace,
+ @ToolArg(description = "Options for the command.", required = false)
ListTypesCommand.Options options) {
var command = new ListTypesCommand(options);
diff --git a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java
index d317e8f7d6..1c66a58440 100644
--- a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java
+++ b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java
@@ -3,6 +3,7 @@
import static io.restassured.RestAssured.given;
import static org.junit.jupiter.api.Assertions.*;
+import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.MissingNode;
@@ -278,6 +279,44 @@ void toolSchemasHideJavaFieldNames() throws Exception {
}
}
+ /** MCP clients choose argument values from these descriptions, so a bare name is not enough. */
+ @Test
+ void everyToolDescribesEveryArgument() throws Exception {
+ for (var tool : toolManager) {
+ var document = inputSchema(tool.name());
+ for (var argument : document.path("properties").properties()) {
+ var label = tool.name() + "." + argument.getKey();
+ var description = schemaMetadata(document, argument.getValue(), "description").asText();
+ assertFalse(description.isBlank(), label);
+ assertNotEquals(argument.getKey(), description.toLowerCase(), label);
+ }
+ }
+ }
+
+ /** An example at the end of an argument description must parse as that argument. */
+ @Test
+ void argumentDescriptionExamplesDeserialize() throws Exception {
+ var marker = "for example ";
+ // Trailing text after the example would mean the example is not the whole JSON value.
+ var reader = objectMapper.reader().with(DeserializationFeature.FAIL_ON_TRAILING_TOKENS);
+ var checked = 0;
+ for (var tool : toolManager) {
+ for (var argument : tool.arguments()) {
+ var start = argument.description().indexOf(marker);
+ if (start < 0) {
+ continue;
+ }
+ var label = tool.name() + "." + argument.name();
+ var example = reader.readTree(argument.description().substring(start + marker.length()));
+ var type = objectMapper.constructType(argument.type());
+ assertNotNull(
+ assertDoesNotThrow(() -> objectMapper.treeToValue(example, type), label), label);
+ checked++;
+ }
+ }
+ assertTrue(checked > 0, "No argument description has an example");
+ }
+
/**
* Each update tool must use the update clause schema and require an update, as the command's
* validation does. The filter may be left out or null.