token-optimization

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Token Optimization Best Practices

Token优化最佳实践

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.

深度知识：调用
mcp__documentation__fetch_docs
并指定technology参数为
token-optimization
可获取完整文档。

本指南用于在MCP服务器与外部工具交互时最小化Token消耗。

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

本技能聚焦于API/工具调用优化，请勿用于以下场景：

运行时性能优化：速度优化请使用
```
performance
```
技能
代码压缩：请使用构建工具（Vite、Webpack等）
数据库查询优化：请使用数据库专属技能
算法效率优化：请使用计算机科学基础相关技能
提示词工程：本内容针对工具使用，而非提示词设计

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

原则	描述
懒加载	仅在绝对必要时加载信息
最小输出	仅请求所需数据，使用 `limit` 和 `compact` 参数
渐进式详情	先从概览/摘要入手，仅在需要时深入查询
缓存优先	发起外部调用前先检查上下文中是否已有相关信息

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

反模式	弊端	Token高效解决方案
SELECT *	返回不必要的列	指定需要的精确列
无LIMIT子句	返回整个数据集	始终添加LIMIT（例如100）
全量schema请求	返回超大规模的规范说明	使用 `compact=true` 或 `format="summary"`
递归拉取文档	拉取完整的文档树	搭配具体查询使用 `search_docs`
拉取全量日志	返回数千行日志内容	使用带limit参数的 `tail_logs` 或 `find_errors`
复制粘贴文档内容	内容重复	做总结并引用来源，不要逐字引用
无分页	一次性返回所有结果	针对大数据集使用offset/limit分页
全量API schema探查	返回数MB的规范文档	先获取接口列表，按需查询详情

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响应体积过大	输出大小超过2000 tokens	添加 `limit` 参数，使用紧凑格式
重复API调用	多次调用同一个工具	在会话上下文中缓存结果
上下文累积速度过快	工具调用次数过多	批量处理相关查询，使用更精准的工具
不必要的文档拉取	所需信息已知	先检查技能文件，最后再拉取文档
全表扫描结果	数据库查询返回数据过多	添加WHERE子句和LIMIT
冗余错误日志	完整栈追踪重复出现	总结错误内容，标注行号即可

MCP Server Patterns

MCP服务器模式

database-query

sql

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

sql

-- 反面示例：无限制的查询
SELECT * FROM users

-- 正面示例：带过滤条件和限制的查询
SELECT id, name, email FROM users WHERE active = true LIMIT 100

工具使用规范：

```
execute_query
```
：必须使用
```
limit
```
参数（默认值：1000）
```
get_schema(compact=true)
```
：用于获取数据库结构概览
```
describe_table
```
：在探查类查询前调用
```
explain_query
```
：在大表上执行复杂查询前调用

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

-- 反面示例：拉取全量schema
get_api_schema(format="full")

-- 正面示例：仅拉取概览摘要
get_api_schema(format="summary")

-- 正面示例：带限制的接口列表查询
list_api_paths(limit=50)

-- 正面示例：单个接口详情查询
get_api_endpoint_details(path="/users/{id}", method="GET")

工具使用规范：

```
get_api_schema(format="summary")
```
：用于获取API概览
```
list_api_paths(limit=50)
```
：用于获取接口列表
```
get_api_models(compact=true)
```
：用于获取模型列表，无需全量schema
```
search_api(limit=10)
```
：用于定向搜索

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

-- 反面示例：拉取完整文档
fetch_docs(topic="react")

-- 正面示例：定向搜索
search_docs(query="useEffect cleanup", maxResults=3)

工具使用规范：

```
search_docs(maxResults=3)
```
：用于特定信息搜索
```
fetch_docs
```
：仅针对非常具体的主题使用
拉取文档前优先检查技能文件

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

-- 反面示例：拉取全部日志
parse_logs(file="/var/log/app.log")

-- 正面示例：仅拉取近期错误
find_errors(file="/var/log/app.log", limit=50)

-- 正面示例：尾部日志用于实时调试
tail_logs(file="/var/log/app.log", lines=50)

工具使用规范：

```
tail_logs(lines=50)
```
：用于查看近期日志
```
find_errors(limit=50)
```
：用于错误调试
```
parse_logs(limit=200)
```
：仅在需要全量分析时使用

security-scanner

Tool usage:

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

工具使用规范：

优先使用
```
scan_dependencies
```
，而非
```
scan_all
```
```
scan_secrets
```
比全量扫描速度更快
```
scan_all
```
仅用于完整审计场景

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

工具使用规范：

analyze_complexity(path="src/specific/file.ts")

：定向扫描特定文件

```
find_duplicates(minLines=10)
```
：仅过滤出有价值的重复代码
```
code_metrics
```
：用于获取紧凑的概览输出

Pre-Call MCP Checklist

MCP调用前检查清单

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)?

调用MCP工具前，请确认：

上下文中是否已有需要的信息？
是否可以使用更精准的工具替代通用工具？
是否设置了合理的
```
limit
```
参数？
可用的情况下是否使用了
```
compact=true
```
？
预期输出是否在合理范围（小于2000 tokens）？

Output Format Standards

输出格式标准

For code analysis

代码分析场景

Max 5 issues per category
Snippets max 10 lines
Use tables for lists

每个分类最多返回5个问题
代码片段最多10行
列表内容使用表格展示

For database queries

数据库查询场景

Max 20 rows in direct output
For results > 20: "Found N rows. First 20: ..."
Compact tabular format

直接输出最多20行结果
结果超过20行时输出：“共找到N行，前20行如下：...”
使用紧凑的表格格式

For documentation

文档场景

Quote only relevant parts (max 500 characters)
Link to complete docs instead of copying content
Summarize instead of quoting verbatim

仅引用相关片段（最多500字符）
提供完整文档链接，不要复制全量内容
优先做总结，不要逐字引用

Efficient Response Examples

高效响应示例

Database Query - Compact Output

数据库查询 - 紧凑输出

Found 1523 rows. First 20:
| id | name | status |
|----|------|--------|
| 1  | ...  | active |
...
Use offset=20 for next page.

共找到1523行，前20行如下：
| id | name | status |
|----|------|--------|
| 1  | ...  | active |
...
使用offset=20获取下一页内容。

API Exploration - Progressive Detail

API探查 - 渐进式详情

API has 45 endpoints. Summary by tag:
- users: 8 endpoints
- auth: 5 endpoints
- products: 12 endpoints
...
Use get_api_endpoint_details for specifics.

该API共包含45个接口，按标签分类概览：
- users: 8个接口
- auth: 5个接口
- products: 12个接口
...
调用get_api_endpoint_details获取具体接口信息。

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.

过去1小时共找到234个错误，出现频率Top5：
1. ConnectionTimeout：出现89次
2. ValidationError：出现45次
...
使用带过滤参数的tail_logs或parse_logs获取详情。

Reference Documentation

参考文档

Deep Knowledge: Use
mcp__documentation__fetch_docs
with technology:
token-optimization
for advanced optimization techniques.

深度知识：调用
mcp__documentation__fetch_docs
并指定technology参数为
token-optimization
可获取高级优化技巧。