Like, hide or delete a TikTok comment

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial nuance: DELETE is permanent and confirm-gated, HIDE is reversible, UNHIDE is not guaranteed because TikTok's own filters may keep it hidden, and the reply reads back real status rather than trusting a 200. This far exceeds what annotations provide and does not contradict them.

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 two critical TikTok enforcement rules in caps, then covers prerequisites and parameter behavior. The structure is easy to scan, with clear sectioning via numbered rules, and there is no filler or redundancy.

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 a tool with five distinct actions, multiple conditions, and edge cases (delete vs hide, unhide uncertainty, videoId requirements, authorization), the description covers all essential operational aspects. The absence of an output schema is mitigated by the statement that the reply reads back the comment's real status. Nothing an agent needs to invoke this tool correctly 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 coverage is 75% (commentId, confirm, videoId have descriptions; action only has an enum). The description enriches all parameters: it explains the action enum values' semantics, confirms that confirm is required for DELETE, specifies that videoId is required for HIDE/UNHIDE and helps verify changes, and identifies commentId as coming from list_tiktok_comments. It adds meaning beyond 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?

The description opens with a precise verb-resource pair: 'Moderate one comment on a TikTok post the authorized account owns' and enumerates all five actions (LIKE, UNLIKE, HIDE, UNHIDE, DELETE). It clearly distinguishes itself from other moderation tools by scoping to TikTok and to a single comment, leaving no ambiguity about what the tool does.

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 decision rules: 'YOU CAN ONLY DELETE A COMMENT THIS ACCOUNT WROTE — anyone else's can be hidden but never deleted, so HIDE is the tool for an unwanted comment from a stranger.' It also states when videoId is required and when it is optional, and mentions the authorization prerequisite via tiktok_account_status. These are concrete, actionable usage conditions that route the agent correctly.

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