一个常见的错误是直接把现有的 REST API 端点或函数封装成 MCP 工具，「反正功能都实现了，包一层不就行了？

LLM Agent 的上下文窗口（context window）是稀缺资源，而计算机内存是廉价且充裕的。这个根本差异决定了工具设计的方向。

简单例子：在通讯录中搜索联系人。

传统软件可以高效地存储和处理整个联系人列表，逐个检查每条记录。
但如果让 LLM Agent 使用一个返回「所有联系人」的工具，然后逐个 token 地阅读每一条……它就是在用最宝贵的上下文空间处理大量无关信息。

# ❌ 不好：直接暴露底层能力，让 Agent 自己处理
list_contacts()         # 返回所有联系人，Agent 需要逐个筛选
get_contact(id)         # Agent 需要知道 ID 才能调用

# ✅ 好：针对 Agent 的认知模式设计
search_contacts(name="张")           # 直接返回匹配结果
message_contact(name="张三")         # 内部处理搜索和发送

两个极端
太细粒度：多次调用，浪费 token
太粗粒度：返回大量无关信息，填满上下文。

核心原则：把编排逻辑放在你的代码里，而不是放在 LLM 的上下文窗口里。

启发式方法：如果 Agent 在 90% 的情况下调用 A 后都会调用 B，考虑合并它们。

# 观察到的调用模式：
# 1. get_issue(id)
# 2. get_issue_comments(id)  <-- 几乎总是紧跟着调用

# ✅ 考虑合并
get_issue_with_comments(issue_id, include_comments=True)

一个 Server，一个职责。

不要试图构建一个「全能」的 MCP Server。就像微服务架构一样，每个 Server 应该专注于一个领域。

当工具数量增长到一定程度，MCP 的「会话开始时加载所有工具」模式会遇到瓶颈。这时，一种互补的方案是 Skills（或类似的渐进式披露机制）。