| name | mcp-server-instructions |
| description | 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. |
MCP Server Instructions
Write workflow-focused server instructions that help LLMs understand your server's capabilities.
What Instructions Are
The instructions field is an optional string in MCP's InitializeResult that gets injected into the LLM's system prompt. It helps models understand:
- How to use your server's tools together
- When to search for specific tools (with tool compaction)
- Operational constraints and patterns
Evidence: In controlled testing, well-written instructions improved task success from 60% to 85% - a 25% improvement.
Template
instructions="""[Server name] for [domain] operations.
KEY WORKFLOWS:
- [Name]: [tool1] -> [tool2] -> [tool3]
- [Name]: [tool1] -> [tool2] (when [condition])
CONSTRAINTS:
- [Limit or behavior users need to know]
- [Input format quirks]
- [Auto-pagination or chunking behavior]"""
What to Include
Focus on what individual tool descriptions don't convey:
| Include | Example |
|---|
| Cross-tool relationships | "Always call authenticate before any fetch_* tools" |
| Operational patterns | "Search results expire after 10 minutes" |
| Constraints | "Rate limited to 100 requests/minute" |
| Sequencing | "Use get_metadata before fetching large content" |
| Format flexibility | "IID accepts: #72, !72, '72', 72" |
What to Avoid
| Avoid | Why | Instead |
|---|
| Repeating tool descriptions | Already in tool docstrings | Show how tools work together |
| Marketing language | "comprehensive", "powerful" add no value | State capabilities factually |
| Lengthy manuals | Instructions should be <500 chars | Be concise and actionable |
| Listing all tools | Tools are discoverable | Only mention in workflow context |
Bad: "The search tool searches for files"
Good: "Use search before read to validate paths. Results expire after 10 min."
Process
- Find tools - Read server.py, locate all
@app.tool() decorators
- Group by workflow - Which tools are used together?
- Find dependencies - Which tools need output from others?
- Note constraints - Pagination, size limits, rate limits, formats
- Identify non-obvious behaviors - Auto-pagination, caching, chunking
Common Patterns
- Search -> Details:
search_X -> get_X
- List -> Inspect -> Act:
list_X -> get_X -> update_X
- Metadata First:
get_X_metadata -> get_X_content (for large content)
- Two-Step Updates:
get_editmeta -> update_X (when schema required)
- Hierarchical Browse:
list_parent -> get_parent -> list_children
Examples
Good
instructions="""GitLab server for repository and CI/CD operations.
KEY WORKFLOWS:
- Code Review: list_merge_requests -> get_merge_request -> get_merge_request_diffs
- Pipeline Debug: list_pipelines_jobs -> get_job_log_metadata -> get_job_log_paginated
- File Browse: search_repositories -> get_repo_tree -> get_file_contents
CONSTRAINTS:
- MR IID accepts: #72, !72, "72", 72
- Job logs >500KB auto-paginate to last 2000 lines
- Use get_job_log_metadata before fetching large logs"""
Bad
instructions="GitLab MCP Server that validates tokens via Authorization Server introspection"
instructions="""This is a comprehensive GitLab integration server that provides
powerful capabilities for working with GitLab repositories..."""
instructions="""Available tools: search_repos, list_projects, get_project,
get_file, list_commits, get_commit, list_issues, get_issue..."""
Limitations
Instructions 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.
