docs(sampling): rewrite sampling docs for MCP server builders #515
Conversation
LucaButBoring
force-pushed
the
docs/sampling
branch
from
2b7bc62 to
d5b58ac
Compare
LucaButBoring
force-pushed
the
docs/sampling
branch
from
d5b58ac to
71e61a8
Compare
| const result = await extra.sendRequest( | ||
| { | ||
| method: "sampling/createMessage", | ||
| params: { | ||
| messages: [ | ||
| { | ||
| role: "user", | ||
| content: { | ||
| type: "text", | ||
| text: `Add ${a} and ${b}. Respond with only the sum of the two numbers.`, | ||
| }, | ||
| }, | ||
| ], | ||
| maxTokens: 1000, | ||
| systemPrompt: "You are very good at math.", | ||
| includeContext: "thisServer", | ||
| }, | ||
| }, | ||
| CreateMessageResultSchema | ||
| ); |
There was a problem hiding this comment.
Out of scope for this PR, but we really need a friendlier API. 😆
There was a problem hiding this comment.
Yeah, honestly even the name of the feature ("sampling") doesn't really convey what this is used for, let alone the API itself 😔
There was a problem hiding this comment.
Agreed! If we could unify sampling and elicitation, I would propose the term "solicitation".
Quoth Gemini 2.5 Pro on "elicit" vs "solicit":
- To solicit a response is to request it.
- To elicit a response is to get it (often without a direct request for that specific response).
In essence, "solicit" is about the asking, while "elicit" is about the succeeding in drawing something out.
There was a problem hiding this comment.
I have to disagree that using two very similar sounding words instead will clarify things. :)
There was a problem hiding this comment.
Haha, well the idea is that if we could unify sampling and elicitation into a single mechanism, then we could call that "solicitation". In other words, no "elicitation" (nor "sampling"), just "solicitation".
There was a problem hiding this comment.
@jonathanhefner thanks, I totally misread the comment.
docs/docs/concepts/sampling.mdx
Outdated
| 3. Client samples from an LLM | ||
| 4. Client reviews the completion | ||
| 5. Client returns the result to the server | ||
| Sampling enables agentic patterns such as: |
There was a problem hiding this comment.
From other discussions it seems like this was partly intended to allow a host/client to 'Bring Your Own LLM' if it supports this capability, taking the responsibility away from the Server. This can be useful for simple use cases as well as complex ones.
If I'm a developer reading this guide for the first time, emphasizing complexity right off the bat makes me feel like I'm good to keep ignoring Sampling if I'm not doing anything I consider complex or agentic. Since at the most basic level Sampling is just asking the host to provide a completion from an LLM, should this overview start with a simpler use case of 'my server needs a model' rather than emphasizing 'agentic patterns?'
There was a problem hiding this comment.
I think that's a good idea, I'll rewrite this section.
There was a problem hiding this comment.
Rewrote this section to align more with that framing - the new overview also touches on the explanation from @jerome3o-anthropic here.
LucaButBoring
force-pushed
the
docs/sampling
branch
from
8a00f28 to
5c265c1
Compare
LucaButBoring
changed the title
LucaButBoring
force-pushed
the
docs/sampling
branch
from
64a064c to
ee07b69
Compare
This change rewrites the sampling documentation to explain how sampling in terms of tool calls and demonstrate how to actually implement sampling workflows via the SDK. Most of the existing information has been reorganized into reference-level material. The intent of this change is to document the existing behavior of sampling prior to proposing any specification changes.
Co-authored-by: Jonathan Hefner <jonathan@hefner.pro>
LucaButBoring
force-pushed
the
docs/sampling
branch
from
854c7fd to
b7de769
Compare
|
Given we haven't moved this forward in months, can we close it? I know it's a lot of hard work not making it and I am sorry for that. I think adding more here is still valuable but likely as a tutorial or guide or so. @jonathanhefner maybe can take a look. |
4 participants
This change rewrites the sampling documentation to explain how sampling works in terms of tool calls and demonstrate how to actually implement sampling workflows via the SDK, rather than simply explaining the message format (which the specification is already capable of addressing). Most of the existing information has been reorganized into reference-level material. I also added a mention of the supported
audiomessage type, which wasn't documented before.This is related to #503. The intent of this change is to document the existing behavior of sampling prior to proposing any specification changes.
I suggest reading this in split diff view rather than the unified view 😔
Motivation and Context
In contrast to the current tools documentation, the sampling documentation is currently structured like an API reference, and has little to no information on how to actually leverage sampling for useful tasks. This PR rewrites the documentation to better convey sampling to developers unfamiliar with the protocol.
How Has This Been Tested?
Documentation tested with
npm run serve:docs. The main implementation sample has been manually tested.Breaking Changes
N/A
Types of changes
Checklist
Additional context
I tried to cut down the error-handling/limitations/best-practices/security sections to consolidate them and limit them to specific and non-generic statements, but I'm not convinced they're well-written even after these revisions. Open to suggestions on how to handle these.