工具调用失败需依次排查：一、检查tool_context.py中函数是否注册并带类型提示；二、校验函数签名是否符合mcp v0.2规范；三、确认当前llm模型supports_function_calling为true；四、重启agent并清除~/.hermes/cache/tools缓存；五、验证函数模块路径正确且可导入。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用Hermes Agent时触发工具调用，但系统提示找不到对应指令，则可能是由于函数未正确注册、签名不合规或LLM模型能力不匹配所致。以下是解决此问题的步骤：
一、检查函数注册与tool_context.py声明一致性
Hermes Agent依赖environments/tool_context.py中显式声明的工具列表来构建可调用函数索引，未在此文件中注册的函数将不会出现在LLM的工具选择池中。该步骤确保Agent运行时具备对目标函数的元信息认知能力。
1、打开项目根目录下的environments/tool_context.py文件。
2、确认目标函数名已作为字符串添加至AVAILABLE_TOOLS列表中。
3、检查该函数是否已在同文件中通过@tool装饰器完成注册，并包含完整docstring描述。
4、验证函数签名中所有参数是否标注了类型提示（如str、int、Optional[dict]），缺失类型提示会导致参数解析失败。
二、校验函数签名与MCP协议兼容性
Hermes Agent采用Model Context Protocol（MCP）标准进行工具描述交换，函数必须满足MCP v0.2规范中对参数结构、必选字段及返回格式的约束，否则LLM无法生成合法的调用请求。
1、确认函数每个参数均具有默认值或明确标记为required=True。
2、检查函数返回值是否为JSON序列化安全类型（如dict、list、str、int、float、bool或None）。
3、若函数内部调用外部API，需确保其超时设置不超过TOOL_TIMEOUT_SECONDS环境变量指定值（默认30秒）。
4、运行hermes validate-tools命令，检测所有注册函数是否通过MCP Schema校验。
三、验证LLM模型对function calling的支持能力
并非所有接入的LLM提供商原生支持function calling机制；Hermes Agent会依据所选模型的能力标识自动启用或降级处理，若模型不支持则转为prompt-based tool selection，导致调用不可靠。
1、执行hermes model list查看当前激活模型及其supports_function_calling字段值。
2、若值为False，切换至明确标注支持的模型，例如openai/gpt-4o、anthropic/claude-3-5-sonnet或本地部署的llama-3.1-70b-instruct-q8_0（需启用--enable-function-calling标志）。
四、重新加载工具上下文并强制刷新缓存
Agent在启动时一次性加载tool_context.py内容，修改后若未重启或未触发重载逻辑，变更不会生效。此操作可绕过冷启动缓存，强制重建工具索引。
1、停止当前运行的Agent服务：hermes stop。
2、清除工具缓存目录：rm -rf ~/.hermes/cache/tools。
3、重启Agent并启用调试日志：hermes start --log-level debug。
4、观察启动日志中是否出现“Loaded N tools from tool_context.py”字样，确认数量与预期一致。
五、检查函数文件导入路径与模块可见性
函数定义文件若未被Python解释器识别为可导入模块，即使注册语法正确，也会在运行时因ImportError导致指令不可见。该问题常见于相对路径错误或__init__.py缺失。
1、确认函数所在Python文件位于environments/目录下，且该目录中存在空的__init__.py文件。
2、检查tool_context.py中import语句是否使用绝对导入，例如from environments.my_tool import my_function，而非相对导入。
3、进入Hermes虚拟环境后手动执行导入测试：python -c "from environments.my_tool import my_function; print(my_function)"。
4、若报错ModuleNotFoundError，说明模块路径未被Python发现，需调整sys.path或重构包结构。
