TikTok

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

Beyond the readOnly/idempotent annotations, it discloses credit costs per resource, that failures are free, that cached results via max_age_days cost zero, that list resources are paged via an opaque cursor, and that changing `sort` restarts the cursor chain. It also flags the variable AI-transcription pricing for video.transcript, which no annotation conveys.

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 the calling convention and paging/caching rules before the long resource table, which is dense but each line carries a distinct resource signature. Minor waste: '1 credit' is restated on nearly every line when a default could be declared once.

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 18-resource dispatcher with no output schema, the description covers selection, costs, pagination, and caching, which is most of what an agent needs before calling. It does not describe the shape of returned data for any resource, nor point to `describe` for output fields, leaving the agent blind to what a successful call yields.

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 per-resource applicability and, critically, names optional parameters that do not appear in the schema at all (include_pinned, date_posted, publish_time, get_transcript, ai_fallback, allow_long_transcription) and routes them to `params`. It still defers types and allowed values to `describe` rather than explaining them.

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 opening sentence names the platform and the data classes (profiles, posts, videos, transcripts, comments, songs, live streams), then enumerates all 18 concrete resources with their signatures. An agent can tell exactly what this tool fetches and distinguish it from siblings such as youtube, instagram, or tiktok_shop.

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?

It gives an explicit calling convention: pick a resource, pass that resource's parameters as top-level arguments, put extras in `params`, and pass `cursor` back unchanged. It also states the credit/caching policy and per-resource optionals. It does not address when to prefer this over overlapping generic siblings like get_profile, get_transcript, or search, which is a real routing gap.

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