feat: add tool annotations according to 2025-03-26 spec #71

SeanChinJunKai · 2025-04-09T08:06:03Z

Motivation and Context

Add tool annotations to provide additional properties describing a Tool to clients.

How Has This Been Tested?

NA

Breaking Changes

NA

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

References:
https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-03-26/schema.ts#L737

Copilot

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

Comments suppressed due to low confidence (2)

src/jvmTest/kotlin/client/ClientTest.kt:526

Consider adding a test case with non-null annotations to validate the behavior when actual annotation data is provided.

annotations = null,

src/commonTest/kotlin/ToolSerializationTest.kt:36

Consider including a test scenario for serializing/deserializing a Tool with non-null annotations to ensure full coverage of the new feature.

annotations = null,

e5l

lgtm, would be nice to have a sample as well

SeanChinJunKai · 2025-04-11T05:34:37Z

Hi @e5l, Ill look into it. Thanks for the feedback!

SeanChinJunKai · 2025-04-13T15:47:00Z

Hi @e5l, shall i add it in the weather server sample?

e5l · 2025-04-17T08:46:14Z

yep, it would be great

SeanChinJunKai · 2025-04-27T03:21:46Z

@e5l Is there anything else required from my end to get this PR merged?

e5l · 2025-04-27T06:46:38Z

Could you run apiDump task and commit the result?

SeanChinJunKai · 2025-04-27T06:56:27Z

@e5l i have commited the result. Should i do so for the other 2 PRs?

e5l · 2025-04-29T12:26:05Z

yep!

e5l

lgtm

