---
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
```python
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
1. **Find tools** - Read server.py, locate all `@app.tool()` decorators
2. **Group by workflow** - Which tools are used together?
3. **Find dependencies** - Which tools need output from others?
4. **Note constraints** - Pagination, size limits, rate limits, formats
5. **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
```python
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
```python
# Too vague - doesn't help LLM understand capabilities
instructions="GitLab MCP Server that validates tokens via Authorization Server introspection"
# Marketing fluff - no actionable information
instructions="""This is a comprehensive GitLab integration server that provides
powerful capabilities for working with GitLab repositories..."""
# Tool listing - just repeats what's already in tool descriptions
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.
