SEP-1577 - Sampling With Tools #1796

ochafik · 2025-11-11T18:40:13Z

Motivation and Context

Spec change for #1577

Related: Python SDK change, TypeScript SDK change

How Has This Been Tested?

Breaking Changes

SDK users will need to update any code that uses sampling to test the type of the CreateMessageResult.content, which can now be an array of content objects.

Wire format will be unchanged if the spec version is < 2025-11-25 (i.e. the content field will not be an array).

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

Implement SEP-1577 to enable tool calling in sampling requests. Major changes: - Add tools and toolChoice parameters to sampling/createMessage - Introduce ToolUseContent and ToolResultContent message types - Support parallel tool calls via content arrays - Add sampling.tools and sampling.context capabilities to ClientCapabilities - Soft-deprecate includeContext values thisServer/allServers Breaking changes: - Content fields can now be arrays (for parallel tool calls) - Wire-level backward compatible - Tool result messages cannot contain mixed content types Updates: - schema/draft/schema.ts: New types and updated interfaces - schema/draft/schema.json: Auto-generated from TypeScript - docs/specification/draft/schema.mdx: Auto-generated from TypeScript - docs/specification/draft/client/sampling.mdx: Tool calling docs with examples - docs/specification/draft/changelog.mdx: SEP-1577 entry Cross-API compatibility: - Compatible with Claude, OpenAI, and Gemini APIs - Message content constraints ensure clean role mapping - Tool IDs support APIs without native ID support 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

… message balance requirement - Make ToolResultContent.content required (not optional) to align with CallToolResult per SEP Oct 27 update that states "aligned on CallToolResult" - Add documentation for message balance requirement in sampling.mdx (tool use messages must be followed by corresponding tool results) - Regenerate schema.json and schema.mdx from updated types 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Aligns terminology with existing naming: - type: "tool_use" - ToolUseContent - stopReason: "toolUse" Updated all documentation and comments to use "tool use" instead of "tool calling" for feature name consistency. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Keep original 5 security considerations unchanged and add tool-specific items (6-12) as new additions rather than rewriting all items. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Remove redundant items (user approval already covered in item 1) - Remove off-topic items (validation, sanitization, timeouts) - Consolidate into key requirement: servers MUST respond to all tool uses and ensure tool result messages contain only tool results 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

bhosmer-ant

Thanks for turning this around so quickly! Lots of comments, mostly minor editing tweaks. Let's chat offline about the others, nothing major but easier to get through with more bandwidth

docs/specification/draft/client/sampling.mdx

schema/draft/schema.ts

ochafik

Addressed some comments (not all yet)

docs/specification/draft/client/sampling.mdx

schema/draft/schema.ts

docs/specification/draft/client/sampling.mdx

@category

…num improvements) Conflicts resolved: - docs/specification/draft/changelog.mdx: Renumbered SEP-1577 to item #6 - schema/draft/schema.ts: Fixed @category annotations (added backticks) - schema/draft/schema.json: Auto-regenerated from schema.ts - docs/specification/draft/schema.mdx: Auto-regenerated with new structure Changes: - SEP-1577: Adds tool calling support to sampling/createMessage - New types: ToolChoice, ToolUseContent, ToolResultContent, UserMessage, AssistantMessage - Enhanced ClientCapabilities.sampling with tools field - SEP-1330: Adds JSON Schema 2020-12 compliant enum types - New types: TitledSingleSelectEnumSchema, TitledMultiSelectEnumSchema, etc. - Structural: schema.mdx template now includes @category tags for organization All schema validations passed: - TypeScript compilation: ✓ - JSON schema generation: ✓ - MDX documentation generation: ✓ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Co-authored-by: bhosmer-ant <[email protected]>

…and tool_result content

Improved line breaks and spacing for clarity in the 'includeContext' note and tool choice modes section of the sampling client specification draft.

….com/modelcontextprotocol/modelcontextprotocol into ochafik/sep-1577-sampling-with-tools

