工具调用Token税：从346 Token隐形成本到百工具上下文爆炸的降本五栈

无工具调用:  prompt → completion
             150 Token → 200 Token

有工具调用:  prompt + schema → tool_call → tool_result → completion  
             150 + 346 Token → 180 Token → result → 200 Token

Token增量: +346 Token（纯Schema + 调用格式开销）

无MCP:     system_prompt(500) + user_input(100) = 600 Token
四MCP:     system_prompt(500) + schemas(7000) + user_input(100) = 7600 Token
倍率:      12.7x

# 一个典型工具的Schema定义（约150 Token）
{
    "name": "query_database",
    "description": "Execute a SQL query against the PostgreSQL database...",
    "parameters": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "SQL query..."},
            "database": {"type": "string", "enum": ["production", "staging"]},
            "limit": {"type": "integer", "minimum": 1, "maximum": 1000}
        },
        "required": ["query"]
    }
}

10工具 × 150 Token/工具 = 1,500 Token/轮
50工具 × 150 Token/工具 = 7,500 Token/轮
100工具 × 150 Token/工具 = 15,000 Token/轮

10步Agent × 100工具 = 150,000 Token 纯Schema开销
按Claude Sonnet 4.6定价($3/M input): 每任务$0.45 纯Schema成本

单步成本 = 基础提示 + 工具Schema + 工具调用 + 工具结果
         = 500    + 7500     + 300     + 500
         = 8,800 Token

10步成本（无上下文管理）:
         = Σ(基础提示 + 完整工具Schema × 步数) + 工具调用 × 10
         ≈ 500×10 + 7500×10 + 800×10
         = 88,000 Token

100步成本: ≈ 880,000 Token → 在Sonnet 4.6上约$2.64/任务

{
  "name": "create_deployment",
  "description": "Create a new deployment with the specified configuration...",
  "parameters": {
    "type": "object",
    "properties": {
      "name": {"type": "string"},
      "replicas": {"type": "integer"},
      "containers": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "image": {"type": "string"},
            "ports": {"type": "array", "items": {"type": "integer"}},
            "env": {"type": "object", "additionalProperties": {"type": "string"}},
            "resources": {
              "type": "object",
              "properties": {
                "cpu": {"type": "string"},
                "memory": {"type": "string"}
              }
            }
          }
        }
      }
    }
  }
}

graph TB
    subgraph "工具调用Token降本五栈"
        L1["第1层: Schema瘦身<br/>精简描述·压缩枚举·去除冗余字段"]
        L2["第2层: 按需注入<br/>动态路由·工具分片·上下文裁剪"]
        L3["第3层: 结果压缩<br/>截断·摘要·结构化过滤"]
        L4["第4层: 推理重叠<br/>投机执行·流式解析·预取结果"]
        L5["第5层: 架构重构<br/>Tool RAG·层级路由·沙箱替代"]
    end

    L1 --> L2 --> L3 --> L4 --> L5

    style L1 fill:#4CAF50,color:#fff
    style L2 fill:#2196F3,color:#fff
    style L3 fill:#FF9800,color:#fff
    style L4 fill:#9C27B0,color:#fff
    style L5 fill:#F44336,color:#fff

# Before: 58 Token
"query_database": {
    "description": "Execute a SQL query against the PostgreSQL database. "
                   "Supports SELECT, INSERT, UPDATE, DELETE operations. "
                   "Results are returned as JSON arrays. Use 'limit' to "
                   "control result set size. Read-only queries are safe.",
}

# After: 18 Token（-69%）
"query_database": {
    "description": "Run SQL on PostgreSQL. Returns JSON. Set limit for rows.",
}

# Before: 大量枚举值
"region": {
    "type": "string", 
    "enum": ["us-east-1", "us-east-2", "us-west-1", "us-west-2", 
             "eu-west-1", "eu-west-2", "eu-central-1", "ap-southeast-1",
             "ap-northeast-1", "ap-southeast-2", "sa-east-1"]
}

# After: 用描述替代枚举
"region": {
    "type": "string",
    "description": "AWS region code (e.g. us-east-1)"
}

# 工具分片路由器
TOOL_SHARDS = {
    "database": [query_db, insert_db, migrate_db],
    "filesystem": [read_file, write_file, list_dir],
    "network": [http_get, http_post, dns_lookup],
    "compute": [run_code, spawn_vm, manage_queue],
}

def select_shard(user_query: str) -> list[str]:
    """轻量分类器决定注入哪个工具分片"""
    embedding = embed(user_query)
    shard_scores = cosine_similarity(embedding, shard_centroids)
    return top_k_shards(shard_scores, k=1)  # 只注入1个分片

# 效果: 100工具 → 每轮只注入~25工具的Schema

