MCP Tool / Agent-ready Harness

一个工具能被 API 调用，不代表它适合 Agent 使用；输出协议、错误信息和调用顺序都需要重新设计。

Context#

我参与过 MCP Tool Serving 相关链路改造。这个经历让我形成了一个很强的判断：

API-ready 不等于 Agent-ready。

一个工具能被后端程序调用，不代表它适合 LLM Agent 使用。Agent 面对的是上下文、自然语言、错误恢复和多轮规划，而不是稳定的函数调用环境。

The problem#

原始工具接口通常面向后端服务，输出大量结构化 JSON。这对程序来说没问题，但对 Agent 来说可能有几个问题：

• 字段太多，token 浪费；
• 错误信息不够可读；
• 不知道失败是否可重试；
• 不知道下一步应该等待、换工具还是终止；
• 工具调用顺序不清楚；
• 返回结果不适合放进上下文；
• 生产环境里的异常没有被转化成 Agent 可理解的状态。

What I worked on#

我参与的改造主要包括：

1. 压缩冗余 JSON 输出；
2. 合并对 Agent 无用的字段；
3. 规范错误语义；
4. 区分 retryable / non-retryable 状态；
5. 给出更清晰的等待和 fallback 信息；
6. 让工具调用链路更适合被上下文记录；
7. 让 Agent 能更容易理解下一步动作。

Why it matters#

Agent 在真实生产链路里不可能只面对完美工具。它会遇到超时、排队、网络问题、权限问题、参数错误、资源不足和内部服务异常。

如果工具只返回一个后端错误码，Agent 很难知道怎么处理。更好的工具协议应该告诉它：

• 当前发生了什么；
• 是否可以重试；
• 如果重试，应该等多久；
• 是否需要换一个工具；
• 哪些信息应该保留在上下文中；
• 哪些失败是不可恢复的。

What I learned#

MCP 和 tool-use 的关键不是“接入更多工具”，而是让工具输出成为 Agent 可以理解、可以决策、可以恢复的状态。

这也是我后面看 Coding Agent 和 sandbox 环境时很在意的一点：工具、环境和错误信息本身就是训练和评测的一部分。