Improve docs on how to use `instructions` on `InitializeResult`

[felixweinberger]

Question

Lots of people want tool bundling / grouping / namespaces to guide servers how to use tools together.

We should make instructions more obvious and have examples for how to use it - maybe this can address a lot of requests for bundling and namespaces if it's more obvious this is something you can do.

https://modelcontextprotocol.io/specification/2025-06-18/schema#initializeresult-instructions

Additional Context

No response

[ChenyangLi4288]

Hi Felix,

If I am trying to provide with more obvious examples. Should I open a PR to modelcontextprotocol and edit the 'draft' version?

Thanks!

[maxisbey]

Hi Felix,

If I am trying to provide with more obvious examples. Should I open a PR to modelcontextprotocol and edit the 'draft' version?

Thanks!

I think this is more about how to do it in the Python SDK rather than the protocol itself. If you'd like to make a PR for this repo with examples for how to use instructions with the SDK then feel free!

[ryanwilliams90]

Hi — happy to take this on. Plan:

1. Add an example snippet examples/snippets/servers/instructions_example.py showing instructions= on MCPServer used to describe how a small set of related tools work together (the bundling/workflow case).
2. Add a short Server instructions section to README.v2.md (and reference it from the snippet) explaining when to use instructions, with concrete examples for tool-bundling and domain-context use cases.
3. No public-API changes — purely docs and an example.

I'll target main. Could you assign the issue to me?

[Joosboy]

Hi! I have implemented this documentation improvement. Since pull request creation is currently restricted on this repository, I have pushed the changes to my fork branch: https://github.com/Joosboy/python-sdk/tree/docs-server-instructions-1464

Please let me know if a maintainer can open the PR or pull these changes. Thanks!