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

Beyond the readOnly/destructive annotations, it discloses late-arriving data (2-3 days, revenue lags further), the meaning of placeholderDays and missingDays ('treat as unknown, never zero'), the refusal behavior for stale connections, that it returns no ad spend, paging via nextCursor, and the important trafficClass caveat that 'organic' includes ad sessions. This is rich operational context the annotations cannot convey.

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 and dataset list are front-loaded, and most sentences earn their place with non-obvious guidance. It is dense as a single block, and the multi-sentence trafficClass/organic discussion is long for a tool description, though the nuance is relevant to correct interpretation.

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?

An output schema exists, so return values need not be explained, and the description covers everything else an agent needs: dataset selection, filtering, paging, latency and coverage semantics, refusal conditions, and what the tool deliberately omits. Nothing material for correct invocation 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 description coverage is 0%, so the description must carry the load, and it largely does: it explains each of the 11 dataset enum values and the metrics they contain, the videoIds filter's applicability to video_daily, paging via cursor/nextCursor, and format=summary. It leaves limit, startDate/endDate semantics (inclusivity, timezone), and artistId unexplained, so it is strong but not fully compensating.

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 opens with a specific verb and resource ('Get YouTube Channel Data'), scopes it to an artist's own connected YouTube channel, and states the shape of the result (daily rows from the YouTube Analytics warehouse, paged). It enumerates every dataset the tool can return, making it unmistakable against siblings like dynamoi_get_artist_analytics or dynamoi_get_campaign.

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?

Explicit when-to-use ('for data science on an artist's own connected YouTube channel'), when-not ('Not available yet: audience demographics, per-video traffic sources and per-video search terms'), prerequisites ('Needs a connected channel; a channel that must be reconnected is refused'), and routing ('Before judging a campaign's strategy, read the strategyGuide from dynamoi_get_campaign'). It also tells the agent to compare periods itself rather than rely on attribution.

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