Token Optimization Best Practices

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: token-optimization for 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 performance skill 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 100

Tool usage:

• execute_query: ALWAYS use limit parameter (default: 1000)
• get_schema(compact=true): For DB structure overview
• describe_table: Before exploratory queries
• explain_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 overview
• list_api_paths(limit=50): For endpoint list
• get_api_models(compact=true): For model list without full schema
• search_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 search
• fetch_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 logs
• find_errors(limit=50): For error debugging
• parse_logs(limit=200): Only if full analysis needed

security-scanner

Tool usage:

• scan_dependencies: Prefer over scan_all
• scan_secrets: Faster than full scan
• scan_all: Only for complete audits

code-quality

Tool usage:

• analyze_complexity(path="src/specific/file.ts"): Target specific files
• find_duplicates(minLines=10): Filter significant duplicates only
• code_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=true if 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: Use mcp__documentation__fetch_docs with technology: token-optimization for advanced optimization techniques.