mcp: implement sampling with tools (#699)

Summary

Add support for tool use within sampling requests, as described in the
MCP 2025-11-25 spec's sampling.tools capability.
  New types

  Content types:
- ToolUseContent — represents a tool invocation request from the
assistant
- ToolResultContent — represents the result of a tool invocation, with
nested []Content for the result blocks

  Capability types:
  - SamplingCapabilities gains Tools and Context sub-fields
  - SamplingToolsCapabilities, SamplingContextCapabilities

  Tool-enabled sampling (parallel tool calls):
- CreateMessageWithToolsParams with SamplingMessageV2 (supports array
content)
  - CreateMessageWithToolsResult (supports array content)
  - ToolChoice — controls tool invocation mode (auto, required, none)
  - ServerSession.CreateMessageWithTools
  - ClientOptions.CreateMessageWithToolsHandler

  Design

Following the TypeScript SDK's pattern, tool-enabled sampling uses
separate types from basic sampling to avoid breaking the existing API.
The basic CreateMessage/CreateMessageResult path
   is unchanged.

Both paths share the same wire method (sampling/createMessage) and go
through the method info table. The table uses the broader
CreateMessageWithToolsResult type internally;
CreateMessage downconverts (erroring if multiple content blocks are
returned). This is documented as a rough edge to unify in v2.

Setting CreateMessageWithToolsHandler automatically infers the
sampling.tools capability. It is a panic to set both
CreateMessageHandler and CreateMessageWithToolsHandler.

  References

-
https://modelcontextprotocol.io/specification/2025-11-25/client/sampling
- TypeScript SDK: CreateMessageResultWithToolsSchema /
CreateMessageRequestParamsWithTools

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

docs/rough_edges.md

@@ -45,3 +45,17 @@ v2.
   **Workaround**: to advertise no capabilities, set
   `ServerOptions.Capabilities` or `ClientOptions.Capabilities` to an empty
   `&ServerCapabilities{}` or `&ClientCapabilities{}` respectively.
+
+- `CreateMessageResult.Content` is singular `Content`, but the 2025-11-25 spec
+  allows `content` to be a single block or an array (for parallel tool calls).
+  We added `CreateMessageResultWithTools` (with `Content []Content`) as a
+  workaround, matching the TypeScript SDK's approach. In v2,
+  `CreateMessageResult` should use `[]Content` directly. Similarly,
+  `SamplingMessage.Content` should become `[]Content` to support sending
+  multiple tool_result blocks in a single user message.
+
+- We didn't actually need CallToolParams and CallToolParamsRaw, since even when
+  we're unmarshalling into a custom Go type (for the mcp.AddTool convenience
+  wrapper) we need to first unmarshal into a `map[string]any` in order to do
+  server-side validation of required fields. CallToolParams could have just had
+  a map[string]any.