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:

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.