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

Annotations only declare it is a non-read-only, non-destructive, non-idempotent write. The description adds real behavioral context beyond that: saving is inert until a start/trigger call, plan gating surfaces as 403 plan_required, and exit_conditions cancel a run when an event or condition matches. It does not mention what happens on duplicate names or whether repeating the call creates a second draft, which is the one gap for a non-idempotent create.

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?

It is front-loaded with the definition and the inert-until-started constraint before the long action mapping, so the critical facts come first. The action-to-tool enumeration and the multi-paragraph 'webinar' example are dense but each earns its place as concrete guidance; the example could be trimmed without much loss.

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 6-parameter, deeply nested create tool with no output schema, the description covers what an agent needs: the draft-only semantics, the execution model, supported versus unsupported step types, plan gating, exit conditions, and a worked end-to-end example. Missing return-shape detail is minor because the tool's product is a saved draft and the description leaves no ambiguity about the call's effects.

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?

Top-level schema description coverage is only 17%, so the description must compensate, and it does: it maps each action value to the equivalent sibling tool (send_email = send-email, update_subscription = bulk-unsubscribe/resubscribe, etc.), explains the flow-step semantics of wait, wait_until modes and branches, condition, goal (runs jump to it), experiment, run_automation and end/end_run, and clarifies that settings.exit_conditions takes an event or a condition. It leaves 'context' and 'connections.branch' largely to the schema, but the added meaning is substantial.

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 first sentence states a specific verb and resource ('Save a new automation as a draft') and enumerates the shape it takes (trigger step, action steps, connections between step keys). It immediately separates itself from the sibling tools that launch automations by stating that saving runs nothing and that start-automation/trigger-automation are what execute it.

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 names the alternatives explicitly (start-automation for each matching event, trigger-automation for a single run) and gives exclusions: webhook steps can only be added via dashboard or REST API, and goal steps / custom events require Pro or Business with contact.on_event needing Business (403 plan_required). That is a genuine when-to-use / when-not / prerequisite set rather than vague context.

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