docs: improve discoverability and docs for the instructions parameter

[QiYuyyds]

Summary

Improve discoverability and documentation of the instructions parameter on
MCPServer (which flows through to InitializeResult.instructions).

Closes #1464

Changes

• Added a docstring to the instructions parameter in MCPServer.__init__,
  explaining its purpose and hinting at tool-grouping / workflow use cases.
• Added a new "Server instructions" section to docs/get-started/first-steps.md
  with a concrete example showing how to use instructions to express tool
  grouping and ordering guidance.
• Added docs_src/first_steps/tutorial002.py as the referenced example.

Checklist

• Linked issue: Improve docs on how to use instructions on InitializeResult #1464 (documentation, ready for work, P1)
• Change is minimal and focused
• Docs example follows the existing --8<-- include pattern
• No code logic changes (docs + docstring only)

---

🤖 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 instructions parameter.

[cubic-dev-ai]

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>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

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>

[cubic-dev-ai]

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"

[github-actions]

Thanks for the contribution. This repository only keeps pull requests open when they're linked to an issue that a maintainer has assigned to the author — CONTRIBUTING.md explains why and how we work. This PR has been closed for now because you aren't currently assigned to #1464.

If a maintainer would like this change as a PR from you, they'll assign you to #1464 and this PR will reopen automatically — there's nothing more you need to do. (If you opened the issue, this PR already shows up on its timeline.)

There's no need to open a new PR — this one will be reopened. While it's closed, please push any updates as new commits rather than force-pushing, since GitHub can't reopen a PR whose branch has been rewritten.

Maintainers: reopening this PR, removing the missing-issue-link label, or adding bypass-issue-check bypasses the check.