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

With readOnlyHint/destructiveHint already covering safety, the description goes well beyond: it defines hobby=true semantics and its tracking-snippet dependency, warns that metrics are nested under stats.metrics (never flat), flags stats periods as server-time approximations and routes to query_stats for exactness, and documents unit definitions for each metric.

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?

Purpose is front-loaded in the first sentence and the rest is dense but informational, with each sentence carrying distinct facts (schema shape, hobby semantics, empty-account flow, unit definitions). It is on the long side and could be tightened, but no sentence is 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?

No output schema exists, and the description fully compensates by describing the response envelope, the empty-account variant, and metric units. Given closed-world, read-only annotations and a single optional parameter, nothing an agent needs to call this correctly 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%, so baseline is 3. The description adds meaning by spelling out the accepted date_range shape indirectly (Nd) and, more importantly, the exact nested stats.metrics structure it produces plus the units of each returned metric, which the schema only briefly gestures at.

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 verb and resource with scope: 'List the sites this API key can read.' That scoping clause cleanly distinguishes it from create_site, update_site, and the many metric-listing siblings without requiring the agent to open any schema.

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 concrete usage context: 'Use site_id with the other tools', explains the date_range option, and prescribes an action flow when the account is empty (follow next_step, ask user, call create_site then get_tracking_snippet). It stops short of explicit when-not-to-use guidance or naming an alternative list tool.

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