AI Agent Tool Calling PromptsAI Agent 工具调用 Prompt
Build reliable tool-using agents with copy-ready prompt templates, layered selection and repair rules, a worked API example, retry boundaries, output validation, and a production evaluation matrix.
用可直接改写的 Prompt 模板、分层选择与修复规则、完整 API 案例、重试边界、结果验证和生产评测矩阵，构建更可靠的工具调用 Agent。
Why Prompt Layering Matters for Tool Calling
为什么工具调用需要 Prompt 分层
The original QVeris blog argues that tool-calling systems should not rely on one long, generic prompt. When agents call hundreds or thousands of tools, each provider has different parameter conventions, field names, schemas, examples, and failure patterns. A single prompt eventually becomes hard to maintain, hard to debug, and easy to contradict.
QVeris 原始博客的核心判断是：工具调用系统不能长期依赖一个又长又通用的 prompt。当 Agent 需要调用数百甚至数千个工具时，不同 provider 会有不同的参数约定、字段名称、schema、样例和失败模式。单一 prompt 会越来越难维护，也更容易产生规则冲突。
The Three Layers: Global, Provider, Exact Tool
三层规则：全局、Provider、具体工具
Universal safety and intent rules. Never fake a repair, never replace the core object, and avoid changing user intent silently.
通用安全和意图规则：不能伪造修复成功，不能替换用户指定的核心对象，也不能悄悄改变用户意图。
Provider-specific conventions. A field fix may be safe for one API but an intent shift for another.
Provider 级别的约定：同样的字段修复在一个 API 中可能安全，在另一个 API 中可能已经改变查询意图。
Rules loaded by full tool_id: quote tools, balance sheet tools, news tools, or company overview tools all need different repair boundaries.
按完整 tool_id 加载规则：行情、资产负债表、新闻搜索、公司概览等工具需要不同的修复边界。
Retrieve documentation, past failures, examples, and risk labels for the current call.
根据当前调用检索文档、历史失败案例、样例参数和风险标签。
What This Design Solves
这种设计解决什么问题
Prompts stop growing linearly
Prompt 不再线性膨胀
Rules live in layers instead of one giant block. Teams can update provider or tool rules without rewriting the whole system prompt.
规则被放在不同层级，而不是堆进一个巨大的系统 prompt。团队可以单独更新 provider 或工具规则。
Tool repair becomes safer
工具修复更可靠
The agent can fix field names, formats, enum values, or types while preserving the user’s core query object.
Agent 可以修复字段名、格式、枚举值或类型，同时保留用户真正要查询的核心对象。
Historical failures become memory
历史失败变成经验
RAG lets the system reuse past repair examples and avoid repeating known bad fixes.
RAG 让系统复用历史修复案例，避免重复犯同样的错误。
Prompt Layering vs One Large Prompt
分层 Prompt 与单一大 Prompt 对比
| Approach方案 | Strength优势 | Risk风险 |
|---|---|---|
| One large prompt单一大 Prompt | Simple to start初期实现简单 | Becomes long, conflicting, and hard to update as tools grow工具增加后容易冗长、冲突且难以更新 |
| Layered prompts分层 Prompt | Clear ownership of rules规则归属清晰 | Needs routing logic to know which layer to load需要路由逻辑决定加载哪一层规则 |
| Layered prompts + RAG分层 Prompt + RAG | Dynamic, maintainable, and experience-aware动态、可维护，并能复用历史经验 | Needs high-quality retrieval and risk labels依赖高质量检索与风险标签 |
Example Workflow for AI Agent Tool Repair
AI Agent 工具修复工作流示例
user intent -> discover candidate tool inspect schema -> retrieve provider rules retrieve exact tool rules -> retrieve historical repairs repair low-risk fields -> call tool -> validate output
This structure fits QVeris because QVeris already treats external capabilities as discoverable, inspectable, and callable units. Prompt layering adds a maintainable reasoning layer around those calls.
这个结构适合 QVeris，因为 QVeris 本身就把外部能力拆成可发现、可检查、可调用的单元。Prompt 分层是在这些调用外面增加一层可维护的判断机制。
Tool Calling Prompt Checklist
工具调用 Prompt 检查清单
Before a tool-calling agent enters production, teams should test whether the prompt stack protects user intent, loads only relevant provider rules, validates required parameters, and records why a repair was attempted. A prompt that fixes every failed call automatically can be dangerous; the system must know the difference between a harmless schema repair and a change to the financial object being queried.
工具调用 Agent 上线前，团队应该测试 prompt 栈是否能保护用户意图、只加载相关 provider 规则、验证必填参数，并记录为什么尝试修复。一个自动修复所有失败调用的 prompt 可能很危险；系统必须区分“无害的 schema 修复”和“改变被查询金融对象”。
Changing ticker to symbol may be safe. Replacing AAPL with a different company because the call failed is not.
把 ticker 改成 symbol 可能是安全修复；因为调用失败就把 AAPL 换成另一家公司则不是。
A production system should record which global, provider, or exact-tool rule shaped the final call.
生产系统应记录是哪条全局、provider 或具体工具规则影响了最终调用。
Related Reading for Reliable Tool Calling
可靠工具调用的相关阅读
Layered prompts work best when they sit next to capability discovery, schema inspection, and structured execution. Read the original QVeris blog for the prompt design pattern, then connect it to the QVeris docs when you are ready to implement discover, inspect, and call flows.
分层 prompt 与能力发现、schema 检查和结构化执行放在一起时效果最好。可以先阅读 QVeris 原始博客了解 prompt 设计模式，再结合 QVeris 文档实现 discover、inspect、call 流程。
Common Tool Calling Prompt Failures
常见工具调用 Prompt 失败模式
| Failure失败模式 | Example例子 | Repair rule修复规则 |
|---|---|---|
| Wrong field name字段名错误 | Agent sends ticker when the tool expects symbol.工具需要 symbol，但 Agent 发送 ticker。 | Allow schema-level repair if the company identity is unchanged.如果公司身份未变，可以允许 schema 级修复。 |
| Unsafe substitution不安全替换 | Agent replaces a missing ticker with a similar company.Agent 把缺失 ticker 换成类似公司。 | Stop and ask for clarification instead of changing the object.停止并询问澄清，而不是改变查询对象。 |
| Overloaded promptPrompt 过载 | One system prompt contains every provider rule and repair example.一个系统 prompt 塞进所有 provider 规则和修复案例。 | Retrieve only the rules relevant to the current tool and provider.只检索当前工具和 provider 相关规则。 |
When RAG Helps Tool Calling Prompts
RAG 什么时候能帮助工具调用 Prompt
RAG is useful when the agent needs recent documentation, known provider quirks, examples from past failures, or policy notes that are too specific to keep in a global prompt. It should not retrieve arbitrary text into the tool call. The retrieval layer should rank only documents that explain the current provider, the exact tool schema, or previous repairs for the same failure class.
当 Agent 需要最新文档、已知 provider 特性、历史失败样例或不适合写进全局 prompt 的策略说明时，RAG 很有价值。但它不应该把任意文本塞进工具调用。检索层应只排序当前 provider、具体工具 schema 或同类失败修复相关的文档。
A good implementation also records the retrieved rule IDs. That makes it possible to debug why the agent changed a parameter, skipped a call, or asked the user to clarify the request.
好的实现还会记录被检索到的规则 ID。这样团队才能调试 Agent 为什么修改参数、跳过调用，或者要求用户澄清请求。
Copy-Ready AI Agent Tool Calling Prompt Templates
可直接改写的 AI Agent 工具调用 Prompt 模板
A production prompt should be modular. Keep the global contract stable, retrieve only relevant provider and tool rules, and make the model state whether it will call, clarify, or refuse. The templates below are deliberately explicit so teams can shorten them after measuring behavior.
生产级 Prompt 应该模块化：全局契约保持稳定，只检索当前 provider 和工具相关的规则，并要求模型明确选择“调用、澄清或拒绝”。下面的模板刻意写得较完整，团队在完成行为评测后可以再压缩。
System prompt for intent-safe tool use
保护用户意图的系统 Prompt
You are a tool-using agent. Preserve the user's requested entity, scope, time range, destination, and constraints. Before calling a tool: 1. Identify the intended outcome. 2. Select the smallest sufficient tool set. 3. Validate required arguments and permissions. 4. Never invent a missing identity or credential. Choose exactly one next action: CALL — schema is valid and intent is preserved. CLARIFY — a meaning-changing value is missing. REFUSE — the action violates policy or permission. After a call, validate freshness, units, identity, completeness, and tool-reported errors. Cite the tool and timestamp in the user-facing answer.你是一个可以使用工具的 Agent。 必须保留用户指定的实体、范围、时间区间、 输出目的地与约束条件。 调用工具前： 1. 明确用户期望的结果； 2. 选择能够完成任务的最小工具集合； 3. 校验必填参数与权限； 4. 不得编造缺失的身份、对象或凭据。 下一步只能选择一种动作： CALL——schema 有效且用户意图未改变； CLARIFY——缺失内容会改变任务含义； REFUSE——操作违反策略或权限边界。 调用后验证时效、单位、对象身份、完整性和 工具错误，并在回答中说明工具来源与时间。
Candidate ranking prompt
候选工具排序 Prompt
Given USER_INTENT and CANDIDATE_TOOLS, rank candidates by: - semantic fit with the requested outcome; - required input availability; - data freshness and geographic coverage; - permission and side-effect risk; - expected latency and cost. Do not choose a tool because its name shares words with the request. Inspect its description, schema, response fields, limits, and examples. Return the selected tool_id plus a brief reason and rejected alternatives. If no candidate is sufficient, return NO_MATCH instead of forcing a call.根据 USER_INTENT 与 CANDIDATE_TOOLS， 按以下条件为候选工具排序： - 与目标结果的语义匹配度； - 必需输入是否已经具备； - 数据时效与地域覆盖； - 权限及副作用风险； - 预计延迟与成本。 不能只因工具名称与请求有相同词就选择它。 必须检查描述、schema、返回字段、限制和示例。 输出所选 tool_id、简短理由及被排除的候选项。 如果没有足够匹配的工具，返回 NO_MATCH， 不要为了完成流程而强行调用。
Safe schema repair prompt
安全的 Schema 修复 Prompt
Compare ARGUMENTS with TOOL_SCHEMA. You may repair representation-only errors: - approved field aliases; - an unambiguous type conversion; - documented enum normalization; - a date format with the same calendar meaning; - removal of unsupported optional fields. Do not change entity identity, requested action, time range, currency, destination, access scope, or irreversible options. If such a value is absent or ambiguous, return NEEDS_CLARIFICATION. Return: repaired_arguments, changed_fields, rule_id, confidence, and clarification_question.对照 TOOL_SCHEMA 检查 ARGUMENTS。 只允许修复不改变含义的表达问题： - 已批准的字段别名； - 含义唯一的类型转换； - 文档明确的枚举标准化； - 保持日期含义不变的格式转换； - 删除工具不支持的可选字段。 不得改变实体身份、操作类型、时间范围、币种、 目的地、访问范围或不可逆选项。以上值若缺失或 存在歧义，返回 NEEDS_CLARIFICATION。 输出 repaired_arguments、changed_fields、 rule_id、confidence 与 clarification_question。
Bounded retry prompt
有边界的重试 Prompt
Classify TOOL_ERROR as TRANSIENT, INVALID_INPUT, PERMISSION, RATE_LIMIT, NOT_FOUND, or UNKNOWN. Retry only TRANSIENT or RATE_LIMIT errors, up to MAX_RETRIES, using documented backoff. Repair INVALID_INPUT only under the safe-repair policy. Never retry PERMISSION errors with broader access. Never turn NOT_FOUND into a different entity. Use a fallback tool only if it provides equivalent coverage and does not weaken freshness, permission, or accuracy requirements. Otherwise stop and report the limitation with a useful next step.把 TOOL_ERROR 分类为 TRANSIENT、INVALID_INPUT、 PERMISSION、RATE_LIMIT、NOT_FOUND 或 UNKNOWN。 只有 TRANSIENT 或 RATE_LIMIT 可以重试，次数不得 超过 MAX_RETRIES，并采用文档规定的退避策略。 INVALID_INPUT 只能按安全修复规则处理；不得通过 扩大权限来重试 PERMISSION；不得把 NOT_FOUND 自动替换成另一个实体。 仅当备用工具能提供等价覆盖，且不会降低时效、 权限或准确性要求时才可回退。否则应停止并说明 限制，同时给出用户可以采取的下一步。
Worked Example: Repairing a Market Quote Call Without Changing Intent
完整案例：不改变意图地修复行情工具调用
Suppose the user asks, “Get the latest AAPL quote, verify its timestamp, and tell me the currency.” Discovery returns a delayed end-of-day tool and a real-time quote tool. The correct selection depends on freshness, not merely on the word “quote.” If the real-time tool expects symbol but the model produces ticker, that alias can be repaired because the identity remains AAPL.
假设用户提出：“获取 AAPL 最新报价，核对时间戳并告诉我币种。”能力发现返回一个延迟的日终行情工具和一个实时行情工具。正确选择取决于时效要求，而不是只看名称中有没有“quote”。如果实时工具需要 symbol，模型却生成了 ticker，由于 AAPL 的身份没有变化，这个字段别名可以安全修复。
Model-generated call
模型生成的调用
{
"tool_id": "market.realtime_quote",
"arguments": {
"ticker": "AAPL",
"include_timestamp": "yes"
}
}Two representation errors exist: the field alias is wrong and the Boolean is a string. Neither requires a change to the requested company or task.
这里有两个表达层错误：字段别名错误，布尔值被写成字符串；二者都不需要改变用户指定的公司或任务。
Validated call
校验后的调用
{
"tool_id": "market.realtime_quote",
"arguments": {
"symbol": "AAPL",
"include_timestamp": true
},
"repair_rule_ids": [
"alias.ticker_to_symbol",
"type.string_to_boolean"
]
}The response still needs validation. Confirm that the returned symbol is AAPL, parse the provider timestamp and timezone, retain the reported currency, and disclose whether the quote is real-time or delayed.
调用成功不等于任务完成。Agent 还应确认返回 symbol 是 AAPL，解析 provider 的时间戳与时区，保留原始币种，并说明行情是实时还是延迟数据。
Where repair must stop
必须停止自动修复的边界
If the user wrote “Apple” and the tool requires an exchange-qualified symbol, the agent may need clarification when multiple instruments are plausible. It must not silently select a listing, substitute a competitor, expand the date range, or convert the currency simply to obtain a successful response. A technically valid call can still be semantically wrong.
如果用户只写“Apple”，而工具要求带交易所的唯一标识，并且存在多个可能标的，Agent 就可能需要澄清。不能为了让调用成功而默默选择某个上市地点、替换成竞争公司、扩大日期范围或转换币种。技术上有效的调用仍可能在语义上完全错误。
Designing the Output Validation Prompt
如何设计工具结果验证 Prompt
Many prompt stacks stop after the API returns a 200 response. Reliable agents treat the response as untrusted structured evidence. The validator should compare the output with the original request, the selected schema, and freshness requirements before the language model summarizes anything.
许多 Prompt 栈在 API 返回 200 后就停止了。可靠的 Agent 会把返回结果视为“尚未验证的结构化证据”，在语言模型进行总结之前，将其与原始请求、所选 schema 和时效要求逐项对照。
Confirm the same object
确认对象一致
Match stable identifiers, not just display names. A result for a parent company, similarly named entity, or another regional listing should fail validation when it is not the requested object.
用稳定标识符核对，而不只是比较展示名称。若结果属于母公司、同名实体或其他地区上市标的，就不应被误判为用户指定的对象。
Check time and coverage
检查时间与覆盖范围
Read provider timestamps, timezone, reporting period, pagination, and truncation flags. “Latest” is not satisfied by stale cached data simply because the call succeeded.
读取 provider 时间戳、时区、报告期、分页和截断标记。缓存数据过期时，即使调用成功，也不能声称满足了“最新”要求。
Preserve units and caveats
保留单位与限制说明
Validate currency, measurement unit, sign convention, null values, and provider warnings. Never fill a missing value with a plausible number or remove a warning that changes interpretation.
校验币种、计量单位、正负号约定、空值与 provider 警告。不得用“看起来合理”的数字填补缺失值，也不能删除会影响解读的限制说明。
Validate TOOL_RESULT against ORIGINAL_INTENT and TOOL_CONTRACT. Return PASS, PARTIAL, or FAIL. Check: entity identity, requested fields, timestamp and timezone, units/currency, pagination/completeness, provider warnings, and errors. Do not infer missing values. For PARTIAL or FAIL, identify the exact gap and choose: another safe call, user clarification, or limitation report.根据 ORIGINAL_INTENT 与 TOOL_CONTRACT 验证 TOOL_RESULT。 返回 PASS、PARTIAL 或 FAIL。 检查：实体身份、所需字段、时间戳与时区、单位/币种、 分页/完整性、provider 警告和错误。不得推测缺失值。 若为 PARTIAL 或 FAIL，明确指出缺口，并选择：安全追加调用、 请求用户澄清，或如实报告能力限制。
Production Evaluation Matrix for Tool Calling Prompts
工具调用 Prompt 的生产评测矩阵
Evaluate the full decision path rather than counting only successful API calls. A high call-success rate can hide wrong-tool selection, silent substitutions, repeated side effects, or unsupported claims in the final answer. Keep test cases versioned so prompt, model, retrieval, and schema changes can be compared against the same baseline.
评测对象应是完整决策链，而不只是 API 调用成功率。很高的成功率可能掩盖工具选错、静默替换对象、重复产生副作用，或最终答案中出现无依据结论。应对测试集做版本管理，让 Prompt、模型、检索与 schema 变更都能在同一基线上比较。
| Dimension维度 | What to test测试内容 | Failure signal失败信号 |
|---|---|---|
| Intent preservation意图保持 | Entity, action, scope, time range, destination, and constraints remain unchanged.实体、动作、范围、时间区间、目的地与约束未被改变。 | A “helpful” substitution produces an answer to a different request.以“帮助用户”为由替换关键条件，实际回答了另一个问题。 |
| Tool selection工具选择 | Correct capability, freshness, coverage, permissions, side effects, latency, and cost.能力、时效、覆盖、权限、副作用、延迟与成本是否匹配。 | The first lexical match is selected without schema inspection.未检查 schema，只选择名称最相似的工具。 |
| Argument validity参数有效性 | Required fields, types, enums, formats, bounds, and dependent parameters.必填字段、类型、枚举、格式、边界及依赖参数。 | The prompt repeatedly sends the same invalid structure.Prompt 反复提交同一个无效结构。 |
| Recovery behavior恢复行为 | Backoff, retry limits, clarification, equivalent fallback, and idempotency.退避、重试上限、澄清、等价回退与幂等性。 | Permission or not-found errors trigger unsafe retries or duplicate actions.权限或未找到错误触发不安全重试或重复操作。 |
| Result grounding结果依据 | Identity, freshness, completeness, units, citations, and provider caveats.身份、时效、完整性、单位、来源与 provider 限制。 | The final answer invents a missing field or hides stale data.最终答案编造缺失字段或隐瞒数据过期。 |
| Operational efficiency运行效率 | Number of calls, tokens, latency, cache use, and unnecessary tool exposure.调用次数、Token、延迟、缓存使用与不必要的工具暴露。 | The same information is fetched repeatedly or the entire catalog is loaded.重复获取同一信息，或每次都加载完整工具目录。 |
Build cases from real logs after removing sensitive data. Include clear requests, underspecified requests, conflicting constraints, malformed arguments, empty responses, partial pagination, timeouts, rate limits, revoked permissions, prompt injection inside tool output, and irreversible actions. Review regressions by severity: one silent identity substitution matters more than several recoverable formatting failures.
测试用例可来自脱敏后的真实日志，应覆盖明确请求、信息不足、约束冲突、参数畸形、空结果、分页不完整、超时、限流、权限撤销、工具结果中的 Prompt 注入和不可逆操作。回归问题要按严重度评审：一次静默替换实体，通常比多次可恢复的格式错误更严重。
Implementation Checklist: From Prompt to Controlled Execution
落地清单：从 Prompt 到受控执行
Translate the request into an outcome and retrieve a narrow candidate set. Keep irrelevant tool descriptions out of context.
把请求转成目标结果并检索一小组候选能力，不把无关工具描述塞进上下文。
Read the exact schema, examples, permissions, side effects, limits, and freshness contract before argument generation.
生成参数前，读取准确 schema、示例、权限、副作用、限制与时效契约。
Validate arguments, attach an idempotency key where supported, enforce timeouts, and record the rule and prompt versions.
校验参数，在支持时加入幂等键，执行超时控制，并记录规则与 Prompt 版本。
Check the returned identity, units, timestamp, completeness, warnings, and provenance before composing an answer.
生成答案前，检查返回对象、单位、时间戳、完整性、警告与来源。
Prompt text is only one control layer
Prompt 文本只是控制层之一
Enforce permissions, argument schemas, timeout limits, idempotency, network boundaries, and approval gates in code. A model instruction can guide behavior, but it should not be the sole protection for data access, financial transactions, file deletion, messages sent to third parties, or any other high-impact side effect.
权限、参数 schema、超时、幂等性、网络边界和审批门槛必须在代码层执行。模型指令可以引导行为，但不能成为数据访问、金融交易、文件删除、向第三方发送消息或其他高影响副作用的唯一保护措施。
External Reference for Tool Calling Standards
工具调用标准的外部参考
For readers comparing prompt layering with broader agent tooling standards, the Model Context Protocol documentation explains a widely used approach to standardizing how clients discover and invoke tools through declared interfaces. Prompt policy and protocol design solve different layers of the problem: the protocol describes what can be called, while the prompt and runtime controls decide whether, when, and how a call is appropriate.
如果需要把 Prompt 分层与更广泛的 Agent 工具标准进行比较，可以参考 Model Context Protocol 文档，了解客户端如何通过声明式接口发现和调用工具。Prompt 策略与协议设计解决的是不同层面的问题：协议描述“可以调用什么”，Prompt 与运行时控制则判断“是否应该调用、何时调用以及如何调用”。
AI Agent Tool Calling Prompt FAQ
AI Agent 工具调用 Prompt 常见问题
What should an AI agent tool calling system prompt include?
AI Agent 的工具调用系统 Prompt 应包含什么？
Include rules for preserving intent, selecting tools, validating required arguments, checking permissions, limiting retries, requesting clarification, validating results, and logging decisions. Put enforceable security controls in code rather than relying on prompt wording alone.
应包含意图保持、工具选择、必填参数校验、权限检查、重试限制、澄清条件、结果验证与决策记录。可强制执行的安全控制应放在代码层，而不是只依赖 Prompt 表述。
When is automatic schema repair safe?
什么时候可以安全地自动修复 Schema？
Repair is usually safe when it changes representation without changing meaning: an approved alias, unambiguous type conversion, documented enum, or equivalent date format. Identity, action, scope, currency, destination, permissions, and irreversible options should not be guessed.
如果修复只改变表达、不改变含义，通常可以自动执行，例如已批准的别名、含义唯一的类型转换、文档明确的枚举或等价日期格式。实体、动作、范围、币种、目的地、权限和不可逆选项都不能猜测。
How many tools should be placed in one prompt?
一个 Prompt 应该放多少个工具？
There is no universal number. The useful target is the smallest candidate set that still contains a sufficient tool. Retrieve by intent, inspect exact schemas, and avoid loading a full catalog on every turn; this reduces confusion, tokens, and accidental exposure.
没有适用于所有系统的固定数量。合理目标是“仍包含足够能力的最小候选集合”。应按意图检索、检查准确 schema，避免每轮加载完整目录，从而减少混淆、Token 与意外暴露。
When should the agent ask the user for clarification?
Agent 什么时候应该向用户澄清？
Ask when a missing or ambiguous value would change the requested object, scope, time range, destination, permission, cost, or side effect. Do not ask about details that the tool can safely derive from an explicit rule or validated context.
当缺失或模糊信息会改变对象、范围、时间区间、目的地、权限、成本或副作用时，应向用户澄清。若工具可以根据明确规则或已验证上下文安全推导，则不必增加无意义追问。
How should tool calling prompts be tested?
如何测试工具调用 Prompt？
Maintain a versioned evaluation set covering success, ambiguity, invalid arguments, tool errors, permissions, stale and partial results, unsafe substitutions, injections, and side effects. Compare intent accuracy, tool choice, schema validity, recovery, grounded output, latency, and cost.
维护版本化评测集，覆盖成功、歧义、无效参数、工具错误、权限、过期或不完整结果、不安全替换、注入和副作用，并比较意图准确度、工具选择、schema 有效性、恢复表现、结果依据、延迟与成本。