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

Annotations already declare readOnlyHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is covered; the description adds real behavior beyond that: it resumes messaging real people and triggers an owner email notification. It does not describe error responses or what a partial failure across multiple accounts looks like, which is the remaining gap for an openWorld multi-account mutation.

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 short sentences, front-loaded with the action and side effects, followed by prerequisites then edge cases. Every sentence contributes a distinct decision-relevant fact and the sibling reference is embedded inline rather than padded out.

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 two-parameter mutation with no output schema and full annotation coverage, the description supplies preconditions, side effects, and the ended-state exception, which is nearly everything an agent needs. The only shortfall is that it never says what the tool returns or how to confirm success apart from the owner email.

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 schema already documents ends_at format and the empty-string behavior, so most parameter meaning is structured data. The description still adds non-schema context: that ends_at is only required to revive an automation whose ended flag is true, which tells the caller a conditional dependency between state and parameter that the schema alone would not reveal.

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 opening sentence gives a specific verb and resource ('Turn a paused automation back on') plus scope ('on every account it runs on'), which separates it cleanly from sprkly_pause_automation, sprkly_update_automation, and sprkly_archive_automation in the sibling list.

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 states the prerequisite ('A draft has to be finished in sprkly first') and two explicit when-not cases: automations that hit their stop-limit stay off, and ended automations (cross-referencing ended=true in sprkly_list_automations) stay off unless ends_at is supplied. That is a complete decision rule for the caller.

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