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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: the tool has a listing mode when no funnel or steps are supplied, and it defines what the computation yields (per-step reach and drop-off). It omits step-count limits, how step order affects results, and how the listing mode's output differs from an analysis.

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?

Two sentences, both front-loaded with the highest-value information: what the tool computes, then how to invoke each mode. There is no redundant restatement of the name or title and no filler.

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?

With seven parameters, no output schema, and date/filter complexity, the description covers the two modes and the shape of the result well enough for a correct call. Gaps remain around the from/to and period interplay and around what listing mode actually returns, which matters more given there is no output schema.

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 earns a bump by explaining the mutual exclusivity between funnel_id and steps and by surfacing the zero-argument listing behavior, which is not obvious from the schema. It adds no detail on periods, filters, or website resolution beyond what the schema already states.

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 description gives a specific verb-and-resource framing: conversion analysis through ordered steps, reporting visitors reaching each step and drop-off. It also names the supported step types (page visits, goals, payment). It does not distinguish itself from the sibling list_funnels, which appears to overlap with the no-argument listing mode.

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 clearly states two invocation modes: pass a saved funnel's id/name, or supply your own steps, and notes that omitting both returns the saved funnel list. That is concrete guidance on how to call it. It never says when a caller should prefer get_funnel's listing mode over list_funnels, leaving a real ambiguity for an agent choosing between siblings.

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