Twitch

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

Annotations already cover read-only/idempotent/open-world safety, and the description adds materially more: per-resource credit costs, that failures are free, that the response reports credits charged and remaining, that list resources return a cursor, and that max_age_days yields a zero-credit cached copy. That billing/caching/pagination disclosure is exactly the kind of behavior an agent cannot infer from structured fields.

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 a compact block of invocation rules, then a scannable bulleted resource list with costs — no filler sentences. Slightly dense given that cost, paging, and caching rules are compressed into one paragraph, but every sentence carries operational information.

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?

For an 8-parameter polymorphic dispatcher with a nested free-form `params` object and no output schema, the description covers resource selection, per-resource required arguments, cost model, cursor paging, and caching, and it routes to `describe` for types and allowed values. The remaining gap is return-shape detail beyond the cursor and credit accounting, which is unavoidable without an output schema.

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 goes further by mapping parameters to resources and by naming optional per-resource arguments (allow_long_transcription, ai_fallback for clip.transcript; type for user.videos) that exist only inside the free-form `params` bag. It also specifies the transcript pricing tier structure (1 credit up to 2 minutes, then 5 per started minute), which is semantic detail absent from 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?

"Data from Twitch: profiles, posts and videos, events, transcripts" plus an enumerated resource list makes the verb (fetch) and resource (Twitch entities) explicit, and the name pairs it cleanly with the sibling platform dispatchers (youtube, tiktok, kick, etc.). Minor noise: the opening sentence mentions "posts and events," which are not among the five listed resources, slightly muddying scope.

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?

Strong invocation guidance: pick a resource, pass its parameters top-level with extras in `params`, reuse the cursor unchanged, and pass max_age_days for a free cached copy. It does not, however, address when to use this Twitch dispatcher versus overlapping siblings such as get_profile, get_transcript, or search, nor when to prefer `describe` or `call_endpoint`.

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