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

Annotations already declare readOnly, idempotent, closed-world, non-destructive behavior, so the description only needs to add the non-obvious constraint — that results depend on the heatmaps tracker feature being enabled and that get_site is how you verify it. It also characterizes the returned metrics (rage clicks, dead clicks, scroll-depth percentages), which annotations do not cover. It doesn't mention empty results when the tracker is off or any data-retention caveats.

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?

Three sentences, front-loaded with the purpose, then the two result modes, then the prerequisite. Every clause carries information an agent needs before calling; there is no restatement of the name or title.

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 9 parameters, no output schema, and high schema coverage, the description does its main job: it describes what comes back in each mode and discloses the feature-flag prerequisite. Minor gap — it doesn't note that output is a ranked, limit-capped list or what an empty result means when the tracker is disabled.

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 89%, so the baseline is 3, but the description genuinely adds meaning beyond the schema: it explains that page_path acts as a mode switch that changes the entire result shape, whereas the schema only says 'e.g. /pricing'. Hostname is contextualized as only relevant with page_path when a site serves several hostnames. Limit, device, and the date/period interplay are left to the schema.

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 a specific resource (click positions and scroll depth) with a verb-like framing and then splits behavior into two explicit modes keyed on page_path: page ranking with rage/dead clicks and scroll depth, versus per-page element ranking with CSS selectors and 25/50/75/100% reach buckets. That level of specificity makes it unmistakable against siblings like get_link_clicks or get_breakdown.

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 clear when-to-use rule for each mode ('Without page_path...', 'with page_path...') and a prerequisite: the heatmaps tracker feature must be enabled, checkable via get_site. It stops short of explicitly steering away from related siblings (e.g., link clicks or general breakdowns), so it's strong context rather than full routing guidance.

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