template_replace

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

描述揭示了重要的非显而易见行为：未提供值的变量保持原样并在 missing_vars 中列出；同段落多处占位符按从右到左应用保证坐标正确；跨 run 断裂的占位符也能正确替换。这些细节超出 schema 和 annotations 提供的范围（annotations 未提供，schema 未提及这些行为）。

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

描述紧凑且信息密集，每句话都有明确用途。核心行为在前两个分句中，边界情况（跨 run、从右到左）透明披露，返回结构也说明了。没有冗余。

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

描述涵盖了返回结构（matched, replaced, missing_vars, applied）、边界情况行为和参数含义。但没有明确说明失败模式（如文件不存在、权限问题）或是否修改原文件或生成新文件。考虑到描述已经提供大量行为细节，缺少这些不影响基本使用。

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema 描述覆盖率 100%，所有参数在 schema 中都有描述。描述本身没有为参数添加额外语义，但 variables 参数的行为（未提供值则保持原样）在描述中提到了，这补充了 schema 描述。整体上 schema 已承担主要负担，描述添加了边际价值。

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

描述明确说明工具行为：批量替换 docx 文档中的 {{变量}} 模板占位符，并提到返回值。与兄弟工具如 find_replace 和 apply_edit 有区分（模板占位符替换 vs 通用查找替换/编辑）。

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

描述隐含了使用场景（模板填充、缺失变量报告），但没有明确说明何时使用 vs 兄弟工具（如 find_replace）。没有提供排除条件，但通过描述变量映射和缺失变量行为暗示了用途。

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.