TikTok follower demographics and daily performance

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

Annotations already declare readOnlyHint and destructiveHint, but the description adds significant behavioral detail beyond that: demographics are withheld below 100 followers for privacy (not because the audience is unmeasurable), daily numbers lag by up to 48 hours, the look-back is capped at 60 days, and specific fields (bio, verified badge, profile link) are deliberately not readable here. It also explains the auth requirement and that it reports which precondition is blocking, which is valuable behavioral context.

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 long but densely packed with useful information. It front-loads the core purpose, then details preconditions, limitations, and alternatives. The structure is logical and each sentence adds value, though a few explanatory clauses (e.g., 'which is not the same as an audience it could not measure') could be trimmed. Overall it remains clear and well-organized, not repetitive.

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 and lack of an output schema, the description is thorough: it enumerates the data returned, explains preconditions and their handling, notes the look-back and lag, identifies excluded fields and provides the alternative, and specifies the required auth and permission check (tiktalk_account_status). Nothing an agent needs to call 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?

The schema covers 100% of parameters (fields, endDate, startDate) with descriptions. The tool description adds some context — the 60-day cap (already in startDate description) and the lag — but does not introduce new meanings for the parameters themselves. Since the schema already does the heavy lifting, the baseline of 3 is appropriate; the description does not significantly enhance parameter understanding beyond what is already in 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 statement of what the tool does: it returns the connected TikTok account's own analytics, listing specific data types (follower demographics by age, gender, country, city, daily series, lifetime counters). It also explicitly names its twins (instagram_insights and youtube_channel_report), clearly distinguishing it from sibling tools and indicating it is the TikTok counterpart.

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 provides explicit usage context: it is the TikTok twin of instagram_insights and youtube_channel_report, so it is the tool to use for TikTok analytics. It states preconditions for demographics (business account, 100+ followers) and notes that it reports which precondition is blocking, rather than returning empty data. It also directs users to tiktalk_account for bio/verified badge/profile link, and warns that the look-back is capped at 60 days (shorter than brand-mentions tools), giving clear when-to-use and when-not-to-use guidance.

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