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

Beyond the read-only annotations, it discloses staleness (results recomputed hourly), the empty-state behavior before the first run (variants empty plus an explanatory note), and the meaning of termination.should_terminate. What remains unsaid is pagination/limits or permission requirements, which is minor for a read-only report.

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?

The result fields are front-loaded and each sentence carries information — metric list, empty-state caveat, recalculation cadence, sibling routing, dashboard hint. The first sentence is dense and runs long, but nothing is redundant 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 no output schema, the description carries the return-value burden and does so: it names the key response fields, explains the empty/degenerate case, states the refresh cadence, and tells the agent what to do with dashboard_url. Nothing an agent needs to call this correctly or interpret the response is missing.

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 single surface_id parameter is already documented as coming from surface_list. The description adds no syntax, format, or constraint detail beyond that, so the schema does all the work.

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 names the specific resource and enumerates the exact metrics returned (per-variant sessions, goal-reaching sessions, rate_per_session, win_probability, termination.should_terminate, all-time traffic per event). It also explicitly contrasts itself with surface_traffic, so an agent can pick the right tool without inspecting schemas.

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 routes the agent away with a concrete condition: 'For sessions per day, use surface_traffic,' and tells it to point users at dashboard_url for charts. It stops short of saying when surface_get or surface_list should be preferred, and gives no exclusion conditions beyond the one traffic alternative.

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