batch_apply

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

With no annotations provided, the description carries the full burden, and it delivers strong behavioral detail: per-file atomicity, validated saves, failure handling, stop_on_error semantics, preservation of already-saved files, and refusal of files open in Word. This goes well beyond what the schema or parameter names alone convey.

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 dense but well-organized: purpose and example first, then the operations contract, allowed tools, and per-file behavior. Every sentence adds operational value, and there is no filler or repetition of schema content.

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?

For a complex batch tool with no annotations, the description covers the critical invocation details: how to structure operations, which tools are allowed, failure semantics, and file-open refusal. It falls slightly short on fully explaining backup behavior and the phrase 'prev/anchor slot rotation,' which may be domain-specific jargon that an agent would not understand without further context.

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 explains the operations array format ('[{'tool': name, 'params': {...}}]'), the file_path exclusion, and the allowed-tool whitelist, and it also gives stop_on_error behavior. However, the backup parameter is never described, which is a notable gap given the low schema coverage.

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 opens with a specific verb and resource: 'Apply the same operations to MANY documents in one call,' with a concrete example (updating a footer across 50 templates). This clearly distinguishes it from the long list of sibling tools that act on single documents or single operations.

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 description makes the intended use obvious: batch repeated operations across many documents, and it lists exactly which tools are allowed inside the batch. It also gives an important exclusion ('Refuses files open in Word') but does not explicitly state when NOT to use it, such as for one-off single-document edits.

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