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

The readOnlyHint=true annotation covers the safety profile, and nothing in the description contradicts it. The description adds real content-level context — what each topic actually surfaces (e.g. journey includes drop-off and last action before leaving; visits includes the Mixpanel session replay id when recorded) — but says nothing about result size, rate limits, or how missing sources are handled.

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?

A single semicolon-chained wall of text with no paragraph breaks, headers, or front-loading — the reader must parse ~15 parenthetical definitions to find anything. The content is informative but the packaging defeats scanability, and the essential fact (this is a topic dispatcher for one app) is buried at the start of a very long 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?

With no output schema, the description carries the burden of explaining return content, and it does so per topic, which is genuinely useful. But it omits how topic interacts with metric/period/source (e.g. does 'why' require a metric? does 'period' apply to 'reviews'?), and gives no hint of result shape or volume for a tool with 5 parameters and 3 enums.

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 would be 3, but the description goes well beyond the schema here: the topic enum's own description is only 'Which part to answer about', and the description is the sole source of meaning for all 15 values (e.g. 'sources' = store sources, recorded install sources, money by source; 'properties' = latest value per attribute). It does not, however, explain how metric, period, or source interact with specific topics.

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 does convey that this tool returns one data slice (topic) for one app, and the enumerated topic list makes the scope concrete. But there is no verb framing (fetch/return) and no differentiation from siblings that clearly overlap — 'timeline', 'why', and 'ads' topics duplicate the sibling tools timeline, why_did_it_change, and ad_campaigns, and the description never acknowledges that. The mass of detail makes the core purpose harder to grasp than it should be.

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?

There is no guidance on when to pick this tool over the sibling tools. With timeline, why_did_it_change, and ad_campaigns existing as separate tools while this description offers 'timeline', 'why', and 'ads' topics, an agent is left to guess which entry point to use. The topic list implies what can be asked but says nothing about selection criteria or prerequisites.

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