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

Annotations already cover the safety profile (readOnly=false, destructive=false, non-idempotent), and the description adds real behavioral facts beyond them: the tool returns an inbox preview, plain text is auto-derived from HTML unless text_body is passed, there is a 50,000-char ceiling, and blank layouts are pre-tested/compliant. It does not say what happens if 'name' collides with an existing template, which is the one visible gap.

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 critical behavior (save + preview) is front-loaded and the three starting modes are a scannable list. The trailing HTML/merge-field guidance is long and reads partly like reference documentation, but it is directly actionable for composing the required payload, so it largely earns its space.

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 an 8-parameter write tool with no output schema, the definition covers creation paths, return behavior (inbox preview), format constraints, validation limits, merge-field syntax, image sourcing, and pointers to spur://email-design-guide and spur://merge-variables. An agent has everything needed to call it correctly on the first attempt.

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 is 3, but the description genuinely adds cross-parameter meaning the schema cannot: start_from_blank yields a populated layout that html then replaces, base_template_id copies one of the user's own templates, and text_body is only needed when generation should be overridden. The precedence between these three paths is the main thing still unstated.

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?

Opens with a specific verb+resource ('Save a new email template') plus an immediate benefit ('show its inbox preview'), and the three starting modes make the scope concrete. It never explicitly contrasts itself with spur_update_email_template or the SMS/letter/postcard template siblings, so differentiation is left to the name alone.

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 enumerates three explicit entry paths (blank layout, copy via base_template_id, raw html/text_body) with the condition selecting each, and tells the agent the downstream alternatives (spur_create_workflow / spur_set_workflow_step_template) for using the result. Nearly nothing about when to use this vs a sibling is left to inference.

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