Align sampling specification XML docs with spec revision d165cd6

[Copilot]

The MCP spec was revised to clarify client obligations for sampling parameters. The SDK implementation is correct, but XML docs needed updates.

Changes Made

MaxTokens - Clarified that the client must respect maxTokens as a limit, while noting the client can choose to sample fewer tokens than requested.

Temperature - Documented randomness control behavior and that client may modify/ignore

StopSequences, Metadata - Added that client may modify/ignore these parameters

Messages - Noted that message lists should not be retained between separate sampling requests

StopReason.endTurn - Updated description to "participant is yielding the conversation" per spec wording

Style

All RFC 2119 keywords (must, should not, may) use lowercase in XML documentation comments per SDK conventions.

Original prompt

Context

The MCP specification was updated in modelcontextprotocol/modelcontextprotocol@d165cd6 ("Revise sampling specification to define all valid request and response fields (#531)"). The C# SDK already has all the correct types, properties, and serialization behavior, but several XML doc comments should be updated to match the revised spec language.

Changes needed

All changes are XML doc comment updates only — no functional code changes.

1. CreateMessageRequestParams.Temperature (High priority)

File: src/ModelContextProtocol.Core/Protocol/CreateMessageRequestParams.cs

Current:

/// <summary>
/// Gets or sets the temperature to use for sampling, as requested by the server.
/// </summary>
[JsonPropertyName("temperature")]
public float? Temperature { get; set; }

Update the doc to describe what temperature does and clarify client obligations per the spec:

• "Controls randomness in model responses. Higher values produce higher randomness, and lower values produce more stable output."
• "The valid range depends on the model provider."
• "The client MAY modify or ignore this value."

2. CreateMessageRequestParams.MaxTokens (High priority — current doc contradicts the spec)

File: src/ModelContextProtocol.Core/Protocol/CreateMessageRequestParams.cs

Current remarks say: "The client can choose to sample fewer tokens than requested."

The updated spec says: "The client MUST respect the maxTokens parameter."

Remove the contradictory remark and replace it with language indicating the client MUST respect this parameter.

3. CreateMessageRequestParams.StopSequences (Low priority)

File: src/ModelContextProtocol.Core/Protocol/CreateMessageRequestParams.cs

Add a remark noting that the client MAY modify or ignore stop sequences, per the spec: "The client MAY modify or ignore temperature, stopSequences and metadata."

4. CreateMessageRequestParams.Metadata (Low priority)

File: src/ModelContextProtocol.Core/Protocol/CreateMessageRequestParams.cs

Add a remark noting that the client MAY modify or ignore metadata.

5. SamplingMessage class or CreateMessageRequestParams.Messages (Low priority)

File: src/ModelContextProtocol.Core/Protocol/SamplingMessage.cs or src/ModelContextProtocol.Core/Protocol/CreateMessageRequestParams.cs

Add a remark that the list of messages in a sampling request SHOULD NOT be retained between separate requests, per the spec.

6. CreateMessageResult.StopReason — endTurn description (Very low priority)

File: src/ModelContextProtocol.Core/Protocol/CreateMessageResult.cs

Optionally update the endTurn description from "The model naturally completed its response." to "The participant is yielding the conversation to the other party." to match the spec's exact wording.

This pull request was created from Copilot chat.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[stephentoub]

@copilot it's ok for the client to send fewer. I'm not sure why you removed the existing comment. Also the MUST shouldn't be capitalized

[Copilot]

Fixed in 086408a - restored the original comment about client choosing fewer tokens and changed capitalization to lowercase "must"

[stephentoub]

@copilot here as well and anywhere sense you do it, don't capitalize with all caps like this

[Copilot]

Fixed in 086408a - changed all RFC 2119 keywords (MUST, SHOULD NOT, MAY) to lowercase throughout the file