Token Optimization Best Practices
Deep Knowledge: Usemcp__documentation__fetch_docswith technology:token-optimizationfor comprehensive documentation.
Guidelines for minimizing token consumption in MCP server and external tool interactions.
When NOT to Use This Skill
This skill focuses on API/tool call optimization. Do NOT use for:
- Runtime performance - Use
performanceskill for speed optimization - Code minification - Use build tools (Vite, Webpack, etc.)
- Database query optimization - Use database-specific skills
- Algorithm efficiency - Use computer science fundamentals
- Prompt engineering - This is about tool usage, not prompt design
General Principles
| Principle | Description |
|---|---|
| Lazy Loading | Load information only when strictly necessary |
| Minimal Output | Request only needed data, use limit and compact parameters |
| Progressive Detail | Start with overview/summary, drill down only if needed |
| Cache First | Check if information is already in context before external calls |
Anti-Patterns
| Anti-Pattern | Why It's Bad | Token-Efficient Solution |
|---|---|---|
| SELECT * | Returns unnecessary columns | Specify exact columns needed |
| No LIMIT clause | Returns entire dataset | Always add LIMIT (e.g., 100) |
| Full schema requests | Returns massive specs | Use compact=true or format="summary" |
| Recursive documentation fetch | Fetches entire doc tree | Use search_docs with specific query |
| Fetching full logs | Returns thousands of lines | Use tail_logs or find_errors with limit |
| Copy-paste documentation | Duplicates content | Summarize and reference, don't quote verbatim |
| No pagination | Returns all results at once | Use offset/limit for large datasets |
| Full API schema exploration | Multi-MB specifications | Get endpoint list first, details on-demand |
Quick Troubleshooting
| Issue | Check | Solution |
|---|---|---|
| Large MCP response | Output size > 2000 tokens | Add limit parameter, use compact format |
| Repeated API calls | Calling same tool multiple times | Cache results in conversation context |
| Slow context buildup | Too many tool calls | Batch related queries, use more specific tools |
| Unnecessary documentation fetch | Info already known | Check skill files first, fetch docs as last resort |
| Full table scan results | Database query returns too much | Add WHERE clause and LIMIT |
| Verbose error logs | Full stack traces repeated | Summarize errors, reference line numbers |
MCP Server Patterns
database-query
-- BAD: Query without limits
SELECT * FROM users
-- GOOD: Query with filters and limits
SELECT id, name, email FROM users WHERE active = true LIMIT 100Tool usage:
execute_query: ALWAYS uselimitparameter (default: 1000)get_schema(compact=true): For DB structure overviewdescribe_table: Before exploratory queriesexplain_query: Before complex queries on large tables
api-explorer
-- BAD: Full schema
get_api_schema(format="full")
-- GOOD: Summary only for overview
get_api_schema(format="summary")
-- GOOD: Path list with limit
list_api_paths(limit=50)
-- GOOD: Single endpoint details
get_api_endpoint_details(path="/users/{id}", method="GET")Tool usage:
get_api_schema(format="summary"): For API overviewlist_api_paths(limit=50): For endpoint listget_api_models(compact=true): For model list without full schemasearch_api(limit=10): For targeted searches
documentation
-- BAD: Entire document
fetch_docs(topic="react")
-- GOOD: Targeted search
search_docs(query="useEffect cleanup", maxResults=3)Tool usage:
search_docs(maxResults=3): For specific information searchfetch_docs: Only for very specific topics- Check skill files FIRST before fetching documentation
log-analyzer
-- BAD: All logs
parse_logs(file="/var/log/app.log")
-- GOOD: Recent errors only
find_errors(file="/var/log/app.log", limit=50)
-- GOOD: Tail for live debugging
tail_logs(file="/var/log/app.log", lines=50)Tool usage:
tail_logs(lines=50): For recent logsfind_errors(limit=50): For error debuggingparse_logs(limit=200): Only if full analysis needed
security-scanner
Tool usage:
scan_dependencies: Prefer overscan_allscan_secrets: Faster than full scanscan_all: Only for complete audits
code-quality
Tool usage:
analyze_complexity(path="src/specific/file.ts"): Target specific filesfind_duplicates(minLines=10): Filter significant duplicates onlycode_metrics: Compact output for overview
Pre-Call MCP Checklist
Before calling an MCP tool, verify:
- Do I already have this information in context?
- Can I use a more specific tool instead of a generic one?
- Have I set an appropriate
limit? - Have I used
compact=trueif available? - Is the expected output reasonable (< 2000 tokens)?
Output Format Standards
For code analysis
- Max 5 issues per category
- Snippets max 10 lines
- Use tables for lists
For database queries
- Max 20 rows in direct output
- For results > 20: "Found N rows. First 20:..."
- Compact tabular format
For documentation
- Quote only relevant parts (max 500 characters)
- Link to complete docs instead of copying content
- Summarize instead of quoting verbatim
Efficient Response Examples
Database Query - Compact Output
Found 1523 rows. First 20:
| id | name | status |
|----|------|--------|
| 1 | ... | active |
...
Use offset=20 for next page.API Exploration - Progressive Detail
API has 45 endpoints. Summary by tag:
- users: 8 endpoints
- auth: 5 endpoints
- products: 12 endpoints
...
Use get_api_endpoint_details for specifics.Log Analysis - Focused Output
Found 234 errors in last hour. Top 5 by frequency:
1. ConnectionTimeout: 89 occurrences
2. ValidationError: 45 occurrences
...
Use tail_logs or parse_logs with filters for details.Reference Documentation
Deep Knowledge: Usemcp__documentation__fetch_docswith technology:token-optimizationfor advanced optimization techniques.