SEP-1577 - Sampling With Tools by ochafik · Pull Request #1796 · modelcontextprotocol/modelcontextprotocol

and others added 6 commits

November 7, 2025 19:45
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 <noreply@anthropic.com>
… 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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
- 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 <noreply@anthropic.com>

@ochafik

This was referenced

Nov 11, 2025

bhosmer-ant

@ochafik

ochafik

@ochafik @claude

…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 <noreply@anthropic.com>

@ochafik @bhosmer-ant

Co-authored-by: bhosmer-ant <basil@anthropic.com>

@ochafik

@localden localden linked an issue

Nov 12, 2025

that may be closed by this pull request

@ochafik

@ochafik

@ochafik

@localden

@localden

@localden

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

@localden

@ochafik

@ochafik

ochafik

@localden

@localden

bhosmer-ant

@bhosmer-ant bhosmer-ant deleted the ochafik/sep-1577-sampling-with-tools branch

November 14, 2025 16:29

dsp-ant

This was referenced

Nov 19, 2025

This was referenced

Nov 21, 2025