mcp-server-instructions

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

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

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

# 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.