Updated the example sequences in the sampling specification to use inline code formatting for ToolUseContent and ToolResultContent, improving clarity and consistency in documentation.

localden · 2025-11-14T06:47:52Z

@ochafik @bhosmer-ant I just pushed a few changes to fix the linting errors. Looks like there are a few more comments left to address?

ochafik

Thanks so much @localden & @bhosmer-ant !!

schema/draft/schema.ts

docs/specification/draft/client/sampling.mdx

bhosmer-ant

LGTM!

dsp-ant · 2025-11-14T16:52:58Z

docs/specification/draft/client/sampling.mdx


+## Tools in Sampling
+
+Servers can request that the client's LLM use tools during sampling by providing a `tools` array and optional `toolChoice` configuration in their sampling requests. This enables servers to implement agentic behaviors where the LLM can call tools, receive results, and continue the conversation&mdash;all within a single sampling request flow.


Suggested change

Servers can request that the client's LLM use tools during sampling by providing a `tools` array and optional `toolChoice` configuration in their sampling requests. This enables servers to implement agentic behaviors where the LLM can call tools, receive results, and continue the conversation—all within a single sampling request flow.

Servers can request that the client's LLM use tools during sampling by providing a `tools` array and optional `toolChoice` configuration in their sampling requests. This enables servers to implement agentic behaviors where the LLM can call tools, receive results, and continue the conversation - all within a single sampling request flow.

dsp-ant · 2025-11-14T16:53:22Z

docs/specification/draft/client/sampling.mdx

+- Multiple tools can be used in parallel
+- Tool results are provided back to the LLM to inform subsequent responses
+
+Clients **MUST** declare support for tool use via the `sampling.tools` capability to receive tool-enabled sampling requests. Servers **SHOULD NOT** send tool-enabled sampling requests to Clients that have not declared support for tool use via the `sampling.tools` capability.


Suggested change

Clients **MUST** declare support for tool use via the `sampling.tools` capability to receive tool-enabled sampling requests. Servers **SHOULD NOT** send tool-enabled sampling requests to Clients that have not declared support for tool use via the `sampling.tools` capability.

Clients **MUST** declare support for tool use via the `sampling.tools` capability to receive tool-enabled sampling requests. Servers **MUST NOT** send tool-enabled sampling requests to Clients that have not declared support for tool use via the `sampling.tools` capability.

dsp-ant · 2025-11-14T16:54:03Z

docs/specification/draft/client/sampling.mdx

+Clients **MUST** declare support for tool use via the `sampling.tools` capability to receive tool-enabled sampling requests. Servers **SHOULD NOT** send tool-enabled sampling requests to Clients that have not declared support for tool use via the `sampling.tools` capability.
+
+<Info>
+  Tool use in sampling uses the same `Tool` type as regular MCP tool calls,


can we link to that? I am also not really sure waht this section means. We usually refer to things in the spec as primitives, if that's what's meant here.

I think we can remove it without losing anything critical - more of a design note than anything else

dsp-ant · 2025-11-14T16:55:17Z

docs/specification/draft/client/sampling.mdx

+**Key capabilities:**
+
+- Servers define tools with JSON schemas for inputs and outputs
+- The LLM decides when and how to use tools (subject to `toolChoice` constraints)
+- Multiple tools can be used in parallel
+- Tool results are provided back to the LLM to inform subsequent responses


not sure this is needed

dsp-ant · 2025-11-14T16:55:47Z

docs/specification/draft/client/sampling.mdx

+**With context inclusion support (soft-deprecated):**
+
+```json
+{
+  "capabilities": {
+    "sampling": {
+      "context": {}
+    }
+  }
+}
+```
+


I am confused about this. There is no section about how this is deprecation is handled. Can we talk in separate section about handling the context inclusion?

See note immediately below - what do you think is missing from there?

dsp-ant · 2025-11-14T16:57:48Z

docs/specification/draft/client/sampling.mdx