| Package | Type | Package file | Manager | Update | Change | |---|---|---|---|---|---| | [io.modelcontextprotocol:kotlin-sdk](https://github.com/modelcontextprotocol/kotlin-sdk) | dependencies | misk/gradle/libs.versions.toml | gradle | minor | `0.5.0` -> `0.6.0` | | [org.jetbrains.kotlinx:kotlinx-serialization-json](https://github.com/Kotlin/kotlinx.serialization) | dependencies | misk/gradle/libs.versions.toml | gradle | minor | `1.7.3` -> `1.9.0` | | [org.jetbrains.kotlinx:kotlinx-serialization-core](https://github.com/Kotlin/kotlinx.serialization) | dependencies | misk/gradle/libs.versions.toml | gradle | minor | `1.7.3` -> `1.9.0` | | [com.google.apis:google-api-services-storage](http://nexus.sonatype.org/oss-repository-hosting.html) ([source](http://svn.sonatype.org/spice/tags/oss-parent-7)) | dependencies | misk/gradle/libs.versions.toml | gradle | patch | `v1-rev20250718-2.0.0` -> `v1-rev20250814-2.0.0` | | [software.amazon.awssdk:sdk-core](https://aws.amazon.com/sdkforjava) | dependencies | misk/gradle/libs.versions.toml | gradle | patch | `2.32.23` -> `2.32.24` | | [software.amazon.awssdk:sqs](https://aws.amazon.com/sdkforjava) | dependencies | misk/gradle/libs.versions.toml | gradle | patch | `2.32.23` -> `2.32.24` | | [software.amazon.awssdk:regions](https://aws.amazon.com/sdkforjava) | dependencies | misk/gradle/libs.versions.toml | gradle | patch | `2.32.23` -> `2.32.24` | | [software.amazon.awssdk:dynamodb-enhanced](https://aws.amazon.com/sdkforjava) | dependencies | misk/gradle/libs.versions.toml | gradle | patch | `2.32.23` -> `2.32.24` | | [software.amazon.awssdk:dynamodb](https://aws.amazon.com/sdkforjava) | dependencies | misk/gradle/libs.versions.toml | gradle | patch | `2.32.23` -> `2.32.24` | | [software.amazon.awssdk:aws-core](https://aws.amazon.com/sdkforjava) | dependencies | misk/gradle/libs.versions.toml | gradle | patch | `2.32.23` -> `2.32.24` | | [software.amazon.awssdk:bom](https://aws.amazon.com/sdkforjava) | dependencies | misk/gradle/libs.versions.toml | gradle | patch | `2.32.23` -> `2.32.24` | | [software.amazon.awssdk:auth](https://aws.amazon.com/sdkforjava) | dependencies | misk/gradle/libs.versions.toml | gradle | patch | `2.32.23` -> `2.32.24` | --- ### Release Notes <details> <summary>modelcontextprotocol/kotlin-sdk (io.modelcontextprotocol:kotlin-sdk)</summary> ### [`v0.6.0`](https://github.com/modelcontextprotocol/kotlin-sdk/releases/tag/0.6.0) [Compare Source](modelcontextprotocol/kotlin-sdk@0.5.0...0.6.0) #### What's Changed - Update jreleaser to fix publication issue by [@e5l](https://github.com/e5l) in modelcontextprotocol/kotlin-sdk#91 - Disable configuration cache to fix jreleaser issue by [@e5l](https://github.com/e5l) in modelcontextprotocol/kotlin-sdk#92 - feat: Add audio type according to 2025-03-26 spec by [@SeanChinJunKai](https://github.com/SeanChinJunKai) in modelcontextprotocol/kotlin-sdk#68 - fix(client): serialize inputSchema as input\_schema by [@shiqicao](https://github.com/shiqicao) in modelcontextprotocol/kotlin-sdk#97 - fix(client) add encodeDefault for field with non spec default value by [@shiqicao](https://github.com/shiqicao) in modelcontextprotocol/kotlin-sdk#99 - Make McpJson public to allow flexible protocol development by [@parnurzeal](https://github.com/parnurzeal) in modelcontextprotocol/kotlin-sdk#103 - fix: apply `requestBuilder` headers when sending rpc messages by [@dead8309](https://github.com/dead8309) in modelcontextprotocol/kotlin-sdk#96 - fix: Remove [@SerialName](https://github.com/SerialName) annotation for inputSchema by [@adamglin0](https://github.com/adamglin0) in modelcontextprotocol/kotlin-sdk#105 - add ios and wasm targets by [@devcrocod](https://github.com/devcrocod) in modelcontextprotocol/kotlin-sdk#81 - Add dependabot by [@StefMa](https://github.com/StefMa) in modelcontextprotocol/kotlin-sdk#121 - Bump org.jetbrains.kotlinx:kotlinx-serialization-json from 1.7.3 to 1.8.1 by [@dependabot](https://github.com/dependabot)\[bot] in modelcontextprotocol/kotlin-sdk#127 - Bump io.github.oshai:kotlin-logging from 7.0.0 to 7.0.7 by [@dependabot](https://github.com/dependabot)\[bot] in modelcontextprotocol/kotlin-sdk#126 - Bump org.jetbrains.kotlinx.binary-compatibility-validator from 0.17.0 to 0.18.0 by [@dependabot](https://github.com/dependabot)\[bot] in modelcontextprotocol/kotlin-sdk#125 - update kotlin to 2.2.0 and ktor to 3.1.3 by [@devcrocod](https://github.com/devcrocod) in modelcontextprotocol/kotlin-sdk#120 - Add client roots addition/removal API and listRoots handler by [@ptitjes](https://github.com/ptitjes) in modelcontextprotocol/kotlin-sdk#118 - Bump org.slf4j:slf4j-simple from 2.0.16 to 2.0.17 by [@dependabot](https://github.com/dependabot)\[bot] in modelcontextprotocol/kotlin-sdk#131 - Bump org.jetbrains.kotlinx:kotlinx-serialization-json from 1.8.1 to 1.9.0 by [@dependabot](https://github.com/dependabot)\[bot] in modelcontextprotocol/kotlin-sdk#132 - Bump io.mockk:mockk from 1.13.13 to 1.14.4 by [@dependabot](https://github.com/dependabot)\[bot] in modelcontextprotocol/kotlin-sdk#133 - Remove fixed suffix /sse by [@adamglin0](https://github.com/adamglin0) in modelcontextprotocol/kotlin-sdk#108 - sse server does not process endpoint correctly when sse path is not a directory by [@shendaxia-sm](https://github.com/shendaxia-sm) in modelcontextprotocol/kotlin-sdk#43 - Add labels to dependabot configuration for Kotlin and GitHub Actions by [@devcrocod](https://github.com/devcrocod) in modelcontextprotocol/kotlin-sdk#135 - feat: add tool annotations according to 2025-03-26 spec by [@SeanChinJunKai](https://github.com/SeanChinJunKai) in modelcontextprotocol/kotlin-sdk#71 - Bump ktor from 3.1.3 to 3.2.1 by [@dependabot](https://github.com/dependabot)\[bot] in modelcontextprotocol/kotlin-sdk#140 - Bump gradle/actions from 4.0.0 to 4.4.1 by [@dependabot](https://github.com/dependabot)\[bot] in modelcontextprotocol/kotlin-sdk#122 - Bump org.jreleaser from 1.17.0 to 1.19.0 by [@dependabot](https://github.com/dependabot)\[bot] in modelcontextprotocol/kotlin-sdk#141 - refactor `SseClientTransport` by [@devcrocod](https://github.com/devcrocod) in modelcontextprotocol/kotlin-sdk#142 - atomic and persistent collections for thread safety by [@devcrocod](https://github.com/devcrocod) in modelcontextprotocol/kotlin-sdk#143 - Bump org.gradle.toolchains.foojay-resolver-convention from 0.8.0 to 1.0.0 by [@dependabot](https://github.com/dependabot)\[bot] in modelcontextprotocol/kotlin-sdk#130 - Add support for elicitation by [@ptitjes](https://github.com/ptitjes) in modelcontextprotocol/kotlin-sdk#138 - Add support for tool structured content and output schema by [@ptitjes](https://github.com/ptitjes) in modelcontextprotocol/kotlin-sdk#146 - Add streamable http client transport by [@devcrocod](https://github.com/devcrocod) in modelcontextprotocol/kotlin-sdk#147 - Refactor JSON processing to exclude "method" in serialization by [@devcrocod](https://github.com/devcrocod) in [#157](modelcontextprotocol/kotlin-sdk#157) - Release 0.6.0 by [@devcrocod](https://github.com/devcrocod) in modelcontextprotocol/kotlin-sdk#149 #### New Contributors - [@shiqicao](https://github.com/shiqicao) made their first contribution in modelcontextprotocol/kotlin-sdk#97 - [@parnurzeal](https://github.com/parnurzeal) made their first contribution in modelcontextprotocol/kotlin-sdk#103 - [@dead8309](https://github.com/dead8309) made their first contribution in modelcontextprotocol/kotlin-sdk#96 - [@adamglin0](https://github.com/adamglin0) made their first contribution in modelcontextprotocol/kotlin-sdk#105 - [@StefMa](https://github.com/StefMa) made their first contribution in modelcontextprotocol/kotlin-sdk#121 - [@dependabot](https://github.com/dependabot)\[bot] made their first contribution in modelcontextprotocol/kotlin-sdk#127 - [@ptitjes](https://github.com/ptitjes) made their first contribution in modelcontextprotocol/kotlin-sdk#118 - [@shendaxia-sm](https://github.com/shendaxia-sm) made their first contribution in modelcontextprotocol/kotlin-sdk#43 **Full Changelog**: modelcontextprotocol/kotlin-sdk@0.5.0...0.6.0 </details> <details> <summary>Kotlin/kotlinx.serialization (org.jetbrains.kotlinx:kotlinx-serialization-json)</summary> ### [`v1.9.0`](https://github.com/Kotlin/kotlinx.serialization/blob/HEAD/CHANGELOG.md#190--2025-06-27) \================== This release updates Kotlin version to 2.2.0, includes several bugfixes and provides serializers for kotlin.time.Instant. #### Add kotlin.time.Instant serializers Instant class was moved from kotlinx-datetime library to Kotlin standard library. As a result, kotlinx-datetime 0.7.0 no longer has serializers for the Instant class. To use new kotlin.time.Instant class in your [@Serializable](https://github.com/Serializable) classes, you can use this 1.9.0 kotlinx-serialization version (Kotlin 2.2 is required). You can choose between default `InstantSerializer` which uses its string representation, or specify `InstantComponentSerializer` that represents instant as its components. See details in the [PR](Kotlin/kotlinx.serialization#2945). #### Other bugfixes - Fix resize in JsonPath ([#2995](Kotlin/kotlinx.serialization#2995)) - Fixed proguard rules for obfuscation to work correctly ([#2983](Kotlin/kotlinx.serialization#2983)) ### [`v1.8.1`](https://github.com/Kotlin/kotlinx.serialization/blob/HEAD/CHANGELOG.md#181--2025-03-31) \================== This release updates Kotlin version to 2.1.20, while also providing several important improvements and bugfixes. #### Improvements - Implemented encoding null in key and value of a map in Protobuf ([#2910](Kotlin/kotlinx.serialization#2910)) - Make type argument in JsonTransformingSerializer nullable ([#2911](Kotlin/kotlinx.serialization#2911)) - Use SPDX identifier in POMs ([#2936](Kotlin/kotlinx.serialization#2936)) (thanks to [Leon Linhart](https://github.com/TheMrMilchmann)) - Add watchosDeviceArm64 to Okio integration module ([#2920](Kotlin/kotlinx.serialization#2920)) (thanks to [Daniel Santiago](https://github.com/danysantiago)) - Update kotlinx-io version to 0.6.0 ([#2933](Kotlin/kotlinx.serialization#2933)) (thanks to [Piotr Krzemiński](https://github.com/krzema12)) #### Bugfixes - Fix incorrect enum coercion during deserialization from JsonElement ([#2962](Kotlin/kotlinx.serialization#2962)) - Supply proper equals(), hashCode(), and toString() for SerialDescriptor() wrapper ([#2942](Kotlin/kotlinx.serialization#2942)) - Do not encode empty packed collections in protobuf ([#2907](Kotlin/kotlinx.serialization#2907)) ### [`v1.8.0`](https://github.com/Kotlin/kotlinx.serialization/blob/HEAD/CHANGELOG.md#180--2025-01-06) \================== This release contains all of the changes from 1.8.0-RC. Kotlin 2.1.0 is used as a default, while upcoming 2.1.10 is also supported. Also added small bugfixes, including speedup of ProtoWireType.from ([#2879](Kotlin/kotlinx.serialization#2879)). </details> --- ### Configuration 📅 **Schedule**: Branch creation - "after 6pm every weekday,before 2am every weekday" in timezone Australia/Melbourne, Automerge - At any time (no schedule defined). 🚦 **Automerge**: Enabled. ♻ **Rebasing**: Never, or you tick the rebase/retry checkbox. 👻 **Immortal**: This PR will be recreated if closed unmerged. Get [config help](https://github.com/renovatebot/renovate/discussions) if that's undesired. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate). GitOrigin-RevId: 40e2f07ecd958e92e64c571d1351e91f96e71ce7

e5l requested review from e5l and Copilot April 9, 2025 18:46

Copilot AI reviewed Apr 9, 2025

View reviewed changes

e5l previously approved these changes Apr 10, 2025

View reviewed changes

e5l enabled auto-merge (squash) April 10, 2025 08:21

e5l disabled auto-merge April 26, 2025 10:55

e5l enabled auto-merge (squash) April 26, 2025 10:55

auto-merge was automatically disabled April 27, 2025 06:55
Head branch was pushed to by a user without write access

SeanChinJunKai dismissed e5l’s stale review via 6a77567 April 27, 2025 06:55

e5l previously approved these changes Apr 29, 2025

View reviewed changes

e5l enabled auto-merge (squash) April 29, 2025 12:26

devcrocod dismissed e5l’s stale review via 0594222 July 3, 2025 16:40

devcrocod force-pushed the sean/tool-annotations branch from f072424 to 0594222 Compare July 3, 2025 16:40

devcrocod requested a review from e5l July 3, 2025 16:40

devcrocod disabled auto-merge July 3, 2025 16:40

SeanChinJunKai and others added 3 commits July 6, 2025 17:49

feat: add tool annotations

b6743ad

chore: commit api dump

431c573

fix import and api

d4db2f2

devcrocod force-pushed the sean/tool-annotations branch from 30159ef to d4db2f2 Compare July 6, 2025 15:49

devcrocod approved these changes Jul 6, 2025

View reviewed changes

Merge branch 'main' into sean/tool-annotations

890acc0

e5l approved these changes Jul 7, 2025

View reviewed changes

e5l enabled auto-merge (squash) July 7, 2025 06:47

e5l merged commit 89c2037 into modelcontextprotocol:main Jul 7, 2025
1 check passed

devcrocod mentioned this pull request Jul 21, 2025

Tool annotations #184

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add tool annotations according to 2025-03-26 spec #71

feat: add tool annotations according to 2025-03-26 spec #71

Uh oh!

SeanChinJunKai commented Apr 9, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

e5l left a comment

Uh oh!

SeanChinJunKai commented Apr 11, 2025

Uh oh!

SeanChinJunKai commented Apr 13, 2025

Uh oh!

e5l commented Apr 17, 2025 •

edited

Loading

Uh oh!

SeanChinJunKai commented Apr 27, 2025

Uh oh!

e5l commented Apr 27, 2025

Uh oh!

SeanChinJunKai commented Apr 27, 2025 •

edited

Loading

Uh oh!

e5l commented Apr 29, 2025

Uh oh!

e5l left a comment

Uh oh!

Uh oh!

Uh oh!

feat: add tool annotations according to 2025-03-26 spec #71

feat: add tool annotations according to 2025-03-26 spec #71

Uh oh!

Conversation

SeanChinJunKai commented Apr 9, 2025

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

e5l left a comment

Choose a reason for hiding this comment

Uh oh!

SeanChinJunKai commented Apr 11, 2025

Uh oh!

SeanChinJunKai commented Apr 13, 2025

Uh oh!

e5l commented Apr 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SeanChinJunKai commented Apr 27, 2025

Uh oh!

e5l commented Apr 27, 2025

Uh oh!

SeanChinJunKai commented Apr 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

e5l commented Apr 29, 2025

Uh oh!

e5l left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

e5l commented Apr 17, 2025 •

edited

Loading

SeanChinJunKai commented Apr 27, 2025 •

edited

Loading