fill_template

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly: it states mutation occurs in place, formatting behavior across runs, missing-key semantics for each mode, auto-backup behavior, atomic validated saving, and refusal to operate on Word-open documents. This goes well beyond simply naming the operation.

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?

Every sentence and clause adds distinct value: scope, placeholder behavior, missing-mode semantics, copy alternative, backup behavior, save behavior, and safety condition. The information is dense but organized, front-loading the core purpose before details.

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?

Given the complexity of the tool, the lack of annotations, and the presence of an output schema, the description is complete enough for correct invocation. It covers mutation semantics, parameter behavior, failure modes, backup behavior, and a key operational restriction, leaving no critical gap.

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 description coverage is 0%, so the description must compensate, and it does: it explains the meaning of data[name], defines all missing modes ('error', 'skip', 'empty'), and clarifies backup=False behavior. It also makes the file_path and data semantics clear through usage context such as 'template' and 'data lacks'.

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?

The description states a specific action ('Fill a template IN PLACE') and identifies both target mechanisms: replacing {{name}} placeholders and setting MERGEFIELDs. It also differentiates from mail_merge, so an agent can distinguish it from a closely related sibling without inspecting schemas.

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?

It gives an explicit when-to-use signal by contrasting in-place filling with producing copies, directing the agent to mail_merge for the copy behavior. It also details the missing-mode options and warns that the tool refuses documents open in Word, which helps an agent decide whether to call it.

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