Clarify request-scoped tool semantics in CreateMessageRequestParams

[Copilot]

Per spec commit d6c28ab, tools in sampling/createMessage requests are scoped to that request and need not correspond to server-registered tools. The existing XML docs didn't reflect this.

Changes

• Tools property: Added remarks clarifying request-scoped semantics and independence from tools/list
• ToolChoice property: Added remarks linking behavior to request-scoped Tools

/// <summary>
/// Gets or sets tools that the model can use during generation.
/// </summary>
/// <remarks>
/// The tool definitions in this array are scoped to this sampling request.
/// They do not need to correspond to tools registered on the server via <see cref="RequestMethods.ToolsList"/>.
/// </remarks>
[JsonPropertyName("tools")]
public IList<Tool>? Tools { get; set; }

Original prompt

Context

Spec commit d6c28ab5e56a3c2978a2b79552a0b48c69cb2cfb (merged via PR #2217) clarified that the tools array in a sampling/createMessage request is scoped to that specific sampling request — the tool definitions don't need to correspond to tools registered on the server (via tools/list). This was a source of confusion discussed in the community (issue #1988).

What to change

Update the XML doc comments on CreateMessageRequestParams.Tools and CreateMessageRequestParams.ToolChoice in src/ModelContextProtocol.Core/Protocol/CreateMessageRequestParams.cs to reflect this clarification.

Tools property

Add a <remarks> block clarifying the scoping:

/// <summary>
/// Gets or sets tools that the model can use during generation.
/// </summary>
/// <remarks>
/// The tool definitions in this array are scoped to this sampling request.
/// They do not need to correspond to tools registered on the server via <see cref="RequestMethods.ToolsList"/>.
/// </remarks>
[JsonPropertyName("tools")]
public IList<Tool>? Tools { get; set; }

ToolChoice property

Add a <remarks> block tying it to the request-scoped tools:

/// <summary>
/// Gets or sets controls for how the model uses tools.
/// </summary>
/// <remarks>
/// This controls whether and how the model uses the request-scoped <see cref="Tools"/> during sampling.
/// </remarks>
[JsonPropertyName("toolChoice")]
public ToolChoice? ToolChoice { get; set; }

No functional or behavioral changes are needed — this is purely a documentation update.

This pull request was created from Copilot chat.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.