Comments that mention the brand on TikTok

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral detail: it caps results at top 1,000 by comment likes, warns that TikTok deprioritizes bare @-mentions (so they may not appear), specifies sorting keys, and states the required authorization permissions (brand-insights and comment-list). These are important non-obvious behaviors that go beyond the annotations and help agents set expectations and interpret results correctly.

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?

The description is dense but well-structured: it opens with the core purpose, then differentiates from a sibling, lists preconditions, notes limitations (cap and deprioritization), and closes with sorting and auth requirements. Every sentence contributes unique information with no filler. It is slightly long but justified by the number of critical constraints; the front-loading of the core purpose aids quick comprehension.

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?

Given the tool's complexity (7 parameters, no output schema), the description covers essential contextual aspects: scope, limitations, sorting, preconditions, and auth. It does not describe the return format, pagination mechanics, or available output fields, but the openWorld hint and standard list-tool patterns mitigate some of this. It is nearly complete but missing some implementation details an agent might need for full integration.

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 only 43% (days, regions, maxCount have descriptions; cursor, fields, sortField, sortOrder do not). The description partially compensates by explaining sorting options (VIDEO_LIKES, COMMENT_CREATE_TIME, COMMENT_LIKES) which align with the sortField enum, and mentions the 1,000 result cap (related to maxCount but distinct). However, it does not explain cursor pagination or fields selection, and given low coverage, it leaves gaps. It adds some value but not full compensation for undocumented parameters.

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 states a specific verb ('list'), resource ('comments and replies'), and scope ('anywhere on TikTok whose TEXT @-mentions the connected account's handle'). It explicitly differentiates from sibling tool list_tiktok_mentions by clarifying it covers conversational comments while the sibling covers post captions. This makes the tool's unique purpose immediately clear.

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?

The description explicitly contrasts with list_tiktok_mentions ('This is the conversational half of brand monitoring, where list_tiktok_mentions covers post captions'), providing clear selection criteria. It also lists the four preconditions (public post, 90 days, adult author, BUSINESS account) and warns that an empty list does not mean silence, giving agents practical guidance on interpretation. This is comprehensive usage direction.

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