mail_merge

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

With no annotations, the description carries the full burden of behavioral disclosure, but 'Execute mail merge operation' discloses almost nothing about side effects. It does not state whether this mutates the document, creates new output, requires a data source, or modifies fields, making the tool's behavior largely opaque.

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?

The description is short and front-loaded, with a clean Args section and no filler. It earns its words, though the brevity leaves substantive gaps elsewhere.

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?

Although an output schema exists, the description omits essential operational context: what mail merge produces, what prerequisites beyond doc_id exist, how it interacts with the document, and how it relates to field-filling sibling tools. The tool has no annotations, so the description is the only source of context, and it is insufficient.

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. It does clarify that doc_id is a Document ID from open_document and that action_params is an optional HMailMerge override object, which adds some meaning beyond the bare schema. However, it does not enumerate or explain valid HMailMerge override keys, so an agent still cannot confidently construct action_params.

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 names a concrete operation ('mail merge') and a verb ('Execute'), and identifies the target through doc_id from open_document. However, it does not explain what a mail merge actually does or how it differs from sibling field-related tools like batch_fill_fields and put_field_text, so it only distinguishes at a surface level.

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?

The only usage guidance is that doc_id comes from open_document, implying a prerequisite. There is no explanation of when mail merge should be chosen over alternatives, what kind of data source is required, or what scenarios it is not appropriate for.

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