Show Account Top Content

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

Annotations already declare the read-only, idempotent, non-destructive safety profile, and the description adds real behavioral context beyond that: the 2-year maximum date span and the required 'Read detailed stats' permission plus delegate_to_contact behavior. It does not address pagination/result-limit behavior, so it stops short of a full picture.

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?

Front-loaded with purpose, then example, then the optional parameter, then the hard constraint, then permissions — a logical order with little waste. The permission markdown block is somewhat boilerplate-heavy, but it is scannable and does not bury the core task.

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 8 parameters, full schema coverage, and no output schema, the description supplies everything an agent needs: the purpose, the return shape, the trade-off for `hashed_ids`, the 2-year constraint, and auth requirements. Nothing material is left implicit for correct invocation.

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 adds meaning the schema lacks: it explains that `hashed_ids` changes the scope from the whole account and that results remain ordered by `sort_by`, and it states the 2-year range bound that applies to the date parameters. This is genuine added value over the enum/format docs.

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 first sentence states a specific verb and resource ('Rank the account's content by a chosen metric over a date range') and clarifies the return shape ('top media, channels, or folders'). It is clear and concrete, but it never names a sibling analytics tool (e.g. get_account_stats, get_media_analytics) to sharpen the distinction from the many other analytics endpoints.

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?

Offers a concrete use-case framing ('answering questions like "what were my most-played videos last month?"') and explains the specific scenario for `hashed_ids` (fetching analytics for a known list of videos). It lacks explicit when-not-to-use guidance or direct routing to the sibling analytics tools an agent would otherwise pick.

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