Save a template as a draft

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

Beyond the annotations, it discloses the key behavioral trait that the save is draft-only and does not affect renders until a person publishes. It also covers authorization requirements, the return contents including review_url, the validation loop with sample data, base_checksum conflict behavior, and plan-limit implications.

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 appropriately sized for a 13-parameter mutation tool with nested objects. The most important fact, that this saves a draft and never publishes, is front-loaded, and each subsequent sentence adds operational guidance rather than repeating schema 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?

It covers the essential context an agent needs: draft semantics, the two invocation modes, prerequisite read via get_template_source, authorization, unsupported template types, validation expectations, and the review workflow. Although an output schema exists, the description's mention of review_url and validation errors is still useful for agent behavior.

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 already 100%, so the schema carries most parameter documentation. The description still adds meaningful semantics beyond the schema for the central parameters: partial updates keep unchanged parts from the read version, base_checksum detects newer versions, and change_note is read by the person before publishing.

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 verb and resource ('Saves a template as a draft') and immediately distinguishes it from publishing or rendering by noting that renders keep using the published version. It also clearly separates the two save modes: updating an existing template versus creating a new one.

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 explicit workflow guidance: read with get_template_source first, change only what the user asked for, and pass template plus base_checksum for an existing template, or new_template plus html for a new one. It also names a limitation (Word and PowerPoint templates cannot be saved here), which helps the agent avoid misuse.

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