Glossary
73 terms from "Agent 工具调用基础：让 Agent 真正动手做事." Look them up when you get stuck; the first mention in the text carries a hover definition.
| Term | Definition | Source |
|---|---|---|
| 工具（tool） | 在 Agent 语境下，工具是模型可以在对话中申请调用的一项具体能力，由宿主程序注册并执行，让模型从「只会说」变成「能动手」。 | Define tools — Claude API |
| 宿主程序 | 宿主程序是实际接收模型的工具调用请求、执行该操作并把结果传回模型的那部分代码，例如 Claude Code 或你自己写的 Agent 脚本。 | How tool use works — Claude API |
| search_files | 课程里用来举例的一个工具名字，代表「按某种条件在项目文件里查找」这一类具体工具定义。 | Define tools — Claude API |
| name | 工具定义里的必填字段，是模型选中某个工具时使用的标识符，必须和调用时给出的名字完全一致。 | Define tools — Claude API |
| description | 工具定义里的必填字段，用文字说明这个工具是做什么的、什么时候该用，是模型选择工具时唯一可读的说明依据。 | Define tools — Claude API |
| input_schema | 工具定义里的必填字段，是一份 JSON Schema，规定了调用这个工具时参数应该是什么形状。 | Define tools — Claude API |
| 客户端工具 | 指由宿主应用自己负责执行的工具，模型只负责生成调用请求，真正的执行代码运行在宿主这一侧。 | Tool use with Claude — Overview |
| 服务器工具 | 指由 Anthropic 服务器代为执行的工具，与需要宿主应用自己实现执行逻辑的客户端工具相对。 | Tool use with Claude — Overview |
| 结构化数据 | 模型返回的工具调用请求是一份结构化数据（而不是自然语言指令），包含工具名和参数，等待宿主程序解析执行。 | How tool use works — Claude API |
| required | JSON Schema 里的字段，列出调用某个工具时必须提供的参数名，缺少这些参数会被当作不合法输入处理。 | Define tools — Claude API |
| Claude Code | 课程里用来具体化「宿主程序」概念的例子，本身就是一个会申请调用多种工具（读文件、搜代码、执行命令等）的 Agent 产品。 | Tools reference — Claude Code Docs |
| tools | 发给模型的请求里携带的字段，是一份工具清单，列出当前对话里模型可以申请调用哪些工具、各自需要什么参数。 | Define tools — Claude API |
| stop_reason | 模型响应里的字段，说明模型这次说完话是因为什么原因停下来，取值包括 tool_use、end_turn 等，只是一个信号而非执行记录。 | Tool use with Claude — Overview |
| tool_result | 发回给模型的消息里的一种内容块类型，携带工具执行完的结果，通过 tool_use_id 和对应的 tool_use 块匹配。 | Handle tool calls — Claude API |
| tool_use_id | tool_result 块里的字段，必须和对应 tool_use 块的 id 完全一致，模型靠它把结果和请求对应起来。 | Handle tool calls — Claude API |
| is_error | tool_result 块里的可选字段，标记这次工具执行本身是否失败，设为 true 时模型会知道这次调用出了问题。 | Handle tool calls — Claude API |
| finish_reason | OpenAI 兼容 API 里对应 stop_reason 的字段名，取值 tool_calls 表示模型请求调用工具。 | Tool Use — LM Studio Docs (OpenAI-compatible API) |
| messages | 请求里携带对话历史的数组字段，每一轮响应都要被原样追加进去，包括模型的 tool_use 回复和后续的 tool_result。 | How tool use works — Claude API |
| end_turn | stop_reason 的一个取值，表示模型这一轮已经说完了话，不再需要调用工具，可以把内容交给用户。 | Tool use with Claude — Overview |
| tool_use 块 | 模型响应 content 数组里表示一次工具调用请求的内容块类型，必须同时具备 id、name、input 三个字段才算完整。 | Define tools — Claude API |
| 往返 | 指一次工具调用从模型发出请求、宿主执行、结果送回、模型再给出下一步响应的完整循环过程。 | How tool use works — Claude API |
| 循环 | 宿主端处理多轮工具调用的实现方式，只要 stop_reason 还是 tool_use 就继续执行工具、回传结果、再次请求，直到变成 end_turn。 | How tool use works — Claude API |
| 数据依赖 | 指同一批并行工具调用里，一个调用的参数理论上应该等于另一个调用的返回值——而那个返回值在这批调用生成时还不存在。 | Parallel tool use — Claude API |
| disable_parallel_tool_use | 请求里 tool_choice 对象的配置项，设为 true 后模型每次响应最多只调用一个工具，用于在并行调用的依赖关系没想清楚时先把行为收紧。 | Parallel tool use — Claude API |
| 爆炸半径（blast radius） | 指一次工具调用出错时，破坏能波及的范围大小，是给五类工具排序的核心标准。 | Configure the sandboxed Bash tool - Claude Code Docs |
| read_file | 课程里读类工具的示例名字，典型参数是文件路径，返回文件内容本身。 | Tools reference — Claude Code Docs |
| write_file | 课程里写类工具的示例名字，典型参数是路径和内容，一旦执行会覆盖原文件且通常无法撤销。 | Tools reference — Claude Code Docs |
| bash | 课程里执行类工具的示例名字，参数是一个开放式的 command 字符串，能执行任意 shell 命令。 | Configure the sandboxed Bash tool - Claude Code Docs |
| search_code | 课程里搜索类工具的示例名字，典型参数包含 pattern 和 max_results，返回命中位置列表而非完整文件内容。 | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| send_slack_message | 课程里调用外部 API 类工具的示例名字，典型参数是频道和文本，调用会跨网络触达一个不受自己掌控的服务。 | The lethal trifecta for AI agents - Simon Willison's Weblog |
| command | 执行命令类工具（如 bash）的核心参数字段，本质是一段开放式 shell 脚本，能力不受 schema 结构约束。 | Configure the sandboxed Bash tool - Claude Code Docs |
| max_results | 搜索类工具常见的参数，用来限制一次返回的命中数量上限，避免结果过多把上下文挤爆。 | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| 后果不对称 | 指读文件和写文件两类工具调用形状相似，但读错了可以重新读、写错了往往无法撤销，风险后果并不对等。 | Tools reference — Claude Code Docs |
| retry_after | 调用外部 API 类工具失败时可以返回的字段，告诉模型应该等待多久之后再重试，是「失败信息要给可操作线索」的具体例子。 | Tools - Model Context Protocol |
| total_matches | search_code 工具返回结果里的字段，给出总命中数量，让模型判断结果是否完整、要不要缩小搜索范围。 | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| code_search_grep | 课程里对比示例中改写后的搜索工具名字，description 明确说明按内容搜索并指名文件名查找该换用 code_search_glob。 | Writing effective tools for AI agents—using AI agents | Anthropic Engineering |
| code_search_glob | 与 code_search_grep 配套的文件名查找工具，课程用它演示 description 里指名替代工具能显著降低模型选错工具的概率。 | Writing effective tools for AI agents—using AI agents | Anthropic Engineering |
| enum | JSON Schema 关键字，把参数取值收窄到列出的几个选项之一，是真正会拦截不合法输入的约束，而不只是说明。 | Creating your first schema - JSON Schema |
| additionalProperties: false | input_schema 顶层的配置，规定 input 对象只允许出现 properties 里声明过的键，堵住模型凭空发明额外字段混进下游代码的漏洞。 | Strict tool use — Claude API |
| strict 模式 | 在工具定义上设置 strict: true 后，平台通过约束模型的采样过程保证生成的 input 严格匹配 input_schema，不合法的参数根本不会被生成。 | Strict tool use — Claude API |
| 命名空间 | 给工具名字加上服务前缀（如 github_、slack_）的做法，让模型在工具一多时能先按前缀排除掉不相关的选项。 | How to implement tool use - Claude Platform Docs |
| github_list_prs | 课程举例的带命名空间前缀的工具名，前缀 github_ 表明这个工具属于 GitHub 服务，帮模型和其他服务的同名操作区分开。 | How to implement tool use - Claude Platform Docs |
| slack_send_message | 课程举例的另一个带命名空间前缀的工具名，前缀 slack_ 表明它专属于 Slack 服务，和其他发送消息类工具区分开。 | How to implement tool use - Claude Platform Docs |
| title | JSON Schema 里的说明性字段，用来给参数起一个可读的标题，和 description 一样只起说明作用，不构成强制约束。 | Creating your first schema - JSON Schema |
| MCP | 一套定义客户端与工具服务之间交互规范的协议，课程引用它对「错误信息应反馈给模型以便自我纠正」的明确规定。 | Tools - Model Context Protocol |
| 55K token | Anthropic 工程团队给出的例子：58 个工具的定义就能占用大约 55K token 的上下文，用于说明工具数量对上下文开销的实际影响。 | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| 134K token | 课程给出的另一个更极端的例子，说明工具数量继续增加时，工具定义本身消耗的上下文可以膨胀到非常可观的规模。 | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| file_type | 课程用来演示 description 不构成约束的示例参数字段，配合 description 时模型可能乱填，加上 enum 后才被真正收窄。 | Creating your first schema - JSON Schema |
| 粒度 | 指工具职责划分的精细程度，课程强调粒度既不是越粗越好也不是越细越好，需要先按功能拆分再用命名空间和描述控制选错概率。 | Writing effective tools for AI agents—using AI agents | Anthropic Engineering |
| 提示注入（prompt injection） | 指攻击者把指令藏在 Agent 迟早会读到的内容（如 issue、网页）里，让 Agent 把这段文字误当成需要服从的新指令去执行。 | The lethal trifecta for AI agents - Simon Willison's Weblog |
| allow | 权限规则三档之一，适用于只读、无副作用、可重复执行而不留痕迹的操作，会被自动放行不需要人工确认。 | Configure permissions - Claude Code Docs |
| ask | 权限规则三档之一，适用于有副作用但可逆、影响范围在本地仓库内的操作，执行前需要人工确认。 | Configure permissions - Claude Code Docs |
| deny | 权限规则三档之一，适用于不可逆或影响范围超出本地的操作，直接拒绝执行，且求值时优先级高于 ask 和 allow。 | Configure permissions - Claude Code Docs |
| Read(./.env) | 课程给出的具体权限规则示例，把读取 .env 文件这个操作直接列入 deny 名单，防止密钥内容被读出后进入对话上下文。 | Configure permissions - Claude Code Docs |
| Bash(git push:*) | 课程举例的权限规则写法，Tool(specifier) 格式直接对应宿主暴露给模型的确切工具名和调用范围。 | Configure permissions - Claude Code Docs |
| 过度授权（excessive agency） | OWASP 定义的风险类别，指模型输出的一次异常、歧义或被操纵的结果，触发了本不该发生的破坏性动作。 | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| 功能过多（excessive functionality） | 过度授权的根因之一，指一个工具身兼多职（比如既能读收件箱又能对外发信），一次误判造成的影响范围因此被放大。 | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| 权限过大（excessive permissions） | 过度授权的根因之一，指工具本身职责单一，但被授予的访问范围超出了任务实际需要。 | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| 自主性过高（excessive autonomy） | 过度授权的根因之一，指 Agent 连续执行多步操作时中间没有人工介入检查，等发现问题时不可逆的操作可能已经执行。 | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| 致命三要素（lethal trifecta） | 私有数据访问、接触不可信内容、对外通信能力三者同时具备时形成的风险组合，让提示注入能真正把数据带出系统。 | The lethal trifecta for AI agents - Simon Willison's Weblog |
| 人在环控制 | OWASP 缓解过度授权的措施之一，要求高影响力的操作在执行前必须经过人工批准。 | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| 沙箱 | 操作系统级的隔离机制，独立于模型的判断而强制执行文件系统和网络隔离，即使提示注入得手也能把破坏范围限制住。 | Configure the sandboxed Bash tool - Claude Code Docs |
| TOOLS | 课程示例里统一注册工具的对象，把每个工具的 schema 字段和实际执行的 handler 函数放在同一张表里，避免两边定义脱节。 | Define tools — Claude API |
| toolSchemas | 从 TOOLS 表派生出来、发给模型的 tools 参数列表，只包含 name/description/input_schema，不包含 handler。 | Define tools — Claude API |
| toolHandlers | 从 TOOLS 表派生出来的执行时查找表，按工具名字映射到真正执行该工具的函数。 | How tool use works — Claude API |
| github_repo_info | 课程实现的第三个示例工具，查询公开 GitHub 仓库的基本信息，是唯一会把数据发到项目之外的工具。 | How to implement tool use - Claude Platform Docs |
| SAFE_NAME | 课程代码里用于校验 owner/repo 参数格式的正则表达式，防止把任意字符串当参数发到外部网络。 | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| MAX_TURNS | 课程执行循环里设置的最大轮数上限，防止模型不停地请求调用工具、循环永远不结束。 | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| PROJECT_ROOT | 课程代码里表示项目根目录的常量，read_file 和 search_files 都靠它做路径边界检查，防止访问项目目录之外的文件。 | Configure the sandboxed Bash tool - Claude Code Docs |
| recentCalls | 课程代码里记录最近几次工具调用签名的数组，用来检测「同一个工具、同一组参数连续调用三次」的重复调用模式。 | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| GITHUB_TOKEN | 从环境变量读取的可选凭证，用于提高调用 GitHub API 时的速率限制，不设置也能匿名调用。 | Configure permissions - Claude Code Docs |
| 安全阀 | 课程给执行循环加上的一组防护机制的统称，包括 MAX_TURNS、重复调用检测、工具内部路径和格式校验，各自防住不同的失控场景。 | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| function walk(dir) | 课程代码里自己实现的目录遍历函数，用于 searchFiles 内部递归列出文件，而不是依赖 shell 的 grep 命令。 | Configure the sandboxed Bash tool - Claude Code Docs |