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

Annotations already declare this is a non-read-only, destructive-hinted mutation, so the safety bar is partly covered. The description adds value the annotations cannot: the ownership prerequisite ('only the author's own draft') and the return value ('Returns the saved_template_id', important since there is no output schema). It does not say whether an existing template with the same name is overwritten, which is the main behavioral gap for a destructive-hinted tool.

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?

Front-loaded with the action and object, then constraints, then the return value — good ordering. Slightly padded by the clause 'so the same inputs can be generated again from the generator or from chat', which restates the purpose rather than adding new constraint information.

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?

Covers all required elements for a 2-param mutation with no output schema: what it does, prerequisite ownership, parameter provenance, and the returned identifier. The only meaningful omission is collision/overwrite behaviour given destructiveHint=true.

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%, so the baseline would be 3. The description still adds provenance semantics: artifact_id must come from a generator (or list_artifacts), and name is a short, human-recognisable label — which tells the agent what a good value looks like rather than just its type.

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 specific verb ('Save ... as a template') and resource ('generated image, email or PDF') plus where it lands ('user's Second Brain'). This clearly separates it from the generate_* family and from list_templates, so an agent can distinguish it without opening schemas.

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?

Gives concrete usage context: it follows a generator, takes the artifact_id that generator returned, and enables re-generation from the generator or chat. It also states the eligibility condition ('Only the author's own draft can be saved'), but never names an explicit alternative or when not to save (e.g. vs. sharing an artifact or using an existing template).

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