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

Goes well beyond the annotations by disclosing cost ($0.001 per call, free on failure), the reversibility contract (empty string restores the original), the blast radius (facts, links and buttons are untouched), and the text format rules (plain text, blank line = new paragraph). These are all consistent with destructiveHint=false and idempotentHint=true.

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?

Four tight sentences, front-loaded with the verb and scope, then the dependency, the reversibility rule, the formatting rule and the cost. No filler, and each sentence carries a fact an agent needs to call it correctly.

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 a 4-parameter mutation with no output schema, the description covers scope, cost, failure behavior, variable sourcing and formatting. It does not say what the response contains or whether the change is immediately live, but with no output schema that gap is minor.

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 only 25%, so the description carries real weight: it explains the empty-string reset semantics, the {variable} placeholders permitted in values, and the plain-text/blank-line formatting for the text fields. It leaves the mapping of individual parameters (e.g. which field the 200 vs 4000 character limits apply to) to the schema, which is acceptable.

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 and resource ('Change an email's subject, headline or opening words') and bounds the scope explicitly: the underlying facts, links and buttons stay fixed. It also names the sibling read tool it depends on (account_list_email_templates), so an agent can distinguish it from listing or brand tools without opening a schema.

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 clear operative context: variables must come from account_list_email_templates ({name}, {when}), and passing an empty string reverts to the original wording. It stops short of explicit when-not-to-use guidance (e.g. that this cannot change times, places or amounts, only the wording), so it lands at clear-context-but-no-exclusions.

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