Skip to content

fix: describe every MCP tool argument and the JSON it takes - #2658

Merged
erichare merged 11 commits into
mainfrom
fix/mcp-tool-argument-descriptions
Nov 19, 2026
Merged

erichare merged 11 commits into
mainfrom
fix/mcp-tool-argument-descriptions

Conversation

@erichare

@erichare erichare commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

What this PR does:

Gives every MCP tool argument a description, to the standard #2619 set for findAndRerank. Aaron asked for this in review. Options arguments say "Options for the command." and rely on the field descriptions on their Options classes, and definition arguments rely on their classes the same way. Filter and sort keep their class descriptions. Free-form documents carry no example, and the alterTable operation and projections keep a short example that a contract test parses as the argument type.

Update arguments use the UpdateClause description from #2651 instead of repeating it.

Which issue(s) this PR fixes:

Addresses the MCP argument portion of #2604.

Verification

118 focused tests passed with 0 failures, 0 errors, and 0 skips at 2a1d8435c, after merging main, which now includes #2651. The local format check did not run because this machine only has JDK 25 and google-java-format 1.21 needs JDK 21, so CI runs it. CI also runs the unit and DSE/HCD integration suites on this push. Manual client checks were not run.

JAVA_HOME=/Library/Java/JavaVirtualMachines/graalvm-25.jdk/Contents/Home ./mvnw clean test -Dfmt.skip=true -Dxml-format.skip=true -Dsurefire.failIfNoSpecifiedTests=false '-Dtest=McpSchemaCustomizerTest,McpClauseSchemaContractTest,McpOpenApiSchemaAdapterTest,McpProtocolTest'

Checklist

  • Changes manually tested
  • Automated Tests added/updated
  • Documentation added/updated
  • CLA Signed: DataStax CLA

MCP stack

Merges bottom up; row 1 is the bottom of the stack.

# PR Change Issue
1 #2651 (merged) Show accepted update syntax in tool schemas #2631
2 #2658 Describe every tool argument Part of #2604
3 #2645 Close the command context after each call Part of #2629
4 #2653 Return useful errors when setup fails #2628
5 #2648 Keep payloads and credentials out of logs #2635
6 #2649 Describe side effects and retry behavior #2636
7 #2655 Validate commands like the HTTP API #2632
8 #2656 Test request isolation, document tracing Refs #2629
9 #2657 Reject unapproved browser origins Part of #2630
10 #2659 Serve only protocol 2026-07-28 Part of #2625, #2626
11 #2669 Add opt-in OAuth authentication Refs #2642, #2643

@erichare
erichare requested a review from a team as a code owner October 23, 2026 21:43
@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

📈 Unit Test Coverage Delta vs Main Branch

Metric Value
Main Branch 57.09%
This PR 57.12%
Delta 🟢 +0.03%
✅ Coverage improved!

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Unit Test Coverage Report

Overall Project 57.12% 🍏
File Coverage
TableDefinitionDesc.java 100% 🍏
FindEmbeddingProvidersCommand.java 42.86% 🍏
KeyspaceCommandTools.java 0% 🍏
CollectionCommandTools.java 0% 🍏
GeneralCommandTools.java 0% 🍏

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

➡️ Integration Test Coverage Delta vs Main Branch (dse69-it)

Metric Value
Main Branch 72.75%
This PR 72.75%
Delta ⚪ 0.00%
ℹ️ Coverage unchanged

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Integration Test Coverage Report (dse69-it)

Overall Project 72.75% 🍏
File Coverage
KeyspaceCommandTools.java 100% 🍏
CollectionCommandTools.java 100% 🍏
GeneralCommandTools.java 100% 🍏
TableDefinitionDesc.java 100% 🍏
FindEmbeddingProvidersCommand.java 85.71% 🍏

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

➡️ Integration Test Coverage Delta vs Main Branch (hcd-it)

Metric Value
Main Branch 74.21%
This PR 74.21%
Delta ⚪ 0.00%
ℹ️ Coverage unchanged

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Integration Test Coverage Report (hcd-it)

Overall Project 74.21% 🍏
File Coverage
KeyspaceCommandTools.java 100% 🍏
CollectionCommandTools.java 100% 🍏
GeneralCommandTools.java 100% 🍏
TableDefinitionDesc.java 100% 🍏
FindEmbeddingProvidersCommand.java 85.71% 🍏

@amorton amorton left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

some changes for the comments etc, and we are going to have to deal with this McpClauseSchemaContractTest class at some point.

@ToolArg(
description =
"Optional type of the index to create. The only supported value is '"
"Type of the index to create. The only supported value is '"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pls put Optional back, this field is basically ignored and only here for consistency

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done, Optional is back.

@ToolArg(
description =
"Optional type of the index to create. The only supported value is '"
"Type of the index to create. The only supported value is '"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pls put "Optional" back.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done, Optional is back.

@ToolArg(description = "include collection properties.", required = false)
@ToolArg(description = "Name of the keyspace") String keyspace,
@ToolArg(
description = "Set explain to true to include the properties of each collection",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just say options and rely on the desc on the Option class fields

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done, it now says "Options for the command."

"Columns and primary key of the new table, for example {\"columns\": {\"id\": \"text\", \"title\": \"text\"}, \"primaryKey\": \"id\"}")
TableDefinitionDesc definition,
@ToolArg(
description = "Set ifNotExists to true to succeed when the table already exists",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just say options and rely on the desc on the Option class fields

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done, it now says "Options for the command."

assertEquals(
description,
schemaMetadata(document, propertySchema(document, "filter"), "description").asText());
void clauseArgumentsUseClassDescriptions() throws Exception {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is a clauseArgument ?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It meant a filter or sort argument, and that test is gone now.

…contract test

McpSchemaCustomizerTest now covers each rule the customizer adds in four
tests: JSON property names, ignored and hidden fields, descriptions, and
component references. It reaches every line and branch of the customizer.

McpClauseSchemaContractTest keeps the checks that published clause schemas
agree with the server's parsers. Tool payload cases that repeat
McpSchemaIntegrationTest are removed, the update cases run once against
the update clause schema instead of once per tool, and the rerank
credentials case is a row in the override table.
…descriptions

# Conflicts:
#	src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java
Options arguments now say "Options for the command." and rely on the
field descriptions in their Options classes. Definition arguments rely
on TableDefinitionDesc the same way, which now carries the column and
primary key details. indexType says "Optional" again, free-form
documents carry no example, and alterTable uses the reviewed wording.
The embedding provider filter now says null or an empty string returns
all models, matching the reranking filter.

The contract test checks that every tool argument has a description
and that any example at the end of one parses as the argument type.
@erichare
erichare requested a review from amorton November 17, 2026 03:00

@amorton amorton left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LOGTM

Base automatically changed from fix/mcp-update-wire-schema to main November 19, 2026 05:10
…-descriptions

# Conflicts:
#	src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants