Metis — Fill Document Template

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

With no annotations, the description must carry the full behavioural burden and does much of it: it discloses that letterhead, styles and fixed wording are kept and only listed paragraphs change, and defines destructive semantics (empty string empties, null deletes). It stops short of stating overwrite behaviour, permissions, or what happens with an unrecognised key.

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?

Action and payoff come first, the prerequisite follows, and the Args/Returns block is scan-friendly. Every line adds information; nothing is padding, even though Args partly restates the schema, which is necessary at 0% coverage.

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?

Complete enough to call correctly, and the return description is a bonus given an output schema already exists. What's missing is failure-mode context: unknown paragraph key, no matching template, and whether the output filename collides with an existing file.

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 coverage is 0%, so the description has to document all three parameters and it does: the edits key-to-text mapping with a worked example and null/empty-string rules, template as a partial-name match with the empty-means-first-document default, and filename derivation when omitted. This fully compensates for the bare 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?

States a concrete verb and resource ('Fill a stored Word template') with a clarifying example (ethics-committee cover letter) and a save-copy outcome. It is clearly distinguishable from the sibling read_document_template, which is positioned as the inspection step.

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 prerequisite 'Call read_document_template first to get the paragraph keys' gives an explicit ordering rule that an agent would otherwise get wrong. However, no when-not guidance or alternative (e.g. create_document) is offered for the case where no template exists.

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