+
+### Tool Use and Result Balance
+
+When using tool use in sampling, messages **MUST** be properly balanced: every assistant message containing `ToolUseContent` blocks must be followed by a user message that consists entirely of `ToolResultContent` blocks, with each tool use (e.g. with `id: $id`) matched by a corresponding tool result (with `toolUseId: $id`), before any other message.


The word "balanced" feels off here. I think we can say:

When using tool use messages MUST ensure that an assistant message containing ToolUseContent is followed by a user message consisting of ToolResultContent blocks

I'm having trouble parsing your suggestion, but if you want to avoid balanced how about just

When using tool use in sampling, every assistant message containing ToolUseContent blocks MUST be followed by a user message that consists entirely of ToolResultContent blocks, with each tool use (e.g. with id: $id) matched by a corresponding tool result (with toolUseId: $id), before any other message.

dsp-ant · 2025-11-14T16:59:16Z

docs/specification/draft/client/sampling.mdx

 Clients **SHOULD** return errors for common failure cases:

-Example error:
+- User rejected sampling request: `-1`


Does JSON RPC have a specific error integer range for custom errors?

json rpc spec says anything outside the reserved range (-32768 to -32000). @ochafik found that we specify -1 elsewhere in the spec, that's where this came from

The -1 is what is used a couple of lines below in the existing example for User rejected sampling request, and looks like it's actually fine as an application error.

The json rpc spec's Custom Error Codes section says:

For application-specific errors, the JSON-RPC 2.0 specification allows using any error code outside the reserved range (-32768 to -32000). Custom error codes are typically chosen based on the specific needs of your application.

Recommended Ranges
Range Usage
...
-31999 to -1 Recommended for general application errors

(next best thing would be -32601 / Method not found / The method does not exist / is not available, if we want to avoid an application error here - slight stretch of meaning to consider that declining sampling is a form of making it not available)

ochafik and others added 6 commits November 7, 2025 19:45

Rename section to 'Tools in Sampling' for clarity

b34c230

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

ochafik requested a review from a team as a code owner November 11, 2025 18:40

mintlify bot deployed to staging - docs November 11, 2025 18:41 View deployment

ochafik requested a review from bhosmer-ant November 11, 2025 18:46

nit

102512e

mintlify bot deployed to staging - docs November 11, 2025 18:53 View deployment

This was referenced Nov 11, 2025

Implement SEP-1577 - Sampling With Tools modelcontextprotocol/typescript-sdk#1101

Merged

Implement SEP-1577 - Sampling With Tools modelcontextprotocol/python-sdk#1594

Merged

SEP-1577 - Sampling With Tools #1577

Closed

bhosmer-ant reviewed Nov 12, 2025

View reviewed changes

address some comments

e942edc

ochafik commented Nov 12, 2025

View reviewed changes

mintlify bot deployed to staging - docs November 12, 2025 12:16 View deployment

mintlify bot deployed to staging - docs November 12, 2025 13:46 View deployment

Update docs/specification/draft/client/sampling.mdx

3a9c719

Co-authored-by: bhosmer-ant <[email protected]>

mintlify bot deployed to staging - docs November 12, 2025 13:49 View deployment

Update schema.json

5096d90

localden linked an issue Nov 12, 2025 that may be closed by this pull request

SEP-1577 - Sampling With Tools #1577

Closed

dend assigned bhosmer-ant Nov 12, 2025

ochafik added 2 commits November 13, 2025 15:36

add sequence diagram

32690e1

drop complexity of SamplingMessage, now can loosely contain tool_use …

8e197eb

…and tool_result content

mintlify bot deployed to staging - docs November 13, 2025 15:38 View deployment

Merge branch 'main' into ochafik/sep-1577-sampling-with-tools

fc75656

mintlify bot deployed to staging - docs November 13, 2025 18:17 View deployment

localden added 5 commits November 13, 2025 22:17

Update formatting in sampling spec documentation

54c7071

Improved line breaks and spacing for clarity in the 'includeContext' note and tool choice modes section of the sampling client specification draft.

Merge branch 'ochafik/sep-1577-sampling-with-tools' of https://github…

4e63bef