Agent → MCP Gateway → MCP Server 1
                     → MCP Server 2
                     → MCP Server 3

# 不要将完整的查询结果塞入上下文
def query_database(sql: str) -> dict:
    results = execute(sql)

    # 坏做法: 返回全部结果（可能数千Token）
    # return {"data": results}

    # 好做法: 返回摘要 + 样本
    return {
        "row_count": len(results),
        "columns": list(results[0].keys()),
        "sample": results[:5],  # 只返回前5行
        "aggregates": compute_basic_stats(results)
    }

工具原始返回: 5000 Token（完整网页内容）
→ 摘要压缩后: 300 Token（关键信息提取）
压缩比: 16.7x

sequenceDiagram
    participant Model as LLM
    participant Predict as 预测器
    participant Tool as 工具引擎

    Note over Model,Tool: 传统串行模式
    Model->>Tool: 1. 生成tool_call
    Tool-->>Model: 2. 返回结果
    Note over Model: 3. 继续生成

    Note over Model,Tool: PASTE重叠模式
    Model->>Predict: 1. 部分生成→预测下一调用
    Predict->>Tool: 2. 提前执行预测的工具
    Tool-->>Predict: 3. 预取结果
    Model->>Tool: 4. 确认调用
    Predict-->>Model: 5. 直接使用预取结果（命中）

# Tool RAG 架构
class ToolRAG:
    def __init__(self, tool_catalog: list[Tool]):
        # 将每个工具的名称+描述编码为向量
        self.tool_embeddings = {
            tool.name: embed(f"{tool.name}: {tool.description}")
            for tool in tool_catalog
        }
        self.tools = {tool.name: tool for tool in tool_catalog}

    def select_tools(self, query: str, top_k: int = 5) -> list[ToolSchema]:
        """只检索最相关的top_k个工具Schema注入上下文"""
        query_embedding = embed(query)
        scores = {
            name: cosine_similarity(query_embedding, emb)
            for name, emb in self.tool_embeddings.items()
        }
        top_tools = sorted(scores, key=scores.get, reverse=True)[:top_k]
        return [self.tools[name].schema for name in top_tools]

# 效果: 200工具 → 每轮只注入5个最相关工具的Schema
# Token节省: (200-5) × 150 = 29,250 Token/轮

第一级: 意图分类器（轻量模型/embedding匹配）
  → 确定工具域（数据库/文件系统/网络/...）

第二级: 域内工具选择（主推理模型）
  → 从该域的10-15个工具中选择具体工具和参数

无缓存:   7,500 Token Schema × $3/M = $0.0225/轮
有缓存:   7,500 Token Schema × $3/M × 10% = $0.00225/轮
10步节省: ($0.0225 - $0.00225) × 10 = $0.2025/任务

=== 无优化版本 ===
每轮输入:
  系统提示:    800 Token
  工具Schema:  15 × 150 = 2,250 Token
  历史上下文:  累积增长（第8轮约8,000 Token）
  用户输入:    200 Token
  小计:        ~11,250 Token/轮（平均）

8轮总输入:     ~90,000 Token
8轮总输出:     ~12,000 Token（含工具调用输出）
工具返回:       ~8,000 Token

总Token:       ~110,000 Token
Claude Sonnet: $3/M in + $15/M out = $0.27 + $0.18 = $0.45/任务
日处理500任务:  $225/天 → $6,750/月

=== 五层优化后 ===
每轮输入:
  系统提示:    400 Token（瘦身）
  工具Schema:  5 × 100 = 500 Token（分片+瘦身）
  历史上下文:  ~3,000 Token（摘要压缩）
  用户输入:    200 Token
  小计:        ~4,100 Token/轮

8轮总输入:     ~33,000 Token（含缓存命中）
8轮总输出:     ~10,000 Token
工具返回:       ~2,000 Token（结构化过滤）

总Token:       ~45,000 Token
缓存折扣后:    ~$0.12/任务（-73%）
日处理500任务:  $60/天 → $1,800/月

月节省: $4,950（73%成本削减）

graph LR
    subgraph "成本诊断决策树"
        A["Schema命中率 < 30%?"] -->|"是"| B["引入 Tool RAG<br/>按需检索替代全量注入"]
        A -->|"否"| C["Prompt Caching<br/>命中率 > 90%?"]
        C -->|"否"| D["调整Schema位置<br/>确保前缀固定"]
        C -->|"是"| E["结果Token > 总量30%?"]
        E -->|"是"| F["增加结果压缩<br/>结构化过滤"]
        E -->|"否"| G["优化完成<br/>维持现状"]
        B --> H["重测指标"]
        D --> H
        F --> H
        H --> A
    end