feat: implement SEP-1577 sampling with tools support

Author: DaleSeo

PR_DESCRIPTION.md

@@ -0,0 +1,129 @@
+# Implement SEP-1577: Sampling With Tools
+
+## Summary
+
+This PR implements [SEP-1577: Sampling With Tools](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1577), which adds tool calling support to `sampling/createMessage` requests. This allows MCP servers to run agentic loops using the client's tokens while maintaining user supervision.
+
+Closes #552
+
+## Changes
+
+### New Types
+
+#### Tool Choice Configuration
+- **`ToolChoiceMode`**: Enum with values `Auto`, `Required`, `None` to control how the model handles tool calling
+- **`ToolChoice`**: Configuration struct with helper constructors (`ToolChoice::auto()`, `ToolChoice::required()`, `ToolChoice::none()`)
+
+#### Tool Content Types
+- **`ToolUseContent`**: Represents a tool call request from the assistant
+  - `id`: Unique identifier for the tool call
+  - `name`: Name of the tool to invoke
+  - `input`: Arguments for the tool call
+  
+- **`ToolResultContent`**: Represents tool execution results from the user
+  - `tool_use_id`: References the original tool call
+  - `content`: Result content blocks
+  - `structured_content`: Optional structured output
+  - `is_error`: Whether the tool execution failed
+
+#### Sampling Content Wrapper
+- **`SamplingContent<T>`**: Generic wrapper supporting both single and array content per SEP-1577 spec
+  - Implements `From<T>` and `From<Vec<T>>` for easy construction
+  - Helper methods: `into_vec()`, `first()`, `iter()`, `is_empty()`, `len()`
+
+- **`SamplingMessageContent`**: Unified enum for all sampling message content types
+  - `Text`, `Image`, `Audio`, `ToolUse`, `ToolResult` variants
+  - Accessor methods: `as_text()`, `as_tool_use()`, `as_tool_result()`
+
+#### Sampling Capability
+- **`SamplingCapability`**: Structured capability for sampling support
+  - `tools`: Enables `tools` and `toolChoice` parameters in CreateMessageRequest
+  - `context`: Enables `includeContext` with values other than "none" (soft-deprecated per SEP-1577)
+
+### Updated Types
+
+#### `CreateMessageRequestParams`
+Added two new optional fields:
+- `tools: Option<Vec<Tool>>` - Tools available for the model to call
+- `tool_choice: Option<ToolChoice>` - Configuration for tool selection behavior
+
+#### `CreateMessageResult`
+Added new stop reason constant:
+- `STOP_REASON_TOOL_USE = "toolUse"` - Indicates the model wants to use a tool
+
+#### `SamplingMessage`
+- Updated `content` field from `Content` to `SamplingContent<SamplingMessageContent>`
+- Added convenience constructors:
+  - `SamplingMessage::user_text(text)`
+  - `SamplingMessage::assistant_text(text)`
+  - `SamplingMessage::user_tool_result(tool_use_id, content)`
+  - `SamplingMessage::assistant_tool_use(id, name, input)`
+
+#### `ClientCapabilities`
+- Changed `sampling` field from `Option<JsonObject>` to `Option<SamplingCapability>`
+- Added builder methods:
+  - `enable_sampling_tools()` - Advertise tool calling support
+  - `enable_sampling_context()` - Advertise context inclusion support
+
+## Usage Example
+
+```rust
+use rmcp::model::*;
+
+// Create a sampling request with tools
+let params = CreateMessageRequestParams {
+    messages: vec![SamplingMessage::user_text("What's the weather in SF?")],
+    tools: Some(vec![
+        Tool::new("get_weather", "Get current weather", schema),
+    ]),
+    tool_choice: Some(ToolChoice::auto()),
+    max_tokens: 1000,
+    // ... other fields
+};
+
+// Handle tool use response
+if result.stop_reason == Some("toolUse".to_string()) {
+    if let Some(tool_use) = result.message.content.first()
+        .and_then(|c| c.as_tool_use()) 
+    {
+        // Execute the tool and send result back
+        let tool_result = SamplingMessage::user_tool_result(
+            &tool_use.id,
+            vec![Content::text("72°F and sunny")],
+        );
+    }
+}
+
+// Advertise capability
+let capabilities = ClientCapabilities::builder()
+    .enable_sampling()
+    .enable_sampling_tools()
+    .build();
+```
+
+## Testing
+
+Added 15 new tests covering:
+- Tool choice serialization/deserialization
+- Sampling capability configuration
+- Tool use/result content serialization
+- Sampling messages with tool use/result
+- Create message result with tool use stop reason
+- Full sampling with tools workflow
+- Client capability builder methods
+
+All existing tests updated to use the new API and continue to pass.
+
+## Breaking Changes
+
+- `SamplingMessage.content` type changed from `Content` to `SamplingContent<SamplingMessageContent>`
+  - Migration: Use `SamplingMessage::user_text()` or `SamplingMessage::assistant_text()` helpers
+  - Or access text via `message.content.first().and_then(|c| c.as_text())`
+
+- `ClientCapabilities.sampling` type changed from `Option<JsonObject>` to `Option<SamplingCapability>`
+  - Empty `{}` JSON still deserializes correctly to `SamplingCapability { tools: None, context: None }`
+
+## Specification Reference
+
+- SEP-1577: https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1577
+- Rust SDK Tracking Issue: https://github.com/modelcontextprotocol/rust-sdk/issues/552