….com/modelcontextprotocol/modelcontextprotocol into ochafik/sep-1577-sampling-with-tools

Update sampling.mdx

2d63d04

Update schema.ts

ac55d00

Format tool use examples with code style

dc31a96

Updated the example sequences in the sampling specification to use inline code formatting for ToolUseContent and ToolResultContent, improving clarity and consistency in documentation.

mintlify bot deployed to staging - docs November 14, 2025 06:34 View deployment

Update schema.mdx

684c91c

mintlify bot deployed to staging - docs November 14, 2025 06:46 View deployment

added sampling error handling examples

bdad356

mintlify bot deployed to staging - docs November 14, 2025 12:23 View deployment

updated to SHOULD NOT send context w/o capability for consistency

fa33396

mintlify bot deployed to staging - docs November 14, 2025 12:30 View deployment

ochafik commented Nov 14, 2025

View reviewed changes

schema/draft/schema.ts Show resolved Hide resolved

docs/specification/draft/client/sampling.mdx Show resolved Hide resolved

docs/specification/draft/client/sampling.mdx Outdated Show resolved Hide resolved

docs/specification/draft/client/sampling.mdx Outdated Show resolved Hide resolved

Merge branch 'main' into ochafik/sep-1577-sampling-with-tools

958fadf

mintlify bot deployed to staging - docs November 14, 2025 16:21 View deployment

Update sampling.mdx

0fb876c

bhosmer-ant approved these changes Nov 14, 2025

View reviewed changes

bhosmer-ant merged commit 35dde44 into main Nov 14, 2025
6 checks passed

bhosmer-ant deleted the ochafik/sep-1577-sampling-with-tools branch November 14, 2025 16:29

connor4312 mentioned this pull request Nov 14, 2025

Support per-model/per-request tools microsoft/vscode#277472

Open

dsp-ant reviewed Nov 14, 2025

View reviewed changes

bhosmer-ant mentioned this pull request Nov 14, 2025

address 1796 comments (SEP-1577 Sampling with tools) #1816

Merged

This was referenced Nov 21, 2025

Add Support for SEP-1577 - Sampling With Tools to Inspector modelcontextprotocol/inspector#932

Open

Add Support for SEP-1577 - Sampling With Tools to Everything Server modelcontextprotocol/servers#3040

Open

olaservo mentioned this pull request Dec 30, 2025

feat(everything): add trigger-agentic-sampling tool modelcontextprotocol/servers#3163

Open

12 tasks


		## Tools in Sampling

		Servers can request that the client's LLM use tools during sampling by providing a `tools` array and optional `toolChoice` configuration in their sampling requests. This enables servers to implement agentic behaviors where the LLM can call tools, receive results, and continue the conversation—all within a single sampling request flow.

	Clients MUST declare support for tool use via the `sampling.tools` capability to receive tool-enabled sampling requests. Servers SHOULD NOT send tool-enabled sampling requests to Clients that have not declared support for tool use via the `sampling.tools` capability.
	Clients MUST declare support for tool use via the `sampling.tools` capability to receive tool-enabled sampling requests. Servers MUST NOT send tool-enabled sampling requests to Clients that have not declared support for tool use via the `sampling.tools` capability.


		### Tool Use and Result Balance

		When using tool use in sampling, messages MUST be properly balanced: every assistant message containing `ToolUseContent` blocks must be followed by a user message that consists entirely of `ToolResultContent` blocks, with each tool use (e.g. with `id: $id`) matched by a corresponding tool result (with `toolUseId: $id`), before any other message.

SEP-1577 - Sampling With Tools #1796

SEP-1577 - Sampling With Tools #1796

Conversation

ochafik commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

bhosmer-ant left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ochafik left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

localden commented Nov 14, 2025

Uh oh!

ochafik left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bhosmer-ant left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bhosmer-ant Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bhosmer-ant Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

ochafik commented Nov 11, 2025 •

edited

Loading

bhosmer-ant Nov 14, 2025 •

edited

Loading

bhosmer-ant Nov 14, 2025 •

edited

Loading