docs: improve discoverability and docs for the instructions parameter - #3311
Open
QiYuyyds wants to merge 1 commit into
Open
docs: improve discoverability and docs for the instructions parameter#3311QiYuyyds wants to merge 1 commit into
QiYuyyds wants to merge 1 commit into
Conversation
There was a problem hiding this comment.
2 issues found across 3 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/get-started/first-steps.md">
<violation number="1" location="docs/get-started/first-steps.md:126">
P3: The new instructions example highlights `name="Demo"` instead of the `instructions` argument, which makes the key parameter harder to spot. Update `hl_lines` to point at the `instructions=` line.</violation>
</file>
<file name="docs_src/first_steps/tutorial002.py">
<violation number="1" location="docs_src/first_steps/tutorial002.py:8">
P2: The example instructions reference `batch_write`, but this tutorial only defines `read_status` and `write_record`. Replace that text with guidance that matches the tools shown, or add a `batch_write` tool.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| instructions=( | ||
| "This server exposes two groups of tools: 'read_*' for fetching data " | ||
| "and 'write_*' for persisting it. Always call a read tool before a " | ||
| "write tool, and prefer batch_write over repeated single writes." |
There was a problem hiding this comment.
P2: The example instructions reference batch_write, but this tutorial only defines read_status and write_record. Replace that text with guidance that matches the tools shown, or add a batch_write tool.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs_src/first_steps/tutorial002.py, line 8:
<comment>The example instructions reference `batch_write`, but this tutorial only defines `read_status` and `write_record`. Replace that text with guidance that matches the tools shown, or add a `batch_write` tool.</comment>
<file context>
@@ -0,0 +1,22 @@
+ instructions=(
+ "This server exposes two groups of tools: 'read_*' for fetching data "
+ "and 'write_*' for persisting it. Always call a read tool before a "
+ "write tool, and prefer batch_write over repeated single writes."
+ ),
+)
</file context>
| to guide the model on how to use your server's tools — for example, grouping | ||
| related tools or describing a workflow: | ||
|
|
||
| ```python title="server.py" hl_lines="4" |
There was a problem hiding this comment.
P3: The new instructions example highlights name="Demo" instead of the instructions argument, which makes the key parameter harder to spot. Update hl_lines to point at the instructions= line.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/get-started/first-steps.md, line 126:
<comment>The new instructions example highlights `name="Demo"` instead of the `instructions` argument, which makes the key parameter harder to spot. Update `hl_lines` to point at the `instructions=` line.</comment>
<file context>
@@ -116,6 +116,22 @@ Notice what isn't there. `completions` (argument autocomplete for resource templ
+to guide the model on how to use your server's tools — for example, grouping
+related tools or describing a workflow:
+
+```python title="server.py" hl_lines="4"
+--8<-- "docs_src/first_steps/tutorial002.py"
+```
</file context>
Suggested change
| ```python title="server.py" hl_lines="4" | |
| ```python title="server.py" hl_lines="5" |
QiYuyyds
force-pushed
the
docs/instructions-param
branch
from
August 15, 2026 07:37
db0f5b0 to
024bac8
Compare
Add a class docstring to MCPServer documenting the instructions parameter, and a new Server instructions section to the first-steps guide, with a concrete example showing how to use instructions to express tool grouping and workflow guidance. Closes modelcontextprotocol#1464
QiYuyyds
force-pushed
the
docs/instructions-param
branch
from
August 15, 2026 07:47
024bac8 to
291811d
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Improve discoverability and documentation of the
instructionsparameter onMCPServer(which flows through toInitializeResult.instructions).Closes #1464
Changes
instructionsparameter inMCPServer.__init__,explaining its purpose and hinting at tool-grouping / workflow use cases.
docs/get-started/first-steps.mdwith a concrete example showing how to use
instructionsto express toolgrouping and ordering guidance.
docs_src/first_steps/tutorial002.pyas the referenced example.Checklist
instructionsonInitializeResult#1464 (documentation, ready for work, P1)--8<--include pattern🤖 AI-assisted: This PR was drafted with AI assistance. I (the contributor)
have reviewed the diff, understand the change, and confirm the example
accurately demonstrates the
instructionsparameter.