MCP Server Instructions

1---
2name: mcp-server-instructions
3description: Write effective MCP server instructions for tool compaction support. Use when creating or updating the `instructions` parameter in MaaSProtectedFastMCP server initialization. Helps LLMs understand when to search for tools, workflow patterns, and cross-feature relationships.
4---
5 
6# MCP Server Instructions
7 
8Write workflow-focused server instructions that help LLMs understand your server's capabilities.
9 
10## What Instructions Are
11 
12The `instructions` field is an optional string in MCP's `InitializeResult` that gets injected into the LLM's system prompt. It helps models understand:
13 
14- How to use your server's tools together
15- When to search for specific tools (with tool compaction)
16- Operational constraints and patterns
17 
18**Evidence**: In controlled testing, well-written instructions improved task success from 60% to 85% - a 25% improvement.
19 
20## Template
21 
22```python
23instructions="""[Server name] for [domain] operations.
24 
25KEY WORKFLOWS:
26- [Name]: [tool1] -> [tool2] -> [tool3]
27- [Name]: [tool1] -> [tool2] (when [condition])
28 
29CONSTRAINTS:
30- [Limit or behavior users need to know]
31- [Input format quirks]
32- [Auto-pagination or chunking behavior]"""
33```
34 
35## What to Include
36 
37Focus on what individual tool descriptions don't convey:
38 
39| Include                      | Example                                               |
40| ---------------------------- | ----------------------------------------------------- |
41| **Cross-tool relationships** | "Always call authenticate before any fetch\_\* tools" |
42| **Operational patterns**     | "Search results expire after 10 minutes"              |
43| **Constraints**              | "Rate limited to 100 requests/minute"                 |
44| **Sequencing**               | "Use get_metadata before fetching large content"      |
45| **Format flexibility**       | "IID accepts: #72, !72, '72', 72"                     |
46 
47## What to Avoid
48 
49| Avoid                       | Why                                      | Instead                          |
50| --------------------------- | ---------------------------------------- | -------------------------------- |
51| Repeating tool descriptions | Already in tool docstrings               | Show how tools work together     |
52| Marketing language          | "comprehensive", "powerful" add no value | State capabilities factually     |
53| Lengthy manuals             | Instructions should be <500 chars        | Be concise and actionable        |
54| Listing all tools           | Tools are discoverable                   | Only mention in workflow context |
55 
56**Bad**: "The search tool searches for files"
57**Good**: "Use search before read to validate paths. Results expire after 10 min."
58 
59## Process
60 
611. **Find tools** - Read server.py, locate all `@app.tool()` decorators
622. **Group by workflow** - Which tools are used together?
633. **Find dependencies** - Which tools need output from others?
644. **Note constraints** - Pagination, size limits, rate limits, formats
655. **Identify non-obvious behaviors** - Auto-pagination, caching, chunking
66 
67## Common Patterns
68 
69- **Search -> Details**: `search_X -> get_X`
70- **List -> Inspect -> Act**: `list_X -> get_X -> update_X`
71- **Metadata First**: `get_X_metadata -> get_X_content` (for large content)
72- **Two-Step Updates**: `get_editmeta -> update_X` (when schema required)
73- **Hierarchical Browse**: `list_parent -> get_parent -> list_children`
74 
75## Examples
76 
77### Good
78 
79```python
80instructions="""GitLab server for repository and CI/CD operations.
81 
82KEY WORKFLOWS:
83- Code Review: list_merge_requests -> get_merge_request -> get_merge_request_diffs
84- Pipeline Debug: list_pipelines_jobs -> get_job_log_metadata -> get_job_log_paginated
85- File Browse: search_repositories -> get_repo_tree -> get_file_contents
86 
87CONSTRAINTS:
88- MR IID accepts: #72, !72, "72", 72
89- Job logs >500KB auto-paginate to last 2000 lines
90- Use get_job_log_metadata before fetching large logs"""
91```
92 
93### Bad
94 
95```python
96# Too vague - doesn't help LLM understand capabilities
97instructions="GitLab MCP Server that validates tokens via Authorization Server introspection"
98 
99# Marketing fluff - no actionable information
100instructions="""This is a comprehensive GitLab integration server that provides
101powerful capabilities for working with GitLab repositories..."""
102 
103# Tool listing - just repeats what's already in tool descriptions
104instructions="""Available tools: search_repos, list_projects, get_project,
105get_file, list_commits, get_commit, list_issues, get_issue..."""
106```
107 
108## Limitations
109 
110Instructions are probabilistic guidance, not deterministic rules. They improve LLM behavior but cannot guarantee it. Don't rely on instructions for security-critical or privacy-sensitive enforcement.
111