Update Template Metadata

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

The description is transparent about side effects, disclosing that expireAt 'can trigger immediate deletion' and that deployedAt affects which version Carbone renders. That said, these disclosures conflict with the annotations: destructiveHint=false, while the tool describes how to trigger immediate, permanent deletion of a template. The annotations signal 'safe, non-destructive update' while the description openly exercises a destructive path, forcing an agent to distrust one signal or the other.

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?

Three tight sentences with zero filler. The first sentence front-loads the metadata list and the next two highlight the two behaviorally significant fields. It earns a 4 rather than 5 because the 'deployment/expiration' phrasing under-sells the genuinely surprising bits (re-parenting, immediate deletion) that the description itself later references.

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 medium complexity of an 8-parameter, 1-required tool with no output schema and no enums, the definition feels mostly complete: units, sentinels, and replace-vs-merge semantics are all covered. However, the description never surfaces the 'id' re-parenting parameter, and the capacity to delete or permanently alter version history is easy to miss. It's adequate for an agent that reads the schema—but that's the schema doing heavy lifting, not the description.

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 100%, and the parameter descriptions are rich: they document the special 'NOW' value (42000000000), time units (Unix seconds), and the difference between Template ID and Version ID. The tool description adds only marginal cross-cutting value, reminding the reader that deployedAt 'activates' and expireAt schedules deletion, but most of this is restated in the schema. With the schema carrying the load, this is a solid baseline 3.

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 clear verb+resource ('Update the metadata of a stored template') and enumerates the exact fields involved (name, comment, category, tags, deployment timestamp, expiration). The two follow-up imperative sentences about deployedAt and expireAt add behavior the field list alone wouldn't convey. It stops short of 5 because it doesn't explicitly distinguish itself from the sibling tools (e.g., upload_template, delete_template) and omits the re-parenting behavior of 'id' entirely.

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 gives explicit parameter-level directives ('Use deployedAt to activate a specific version for rendering. Use expireAt to schedule or trigger immediate deletion.') which guide one aspect of usage well. However, there is no guidance on when this tool should be preferred over template- or document-level alternatives, no exclusions, and no prerequisites mentioned.

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