模型可见的工具错误
返回人工智能能够读取并据此恢复的错误。
模型可见的工具错误 是 CoddyKit 上的免费 MCP Academy 课时。 这是第 1 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 MCP Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 MCP Academy 课程共包含 4 节课。
错误只是更多上下文
工具失败时，AI 不会崩溃。它只会读取您的错误，将其作为上下文，然后像处理任何结果一样决定下一步该做什么。
好的错误应当可采取行动
请面向能够采取行动的读者编写错误信息。“找不到城市”比“异常”更好，因为模型可以请求用户修正城市名称。
返回错误字符串
最简单的模式是在出现问题时返回清晰的消息字符串，这样模型就能准确读出失败的原因。
@mcp.tool()
def get_user(uid: int) -> str:
if uid < 1:
return "Error: uid must be positive."通过引发异常标记工具错误
您也可以引发普通的 Python 异常。FastMCP 会捕获它，并向模型报告工具错误，而不是导致服务器崩溃。
@mcp.tool()
def divide(a: float, b: float) -> float:
if b == 0:
raise ValueError("b cannot be zero")
return a / bisError 标记结果
在底层，失败的工具调用会返回一段内容，并将isError设置为 true。这个标记会告诉客户端，该结果描述的是一次失败。
模型可以恢复
易读的错误信息可以让 AI 使用更好的输入重试，或向用户解释问题，从而把失败转化为有帮助的下一步。🔁
说明是什么以及为什么
好的错误信息要说明什么失败了，以及为什么失败。“文件缺失：report.csv”比单独一句“未找到”对模型有用得多。
提出修复建议
可以的话，请在错误信息中提示解决办法。“日期必须采用 YYYY-MM-DD 格式”能让模型在下一次调用时自行纠正。
if not iso_date:
raise ValueError("Date must be in YYYY-MM-DD format")绝不要泄露内部信息
错误信息会传给模型，通常也会传给用户，因此请勿在返回的消息中包含秘密、原始堆栈跟踪信息或连接字符串。
先验证，再尽早报告错误
先检查参数，在执行实际工作前返回错误。快速失败能让工具的行为保持可预测，也更容易理解。
错误是契约的一部分
请把失败视为经过设计的输出。能够说明可能出现哪些错误的工具，对模型的帮助并不亚于记录了成功情况的工具。
快速检查
为什么要将工具错误写成清晰、易读的消息？
回顾
工具错误是模型会读取的上下文：请让它们清晰，说明是什么以及为什么，提出修复建议，并且绝不要泄露内部信息。✅
用 AI 导师学习 Python — 免费
在浏览器中编写并运行真实代码，获得全天候 AI 导师的即时帮助，并在网页或应用中继续学习。
- 课程
- 30
- 课程
- 120
常见问题解答
「模型可见的工具错误」课时是免费的吗？
是的 — 「模型可见的工具错误」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 MCP Academy 课程的其余内容，请升级到 CoddyKit PRO。 MCP Academy 课程共包含 4 节课。
「模型可见的工具错误」这节课中我会学到什么？
返回人工智能能够读取并据此恢复的错误。 你通过在浏览器中直接运行的动手代码来练习 MCP Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 MCP Academy 需要有经验吗？
无需任何先前经验。CoddyKit 上的 MCP Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 1 节课，共 4 节。
「模型可见的工具错误」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 MCP Academy 课中编写并运行代码吗？
能。每节 MCP Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。