Skip to content

docs: improve discoverability and docs for the instructions parameter #3311

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
QiYuyyds wants to merge 1 commit into
base: main
Choose a base branch
from
+48 −0
Open

docs: improve discoverability and docs for the instructions parameter #3311

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions docs/get-started/first-steps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,22 @@ Notice what isn't there. `completions` (argument autocomplete for resource templ
`Client(mcp)` is the same in-memory client every example in these docs is tested with, and
it's how you'll test yours. It gets a whole page: **[Testing](testing.md)**.

## Server instructions

When a client connects, the server sends an `InitializeResult` during the
handshake. Its `instructions` field is a free-text string that clients can use
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"

@cubic-dev-ai cubic-dev-ai Bot Aug 15, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"

--8<-- "docs_src/first_steps/tutorial002.py"
```

This is the simplest way to express "these tools go together" or "follow this
order" without building a dedicated grouping API. See the
[specification](https://modelcontextprotocol.io/specification/2025-06-18/schema#initializeresult-instructions)
for the wire format.

## What you did not write

Look back over this page. You wrote three small Python functions. You did **not** write:
Expand Down
22 changes: 22 additions & 0 deletions docs_src/first_steps/tutorial002.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
from mcp.server import MCPServer

mcp = MCPServer(
name="Demo",
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."

@cubic-dev-ai cubic-dev-ai Bot Aug 15, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>

),
)


@mcp.tool()
def read_status() -> str:
"""Read the current system status."""
return "ok"


@mcp.tool()
def write_record(data: str) -> str:
"""Persist a record."""
return f"wrote: {data}"
10 changes: 10 additions & 0 deletions src/mcp/server/mcpserver/server.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,16 @@ async def wrap(_: Server[LifespanResultT]) -> AsyncIterator[LifespanResultT]:


class MCPServer(Generic[LifespanResultT]):
"""A more ergonomic interface for MCP servers.

Exposes tools, resources, and prompts to connected clients, and declares
capabilities automatically based on what you register.

The ``instructions`` parameter returns free-text guidance to the client in
the ``InitializeResult`` handshake. Use it to describe tool groupings,
workflows, or usage hints for the model without a dedicated grouping API.
"""

def __init__(
self,
name: str | None = None,
Expand Down
Loading