List comments on one of the brand’s TikTok posts

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

Beyond the annotations (readOnlyHint, destructiveHint, openWorldHint), the description discloses critical behaviors: it returns both public and hidden comments by default, explains the nuance that hidden comments may come from owner hiding vs TikTok's moderation filters (which may refuse to unhide), clarifies that parentCommentId marks replies, and notes the include_replies cap of three. It also states it's read-only and free, reinforcing the annotations without contradiction.

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 every sentence earns its place. It front-loads the core purpose, then layers the key behaviors (status, replies, auth) in a logical flow. There is no fluff or repetition; the length is justified by the amount of critical operational detail (e.g., the distinction between types of hidden comments) that would otherwise be missed.

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 and no output schema, the description covers all essential aspects: what the tool does, how to filter, how to identify replies, the reply cap, auth prerequisites, and related tools for more detail. An agent would know exactly how to invoke it correctly and what to expect in terms of behavior. The mention of tiktok_account_status closes a potential operational gap.

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 50%, and the description adds meaningful value for key parameters: it explains the status enum's default behavior (ALL) and its implications, the include_replies cap of three, and the videoId identification from URL path. It doesn't explain cursor, maxCount, sortField, sortOrder, but those are conventional for list tools and the schema already has enum definitions for sortField/sortOrder. The description compensates well for the coverage gap on the most nuanced 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 ('Read the comments') and resource ('a TikTok post the AUTHORIZED ACCOUNT OWNS'), and explicitly positions it as TikTok's answer to list_meta_comments and list_youtube_comments. This clearly differentiates it from sibling tools and leaves no ambiguity about what it operates on.

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 gives explicit when-to-use guidance (only on owner's posts), explains the status filter to get only public comments, and distinguishes list_tiktok_comment_replies for fetching all replies versus the three-reply cap with include_replies. It also explains the separate authorization requirement and points to tiktok_account_status to check. Nothing is left to inference.

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