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

Adds substantial context beyond the annotations: the 2-8 step constraint, the ordering rule, the rule that a 'not:' step can never be first, and that funnel names are unique per site. The idempotency claim ('a retry does not fail or make a duplicate') sits in tension with idempotentHint=false, though it is defensible as key-dependent behavior rather than a flat contradiction.

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?

One long run-on paragraph packs the step grammar, the global rules and the retry advice together with no visual separation. Every sentence earns its place, but the density hurts scannability and the 'not: never the first step' constraint is buried mid-sentence.

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?

There is no output schema, and the description never says what comes back on success (e.g. the new funnel's id), which an agent likely needs for follow-up calls. Otherwise the creation contract — inputs, constraints, validation path, retry safety — is fully covered.

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 75%, but the description goes well past it: it enumerates every accepted string micro-syntax ('page:/path', 'page:*blog*', 'page:/docs*', 'goal:name', 'not:name') and mirrors the object form with its match enum. That is exactly the semantics an agent needs to build a valid steps array.

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 the resource (funnel) and that it is persisted ('Save a funnel in the dashboard'), which is clear enough to act on. However, the verb 'save' is ambiguous against siblings update_funnel and get_funnel — nothing says this creates a new funnel rather than modifying an existing one.

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 a concrete pre-flight instruction: 'Check the steps first with get_funnel and steps', and tells the agent to pass idempotency_key on retries. It stops short of routing explicitly to update_funnel for existing funnels or saying when not to use it.

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