TokConnect: TikTok Research

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

With no annotations, the description carries the full burden and does substantial work: it states the data provenance (values come from TikTok), warns not to assume counts are percentages, instructs retention of source units, clarifies that missing breakdowns mean unavailable data rather than zero, and rules out pagination. It stops short of auth/permission or rate-limit context, but the interpretation caveats are the higher-value disclosure for an analytics tool.

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?

Four tight sentences, no repetition, and the most important framing (what is fetched and what it is not) comes first. Each remaining sentence carries a distinct data-interpretation constraint, so nothing is filler.

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?

No output schema exists, so the description must pre-empt confusion about the return payload, and it does: what dimensions come back, that values are raw TikTok units, that missing data is not zero, and that there is no pagination. For a two-parameter read tool this is fully sufficient.

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 100%: days (enum, default 30, 'does not define the aggregation period') and query_id (what it is and what it is not) are both documented in the schema. The description adds only marginal framing via 'one search topic over a requested window,' so the baseline 3 is appropriate.

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?

Names a specific verb (fetch) and resource (TikTok country/gender/age breakdowns and demographic summaries) scoped to one search topic over a window. It then explicitly disambiguates against adjacent resources: 'not a creator's followers or a specific video's viewers,' which separates it from creator_followers, user_profile, and video_detail.

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?

States the applicable scope clearly (one search topic, requested window) and rules out the two most likely mis-selections, creator followers and video viewers. It also ties query_id back to its producers (search_topics, browse_topics, trending_topics, related_topics), though it does not give an explicit when-to-use statement or exclusions beyond those two cases.

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

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

With no annotations, the description carries the full burden and does well: it discloses the returned fields, the pagination contract (nextOffset only when hasMore), and an eligibility prerequisite for the followers channel. It does not cover auth requirements or rate limits, but the behavioral core for a read-only paginated feed is present.

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 core action, then dense semantic notes. Every sentence carries information (feed identity, field list, channel caveats, pagination rule), though the channel-by-channel caveats make it slightly listy rather than tightly prioritized.

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?

No output schema exists, so the description compensates by enumerating return fields and the pagination contract. Channel semantics and the trending/category routing note cover the main ambiguities of a 4-param, 12-value-enum feed browser; only auth/rate-limit behavior is left unstated.

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 limit/offset/channel/language are already documented. The description does add channel meaning (content_gap is TikTok's feed not a computed score; followers refers to the connected account), which is genuine added value, but it also references a 'nextOffset' that does not exist in the schema (the parameter is 'offset'), creating a minor mismatch rather than clean enrichment.

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?

States a specific verb and resource ('fetch one page of search topics from a selected Creator Search Insights feed') and explicitly negates adjacent content ('not videos or creators'), so an agent can distinguish it from search_videos/creator_posts without opening a schema.

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?

Gives real usage context: content_gap and followers channel semantics, the note that trending/category channels route to the same feed as trending_topics, and the rule to pass nextOffset only when hasMore is true. It stops short of an explicit 'use this instead of search_topics/topic_detail when...' routing statement, so it is clear context rather than full when/when-not guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses pagination, which is useful, but does not state authorization needs, rate limits, whether replies are nested or flat, or any mutation (it is read-only). For a read tool with no annotations, this is adequate but not rich.

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?

Two short sentences, front-loaded with the core action and followed by the required parameter source. No wasted words.

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 4 parameters with full schema coverage, no output schema, and no annotations, the description covers the essential call pattern and pagination. It could add more about return shape or auth, but it is sufficient for an agent to invoke correctly.

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 100%, so the schema already documents count, cursor, aweme_id, and comment_id. The description adds the required sourcing of comment_id from video_comments, which is valuable procedural context but does not add format or constraint details beyond the schema. Baseline 3 applies.

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 and resource ('Read the replies to one comment') and ties itself to the sibling video_comments by referencing commentId from that tool. An agent can distinguish this from video_comments without inspecting schemas.

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 clearly indicates the context of use ('Pass a commentId from video_comments') and its role as a dependent read after fetching a comment. It does not explicitly state when not to use it (e.g., instead of fetching top-level comments), but the workflow is clear.

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

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

With no annotations, the description carries the full burden and does well: it discloses provenance (TikTok-generated), a meaningful empty-result state, and explicit constraints against polling, pagination, and fabrication. It does not state read-only status, auth requirements, or rate limits, which keeps it from a 5.

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?

Four sentences, each earning its place: purpose, provenance/disambiguation, empty-state handling, and operational limits. Front-loaded with the core action and free of padding.

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 no output schema, the description enumerates what the response may contain and warns of empty results, which is the key completeness gap for this tool. Minor omissions (auth expectations, explicit read-only framing) are the only shortfall.

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% and the query_id description already explains its origin (search_topics, browse_topics, trending_topics, related_topics) and what it is not. The description only restates 'one CSI queryId', adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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?

States a specific verb and resource ('retrieve available guidance for one CSI queryId') and enumerates the content types returned (hashtags, insights, script outlines, title ideas). It further distinguishes this from other tools by clarifying that the material is TikTok-generated, not produced by TokConnect.

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?

Gives clear when-not guidance: some topics have no guidance ready and the agent should report that rather than invent it or promise future generation. It also states there is no automatic polling or pagination. It stops short of naming a sibling as the alternative (e.g., search_topics to obtain a queryId), which the schema covers instead.

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

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

With no annotations, the description carries the burden and does so well: it discloses that the list is potentially limited and not guaranteed complete, and that restricted lists fail with an upstream error. It omits auth/permission requirements and rate-limit behavior, which keeps it from a 5.

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?

Three dense sentences, front-loaded with the core action and then the return shape, followed by the limitation and pagination rule. Every sentence carries distinct information and there is no filler.

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 paginated read tool with no annotations and no output schema, the description covers return fields, pagination discipline, dataset limitations, and error behavior. The main remaining gap is authentication or access prerequisites for private/restricted creators.

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 real meaning by tying max_cursor/min_cursor to the returned cursor values and constraining their use to when hasMore is true. That operational guidance goes beyond the schema's per-field strings.

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?

States a specific verb ('Get one native page') and resource ('TikTok's available follower list') with explicit scope ('for the specified creator'). It also distinguishes itself from the sibling audience_demographics by stating it is 'not audience demographics', so an agent can tell the tools apart without opening schemas.

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?

Gives concrete usage rules: advance cursors only while hasMore is true, and expect an upstream error for restricted lists. It implicitly routes away from audience_demographics for demographic data, but does not explicitly state when to prefer creator_following or other list tools, so it stops short of the full when/when-not/alternatives bar.

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

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

With no annotations, the description carries the full burden and does well: it discloses that TikTok may restrict or truncate results, warns against inferring complete counts from a single page, explains the hasMore/cursor contract, and rules out mutation. It omits auth or rate-limit context, keeping it just short of exhaustive.

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?

Four tight sentences, each doing distinct work: purpose, return shape, truncation caveat, pagination rule, and non-mutation disclaimer. The scoping verb+resource leads, and nothing is redundant.

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?

No output schema exists, yet the description enumerates the return fields (userList, minCursor/maxCursor, hasMore, isTruncated) and the pagination semantics. Combined with the fully documented schema, an agent has everything needed to call and page through it correctly.

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 schema already documents count, sec_uid, user_id, and both cursors with formats and defaults. The description adds only the behavioral rule about when to advance cursors, which is usage rather than parameter meaning. Baseline 3 applies.

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?

States a specific verb and resource with scope: 'Get one native page of public accounts followed by the specified creator.' The phrase 'followed by' distinguishes it from the sibling creator_followers (who follows the creator), so an agent can disambiguate the direction of the relationship without opening either schema.

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?

Gives clear operational context: forward cursors only while hasMore is true, and stop when it is false. The closing line 'Does not follow or unfollow anyone' heads off a wrong-intent invocation. It never names a sibling alternative for the inverse direction (creator_followers), so it falls short of explicit when-not/alternatives guidance.

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

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

With no annotations, the description carries the full burden and does most of it: it discloses pagination semantics ("one page"), the condition for cursor reuse ("only when hasMore is true"), the returned entity fields, and the empty-account case. It omits auth/rate-limit behavior, which keeps it short of a 5.

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?

Five tight sentences, zero filler, front-loaded with the purpose and scoping before behavioral caveats. Every clause adds either disambiguation, return shape, or pagination guidance.

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 3-param list tool with no output schema, the description covers return fields, pagination, empty results, and the downstream handoff. The only gap is operational context such as auth or rate limits, which is minor here.

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 meaning beyond the schema: it ties mixId output to playlist_id input and constrains cursor reuse to hasMore=true, which the schema does not state. That extra semantic layer lifts it above baseline.

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?

States a specific verb and resource with explicit scope: "List one page of a creator's public playlists." The phrase "No creator lookup or playlist expansion" and the handoff to playlist_videos clearly separate it from siblings like creator_posts and playlist_videos.

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?

Provides clear usage context and a concrete next step ("Pass a mixId as playlist_id to playlist_videos") plus an exclusion ("No creator lookup or playlist expansion"). It stops short of naming a competing alternative with an explicit when-to-use rule, so it is context-rich but not fully routed.

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

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

With no annotations, the description carries the behavioral burden and does so well: it discloses that page sizes vary, that boundary posts can repeat, and the exact cursor derivation logic. It does not address rate limits or auth, but for a read-only listing operation the disclosed quirks are the meaningful ones.

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 core purpose, then the required input source, then pagination mechanics, then scope exclusions. Every sentence is functional; none is filler despite the density.

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?

No output schema exists, so the description appropriately previews the returned fields and explains pagination quirks, which is what an agent needs to page correctly. Minor gaps remain around error/empty-result behavior, but the coverage is strong for a listing tool.

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 value beyond the schema by encoding the hasMorePrevious -> lastItem.createTime*1000 cursor rule and the 'omit cursor for first page' convention. It gives operational meaning to cursor and sec_uid rather than merely restating their types.

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?

States a specific verb and resource ('Get one native page of a creator's posts') and enumerates exactly what is returned (descriptions, timestamps, engagement stats, video and music data). The closing constraint 'No aggregation, ranking or per-video requests' cleanly disentangles it from search/popularity tools and video_detail.

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?

Gives clear when-to-use context: supply sec_uid from user_profile or video_detail, omit cursor for the first page, and follow the hasMorePrevious pagination rule. The exclusion of aggregation/ranking/per-video use is stated but the alternatives for those excluded needs are not named explicitly, so it stops short of a full 5.

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

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

With no annotations, the description carries the full burden and does well: it discloses the pagination model (native cursor page, no automatic pagination), the visibility authority (TikTok), and explicitly rules out private-data access and per-video enrichment. It does not mention auth or rate-limit behavior, so it falls short of a 5.

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?

Four short sentences, front-loaded with scope and the authored-posts exclusion, then return shape, then negative constraints. Every sentence adds information and none is redundant.

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 no annotations and no output schema, the description compensates by naming the returned fields (itemList, cursor, hasMore) and the pagination/visibility model. Only auth requirements and error behavior are left unaddressed.

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 100%, so cursor, count and sec_uid are already fully documented. The description only alludes to the cursor/hasMore round-trip, adding no syntax or format detail beyond the schema; baseline 3 applies.

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?

States a specific verb (Get) and resource (a creator's publicly available reposted videos), and explicitly excludes authored posts, which cleanly separates it from the sibling creator_posts tool. An agent can pick this tool without opening any schema.

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 'not their authored posts' clause implicitly routes the agent to creator_posts for authored content, and 'one native page' sets the pagination expectation. It stops short of naming the alternative tool or stating when-not-to-use conditions explicitly.

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

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

No annotations are provided, so the description carries the full burden. 'List the categories currently available' implies a read-only operation and it discloses the return payload ('native categoryList metadata'), but it says nothing about auth requirements, rate limits, or whether the list is cached/stable. Adequate but not rich for a tool with zero structured behavioral hints.

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?

Three short sentences, front-loaded with the purpose, then the follow-up action, then the disambiguation. No filler; each sentence adds a distinct piece of information.

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?

There is no output schema, and the description partially compensates by naming the return payload ('categoryList metadata') and the key field ('numeric type') an agent needs for the next step. Combined with the sibling disambiguation, an agent has enough to call and use it correctly, though field-level detail is thin.

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 tool takes no input parameters, so there is nothing for the description to clarify on the input side; baseline 4 applies. The mention of the 'numeric type' field refers to the returned categories and is handled under contextual completeness rather than input semantics.

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?

States a specific verb (List) and resource (categories in TikTok Explore), and explicitly disambiguates from two things an agent might confuse it with: the sibling explore_videos (as a consumer of the output) and the unrelated Creator Search Insights categories.

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?

Gives clear downstream usage guidance ('Use each category's numeric type with explore_videos'), which tells the agent why and when to call this tool. It does not state any exclusions or prerequisites, but for a zero-parameter listing tool the context is sufficient.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses that the result is region/session-influenced and non-exhaustive, and that pagination is not supported. It does not state authentication needs, rate limits, or what happens if the category_id is invalid, so it is adequate but incomplete.

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?

Three tight sentences front-load the core action, then add scope and pagination caveats. Every sentence earns its place and there is no repetition or filler.

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 a simple two-parameter tool with no output schema and no annotations, the description covers the essential behavior: scope, dependency, and pagination limits. It could go further on error handling or auth, but it is otherwise complete for an agent to call this correctly.

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 schema already documents both parameters. The description adds meaning by tying category_id to the explore_categories tool and by clarifying the non-exhaustive nature of count. Baseline 3 is appropriate because the schema does the heavy lifting and the description adds only moderate context.

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?

States a specific verb (Get), resource (TikTok Explore videos), and the dependency (category_id from explore_categories). An agent can distinguish this from search_videos or hashtag_videos because it is explicitly tied to the Explore feed and category IDs.

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 clearly frames this as a 'discovery sample' influenced by region/session and not an exhaustive ranking, which tells the agent when this is appropriate. However, it does not name a direct alternative for exhaustive ranking or general search, so it falls short of the 5-level explicit when-to-use-this-vs-alternative guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implicitly discloses a read operation ('Get') and clarifies that the response is native and unenriched, but does not state read-only status explicitly, nor does it cover auth requirements, rate limits, or error behavior.

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?

Two concise sentences with zero waste. The core purpose is front-loaded, followed by a useful scoping clarification about what is not included.

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 simple detail endpoint with one fully documented parameter and no output schema, the description adequately explains what the tool returns (ch_info, description, counts) and what it excludes. Minor gaps around read-only confirmation and error behavior remain.

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 100% and the single parameter is fully documented in the schema, including its source ('from search_hashtags'). The description adds no additional parameter semantics, so the baseline of 3 applies.

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?

States a specific verb ('Get') and resource ('TikTok's native hashtag detail response') and enumerates included fields (ch_info, description, usage/view counts). The phrase 'No calculated metrics or enrichment' helps distinguish it from potential enriched alternatives, though it does not name a specific sibling tool.

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?

No explicit guidance on when to use this tool versus alternatives. The only hint is that it returns native data without calculated metrics, implying use when raw detail is needed, but there are no named alternatives or conditions.

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

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

No annotations are provided, so the description carries the full burden. It discloses what the response contains (author plus view/like/comment counts) and that results are ranked, which is genuine behavioral value, but it says nothing about pagination semantics, rate limits, or whether results are cached/refreshable.

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?

Three tight sentences, front-loaded with the core action and no filler. The closing sentence is mildly editorial but still carries real usage value.

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 read-only list tool with no output schema, the description covers the return contents and the input dependency adequately. The only minor gap is pagination/cursor behavior, which the schema already labels.

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 100%, so all four parameters are already documented in the schema. The description only loosely gestures at 'ranked' (relating to sort) and 'top' (relating to count) without adding syntax, defaults, or format detail 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?

States a specific verb and resource ('Get the top videos for a hashtag, ranked') with clear scope. It differentiates itself from search_hashtags by declaring the dependency, but does not distinguish itself from near-neighbors like hashtag_detail or sound_videos.

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?

Gives the prerequisite chain ('Feed it the id from search_hashtags') and a clear usage context ('before you commit to it'). No explicit when-not-to-use or named alternative for the same task, so it stops short of a 5.

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

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

With no annotations, the description carries the transparency burden. It usefully discloses the output boundary ("No videos or topic results are returned") and identifies trendingCategories as the supported category list, but says nothing about authentication, rate limits, or response shape for a catalog read.

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?

Four front-loaded sentences that open with the identity, then the usage, then the constraint; little waste. The "CSI catalog" prefix is slightly jargon-heavy and the sibling-key note is a touch tangential, but overall tight.

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 zero-parameter discovery tool with no output schema, the description covers purpose, usage, the key trendingCategories reference, and the contents of the response (metadata only, no videos). Only the exact return shape and auth expectations remain unspecified, which is minor here.

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 input schema is empty with no properties, so there are no parameters to explain. Baseline 4 applies: nothing in the schema needs compensating for, and the description introduces no parameter semantics of its own.

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?

States a specific verb and resource ("list Creator Search Insights channels, tabs and category metadata") and explicitly scopes what it returns versus the sibling tools browse_topics and trending_topics. An agent can distinguish it from the other topic tools without opening any schema.

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?

"Use to inspect available topic feeds" gives clear context, and it names the alternatives (browse_topics, trending_topics) plus the constraint that they only accept schema values, not raw tab keys. It stops short of an explicit when-not or a full prerequisite statement, so it is clear but not exhaustive.

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

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

No annotations, so the description must carry the behavioral burden. It discloses that the returned codes feed other tools and that trending_topics and browse_topics ignore language — a non-obvious routing behavior. It does not document the return shape or pagination, but for a 0-param list tool this is solid.

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?

Three sentences, front-loaded with the resource identity, then usage, then a caveat about trending_topics. Tight and purposeful. Slightly dense but no wasted sentences.

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 no-param, no-output-schema list tool, the description covers identity, downstream usage, and an important exception. The only mild gap is not describing the return format, though for a language list this is largely predictable.

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?

Zero parameters, so baseline 4 applies. The description adds meaning by clarifying the semantics of the returned values (language codes) and their downstream use, going beyond an empty 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?

States a specific verb+resource: list language options for TikTok Creator Search Insights (CSI) catalog. The prefix 'CSI catalog —' disambiguates from the many other TikTok list_* siblings like list_channels.

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?

Explicitly says where to use returned codes (search_topics, browse_topics) and where they are NOT applicable (trending_topics has no language parameter). It routes the agent away from wrong siblings, which is rare and valuable.

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

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

With no annotations present, the description carries the full burden and does so thoroughly: it discloses the request cost model (one video_detail request plus one per 50 comments), the RNG behavior (crypto/rand unseeded vs ChaCha8 keyed by sha256(seed) over id-sorted comments), reproducibility guarantees, and concrete fairness limits (only fetched comments eligible, TikTok's own ordering, replies excluded, deleted/hidden comments invisible). This is well beyond what structured fields provide.

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 paragraph is front-loaded with the purpose and cost model, and every sentence carries information (RNG semantics, return fields, fairness limits). It is dense and somewhat run-on with heavy parenthetical asides, which costs a point against perfect conciseness, but there is no filler.

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 no annotations and no output schema, the description compensates fully: it enumerates the return fields (winners, eligible, fetched, totalReported, coverage, rules applied) and documents the fairness caveats an agent or caller needs to interpret results honestly. Nothing material for correct invocation 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 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: it explains that seed enables reproducibility and should be published, and ties max_comments to a request-cost model ('one request per 50 comments'). It does not, however, elaborate on filters like must_include or unique_users beyond what the schema already says.

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?

States a specific verb+resource+scope: 'Comment giveaway draw ... fetches up to max_comments top-level comments for a TikTok video, applies the stated filters and draws winners uniformly at random.' This is unmistakably distinct from siblings like video_comments or comment_replies, which merely list comments, and the agent can differentiate without opening the schema.

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 opening 'Comment giveaway draw' gives clear context for when this tool applies, and the fairness-limits sentence implies the boundary conditions (only fetched comments eligible, no replies). However, it never names an alternative such as video_comments for plain comment retrieval, nor states an explicit when-not-to-use condition, so it falls short of the 5-level routing guidance.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses what it returns (native poiInfo and available place/share metadata) and a privacy boundary (does not reveal creator or viewer location), but says nothing about auth requirements, rate limits, or error behavior for a public-metadata read.

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?

Three compact sentences, front-loaded with the core action and return shape, followed by the privacy clarification. Every sentence carries information with no padding.

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 no output schema and no annotations, the description steps in to describe the return payload and scope the privacy boundary, which is enough to call the tool correctly. It is slightly thin on behavioral/operational context but adequate for a single-parameter read.

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 100% and the single place_id parameter is fully documented in the schema (numeric public POI ID from poi.id). The description adds the 'from video metadata' provenance but no syntax or format detail beyond the schema, so the baseline of 3 applies.

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?

States a specific verb and resource ('Get public place metadata for a TikTok POI ID') and clarifies the data source ('from video metadata'), which distinguishes it from a generic lookup. It does not explicitly name or differentiate itself from the sibling place_videos, so it falls short of a 5.

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 implies when to use it ('from video metadata', keyed on a POI ID returned in a video's poi.id), but gives no explicit when-to-use, when-not-to-use, or named alternatives such as place_videos. Usage is inferable rather than stated.

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

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

With no annotations, the description carries the full burden and does reasonably well: it names the return fields (itemList, cursor, hasMore) and explains the pagination loop ('Pass returned cursor while hasMore is true'). It omits auth/rate-limit or public-visibility caveats, but for a read-only public-data tool this is solid coverage.

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?

Three sentences, front-loaded with the action, then returns, then usage/scoping. Every sentence earns its place with no repetition or padding.

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?

No output schema exists, but the description names the returned fields and the pagination contract, and clarifies content scope. It leaves the required place_id sourcing unstated in prose (relying on the schema's reference to place_detail), which is a minor 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 description coverage is 100%, so the baseline is 3, and the description adds cursor/hasMore handling semantics ('Pass returned cursor while hasMore is true') that go beyond the schema's 'pass back unchanged' note. It doesn't add detail on count/place_id, so it is a modest gain over 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?

States a specific verb ('Get') and resource ('one native page of videos tagged to a public TikTok place'), and the scoping clause ('not a creator's current location or all content from a city') disambiguates it from sibling search/explore tools. An agent can select it without opening the schema.

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?

'Use for location-specific content research' gives clear context, and the explicit exclusions (tagged content, not creator location, not all city content) sharpen the boundary. It stops short of naming a sibling alternative (e.g., place_detail to obtain place_id), so it lands just under full credit.

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

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

With no annotations, the description carries the full burden and does reasonably well: it declares the return shape (itemList, cursor, hasMore), the ordering guarantee (preserves upstream order and metadata), and two explicit non-behaviors. It omits auth/rate-limit expectations and any note on whether upstream ordering can be trusted across pages.

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?

Three tight sentences: the core action first, then scope limits, then the pagination loop. No filler, no restatement of the name, and every sentence carries information an agent needs.

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?

There is no output schema, and the description compensates by enumerating the returned fields and the hasMore/cursor loop. For a three-parameter read tool this is nearly complete; only auth or rate-limit context is absent.

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 playlist_id, cursor, and count are already fully documented in the schema. The description's cursor guidance duplicates the schema's 'Pass back the returned cursor unchanged,' adding no new syntax or format detail beyond the baseline.

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?

States a specific verb and resource ('Get one native page of videos in a public TikTok playlist') plus the key input ('using its mixId'). The scope qualifier 'one native page' and the exclusion of playlist details separate it cleanly from siblings like creator_playlists and video_detail.

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?

Gives a clear usage context and an explicit pagination rule ('Pass returned cursor while hasMore is true'), and states what the tool does not do (no playlist details, no additional pages). It stops short of naming the sibling to use for playlist metadata, so the when-not branch is only implied.

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

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

With no annotations, the description carries the full burden and does so well: it discloses label-vs-typed topic selection, the isLabel/bestIsLabel fallback behavior, deterministic thresholds (±15%), the perVideo formula, and that failed sub-requests are listed in 'unavailable' rather than silently filled. It omits auth/rate-limit context, but behavioral disclosure is strong.

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 composite scope is front-loaded, but the single dense paragraph over-invests in internal selection minutiae (word-order-ignored matching, 'first five' tiebreak, multiple searchVolume thresholds) that an agent does not need in order to invoke the tool. Significant trimming is possible without losing selection-relevant information.

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?

Since there is no output schema and no annotations, the description correctly compensates by naming the returned fields (topics, best, bestIsLabel, series, audience, videos, perVideo) and the plain-English read, plus failure handling. It is largely complete for a high-complexity composite tool, with only auth/permission context absent.

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 both parameters are already fully documented in the schema. The description mentions the popularity series and country-based scoping only incidentally and adds no syntax or format detail beyond the schema. Baseline 3 applies.

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?

States a specific composite action ('composite product check') and enumerates exactly which upstream requests it performs (search_topics, search_popularity, audience_demographics, search_videos) for a product phrase. This clearly distinguishes it from any single sibling tool it wraps.

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 'composite' framing implies it is the one-shot option versus calling search_topics/search_popularity/search_videos separately, but no explicit when-to-use, exclusions, or named alternatives are given. Usage must be inferred from the mechanics rather than stated.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return container (itemList with creator, video, music and engagement fields), the feed's session/region scoping, and that the call is one-shot with no pagination. It omits rate limits, auth requirements, and any freshness/staleness behavior of the feed, which keeps it below 5.

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?

Four tight sentences, front-loaded with the action, followed by return shape, scope caveat, and invocation constraint. No filler and every sentence adds decision-relevant information.

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?

No output schema exists, yet the description compensates by naming the return container and its fields, and with no annotations it still covers safety-relevant behavior (single request, no pagination) and scope semantics. Nothing an agent needs to call this 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 100% and the single 'count' parameter is fully documented in the schema (range, default, and TikTok-return-may-differ caveat), so the schema does the heavy lifting. The description contributes only the framing that no pagination parameter exists — a useful but minor addition.

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?

States a specific verb and a precisely scoped resource: 'Get one native batch from TikTok's For You recommendation feed.' It explicitly disclaims two confusable scopes — the MCP user's personal feed and a global trending ranking — which is exactly what an agent needs to tell it apart from trending_topics or explore_videos.

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?

Gives strong negative scoping ('not the MCP user's personal feed or a global trending ranking'), which effectively tells the agent when this is the wrong tool, and the region/session caveat sets expectations. It stops short of naming an alternative tool to use instead, so it does not reach a 5.

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

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

No annotations, so the description carries the burden. It discloses the shape of the result ('small native page', 'challengeInfoList') and the semantic nature of the data (suggestions, not search volume), which is useful. However, it says nothing about pagination, auth requirements, rate limits, or whether the list is exhaustive — gaps that matter for an unannotated tool.

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?

Three short sentences, front-loaded with the verb and output name, then the downstream usage, then the caveat. Every sentence earns its place; no filler.

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 single-parameter lookup with no output schema, the description covers purpose, return shape, downstream routing, and the semantic caveat. It stops short of pagination or auth details, but those are minor for this class of tool.

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% and the single parameter already carries its own description ('Numeric hashtag ID from search_hashtags or video metadata'). The tool description adds the constraint that it must be a 'numeric hashtag ID' but otherwise repeats the schema. Baseline 3 is correct when the schema does the heavy lifting.

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?

Specific verb+resource: 'Get a small native page of related hashtags for a numeric hashtag ID.' It also names the return payload ('challengeInfoList') and the downstream siblings that consume the result, distinguishing it from search_hashtags and hashtag_videos. An agent knows exactly what this tool is.

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?

Explicit routing: 'Use the returned IDs with hashtag_detail or hashtag_videos.' It also sets expectations that results are 'related suggestions, not measured search volume,' which tells the agent what not to use this for. The when and the when-not are both present.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the return is the endpoint's raw native payload, that there is no pagination parameter, and warns that not every phrase carries a queryId or search-volume metric. It stops short of describing the actual payload shape, but the caveats are genuinely useful.

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?

Four tight sentences, front-loaded with the core action and the sibling contrast. Each sentence contributes a distinct fact (contrast, payload nature, field caveat, pagination absence) with no padding.

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 single-param tool with no annotations and no output schema, the description supplies the routing, the payload nature, and the expectation-setting caveats an agent needs. Only the concrete return field structure is left unspecified, which the description explicitly tells the agent to inspect at runtime.

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 queryId source is already documented, but the description adds non-obvious information: that there is no pagination parameter (preventing a failed call attempt) and that results should not be assumed to have a queryId or volume metric.

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?

States a specific verb and resource ('retrieve TikTok's related_deep_dive response for one CSI queryId') and explicitly distinguishes itself from the sibling related_topics. An agent can select it without opening the schema.

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?

Gives a clear use case ('adjacent search phrases and query exploration') and names the alternative tool (related_topics) with the condition that differentiates them (native payload vs normalized paginated list). No explicit when-not-to-use case beyond that contrast, but the routing guidance is strong.

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

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

No annotations, so the description carries the burden: it discloses pagination semantics, the hasMore gate for nextOffset, and that records carry queryId values usable in further CSI calls. Does not describe rate limits, auth needs, or failure behavior, and there is no output schema to cover returns.

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?

Three compact sentences, front-loaded with the core action, then sibling differentiation, then the pagination rule. No filler.

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 paginated read with no annotations and no output schema, it covers seed input, page scope, record contents, sibling disambiguation, and continuation. Missing only return-shape and error/rate context, which are minor for this tool class.

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 100%: limit, offset, and query_id are fully documented, including that query_id is not a video ID or username. The description adds only the nextOffset/hasMore relationship, so the schema does the heavy lifting and baseline 3 applies.

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?

States a specific verb and resource: fetch one page of TikTok's related topic records for a seed CSI queryId. Explicitly distinguishes from sibling related_queries ('Unlike related_queries, this is a paginated topic-record feed') and from similar_videos. An agent can route correctly without opening any schema.

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?

Names the alternative it is not (related_queries, similar_videos) and gives continuation guidance ('Continue with nextOffset only when hasMore is true'). Does not state prerequisites or which seed-tool output to use beyond the schema, but the exclusions and pagination rule are explicit.

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

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

With no annotations, the description carries the full burden and does well: it discloses the two-upstream-request behavior, that the return is ordinary video-search results rather than CSI-related or seed-similar videos, and that it cannot pass search_id. It omits auth/rate-limit/error context, but the load-bearing behavioral traits are covered.

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?

Three sentences, front-loaded with what the tool is, then routing guidance. Every sentence serves a purpose (definition, return clarification, alternative routing), though it is fairly dense and slightly repetitive about search_videos.

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?

No output schema exists, and the description compensates by stating the return is ordinary video search results. It covers the mechanism, routing, and continuation limitation; only minor gaps remain (no explicit return shape or permission notes) for a simple read-only helper.

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 baseline is 3, but the description adds rationale the schema lacks — it explains why offset/continuation is unsupported (no search_id plumbing) and reinforces that query_id is a topic queryId, not a video ID or keyword. This gives genuine added meaning beyond the field descriptions.

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 gives a specific verb+resource (CSI topic-to-video search helper), explains the two-request mechanism precisely, and explicitly distinguishes itself from search_videos, similar_videos, and a dedicated CSI related-video response. An agent can select it correctly without opening the schema.

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 states when to use it (queryId known, queryText not), when to skip it (queryText already known, use search_videos directly), and when to use the alternative for pagination/filtering. Exclusions are explicit, including the missing search_id continuation case.

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

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

No annotations are provided, so the description carries the full burden and largely meets it: it discloses the return shape (native data array with upstream result types and metadata), warns that entries are heterogeneous, and specifies the pagination loop condition (reuse cursor and log_pb.impr_id while has_more is true). It omits auth requirements and rate limits, which for an unannotated upstream-scraping endpoint would be useful.

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?

Four dense sentences, purpose front-loaded, and each one carries distinct information (scope, return caveat, pagination mechanics, sibling exclusion). It is slightly compressed — the pagination sentence packs two parameters and a loop condition — but there is no filler to cut.

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 no output schema and no annotations, the description still covers what an agent needs to call it correctly: what comes back (heterogeneous native array), how to paginate, and what it does not cover. Missing auth/permission expectations are the only notable gap for a network-backed search tool.

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 cross-parameter workflow meaning the schema does not: that the returned cursor and log_pb.impr_id must be fed back as search_id for continuation, and that this only applies while has_more is true. That is a genuine relationship between parameters, not a repeat of field docs.

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?

States a specific verb+resource ('Search TikTok's mixed-results endpoint in one request') and immediately distinguishes itself from the many search_* siblings by declaring that no separate creator, video, or sound searches are performed. An agent can tell this is the heterogeneous catch-all search rather than search_videos/search_users/search_sounds without reading any schema.

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?

Gives real usage context: use this for one mixed-results request, inspect entries rather than assume they are videos, and continue with cursor + log_pb.impr_id as search_id while has_more is true. It implies but never names the dedicated alternatives (search_videos, search_users, search_sounds), so routing is inferable but not explicit.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that results carry view counts, video counts, and a commerce indicator, but says nothing about pagination (despite the cursor parameter), rate limits, or permissions, leaving meaningful gaps for a read tool with zero annotation coverage.

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?

Two tightly written sentences with the primary purpose front-loaded followed by a use case; no filler and nothing redundant.

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 no output schema, the description would normally need to explain return values, and it does describe the key returned fields (views, video counts, commerce flag). It stops short of explaining pagination via the cursor, which is the main remaining gap for this tool.

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 100%, so all three parameters (count, cursor, keyword) are already documented in the schema. The description adds no syntax or format guidance beyond that, so the baseline 3 applies.

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?

States a specific verb+resource ('Find hashtags by keyword') and clarifies the returned payload (total views and video counts). It does not, however, name or differentiate itself from close siblings like related_hashtags or hashtag_detail, so an agent still has to infer which one to reach for.

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?

Gives concrete usage context: pick big hashtags before placing them in a caption, and spot commerce-enabled ones. This is a clear 'when to use' signal, but it offers no exclusions or named alternatives (e.g. when to prefer related_hashtags or hashtag_detail instead).

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

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

With no annotations, the description carries the full burden and does well: it discloses a single upstream request, that the response is native/unprocessed data, and importantly that room status and counters reflect the response time rather than historical performance. It omits auth requirements, rate limits, and error behavior, keeping it short of a 5.

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?

Four compact sentences, front-loaded with the purpose before the payload and paging caveats. Dense but every sentence carries information; minor awkwardness in the status/counters sentence.

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 no annotations and no output schema, the description compensates by naming the returned fields (native data, cursor, has_more, log_pb.impr_id) and explaining how to page. An agent can call it correctly and chain pages, though return-shape detail and error handling remain thin.

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 real value by spelling out the pagination loop: use log_pb.impr_id as search_id together with the returned cursor, and it clarifies cursor semantics (returned cursor, default 0) beyond the schema text.

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?

States a specific verb and resource ("Search TikTok LIVE rooms by keyword"), and the LIVE-rooms scope distinguishes it from siblings like search_videos, search_all, and search_users without needing to open any schema.

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?

Gives clear operational guidance for paging (pass log_pb.impr_id as search_id with the returned cursor) and warns there is no automatic paging or analysis, but never states when to choose this tool over the many sibling search_* tools, which is the main selection decision an agent faces.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses the nested return shape (item_list[].imagePost and the legacy search_item_list[].aweme_info.image_post_info.images path), notes that single-image posts are included, warns that image URLs can expire, and clarifies pagination state via has_more. Auth requirements and rate limits are still undisclosed.

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?

Purpose is front-loaded in the first sentence, followed by return shape, pagination, and caveats. The parenthetical legacy payload path is dense but earns its place for agents parsing raw responses; overall there is little waste.

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?

There is no output schema, so the description appropriately explains the return structure and image URL ordering/expiry, which an agent needs. It stops short of covering auth, rate limits, or explicit sibling routing, leaving minor gaps for a keyword-search tool.

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 100%, so all four parameters are already documented in the schema, including that search_id comes from log_pb.impr_id and is required when offset > 0. The description restates the offset/search_id workflow without adding syntax, format, or constraints beyond the schema, so the baseline 3 applies.

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?

States a specific verb (Search) and resource (TikTok photo posts and slideshows) and implicitly separates itself from search_videos by restricting to photo posts/slideshows. It does not name a sibling alternative explicitly, so the agent must infer routing from the resource noun rather than being told.

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?

Gives concrete pagination guidance ('pass cursor as offset and log_pb.impr_id from the first page as search_id while has_more is true') and states scope exclusions ('No image downloading, OCR, analysis or aggregation'). It never names an alternative sibling such as search_videos or search_all for non-photo content, so the routing guidance is incomplete.

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

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

With no annotations, the description carries the full burden and does disclose meaningful traits: return shape (country series with timestamped points and a 'latest' value), no pagination, and that some requested countries may be unavailable. It omits any note on authorization or rate limits, but the operational caveats it does give are valuable.

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-loads what it returns and is dense with constraints, but the 'days does not define the aggregation period' caveat duplicates the schema description, so a small amount of redundancy is present.

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 no output schema, the description is responsible for return semantics and does describe the country-series/timestamped-point/latest structure, plus the no-pagination constraint. Slightly more on how 'latest' relates to the window would make it fully complete.

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 all three parameters are already documented in the schema. The description's points about 'days selects the chart window, not the aggregation period' largely restate the schema wording, and the extra 'global is not a substitute for missing country data' is only marginally additive; baseline 3 applies.

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?

States a specific verb and resource ('fetch the source-reported time series for one CSI queryId') plus the scope of the date window and multi-country option. It is clearly distinguishable from sibling tools like search_topics (which supplies the queryId) and trending_topics.

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?

Gives clear context and explicit exclusions: do not label values monthly search volume, do not sum rolling values, use only returned countries and not global as a substitute. It does not, however, name an alternative tool or state when a different tool would be preferable.

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

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

No annotations exist, so the description carries the burden and does so thoroughly: one upstream request, preservation of native metadata, no auto-paging, no analysis, and explicit return fields (native data, cursor, has_more, log_pb.impr_id). This is rich behavioral disclosure an agent needs to call it 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?

Four short sentences, front-loaded with purpose, then scope caveats, then return values, then paging instructions. Every sentence carries a distinct fact with no repetition.

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?

Covers purpose, return shape, paging workflow, and limitations without an output schema or annotations. It is close to complete for a search tool, though it could mention result ordering or rate-limit behavior, which an agent might need when iterating pages.

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 100%, so the schema already documents all four parameters including defaults, ranges, and the search_id dependency. The description reiterates the paging relationship but adds no syntax or format detail beyond what the schema provides, so baseline 3 is appropriate.

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?

States a specific verb+resource ('Search TikTok sounds by keyword') and distinguishes from siblings by naming sound_videos implicitly and clarifying it is not a trend-growth score. The negative framing ('these are sound search results, not a trend-growth score') is unusually precise about what the tool is not.

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?

Explains the paging workflow (pass impr_id as search_id with returned cursor) and states 'no automatic paging or analysis', giving clear usage context. It does not name an alternative sibling for related tasks (e.g., sound_videos for a sound's videos), so it lacks explicit when-to-use-another-tool guidance.

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

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

With no annotations, the description carries the burden and does add real behavioral context: autocomplete survives rate limiting while full search does not, results include TikTok's own ranking, and user_only switches the response to account suggestions with handles/avatars. It omits auth requirements and the effect of count on behavior, keeping it below 5.

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?

Three tight sentences with the core purpose front-loaded, followed by the flag behavior and the operational rationale. Every clause adds information and nothing is padded.

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 3-parameter read tool with no output schema and no annotations, the description covers purpose, one parameter's semantics, and a key operational trait. It leaves response shape (ordering, count effects, pagination) and any auth prerequisites unspecified, which is a minor gap rather than a blocker.

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 baseline is 3, and the description earns an extra point by enriching user_only beyond the schema's terse 'Return account suggestions instead of queries' — it specifies that those suggestions come with handles and avatars. count and keyword get no additional elaboration.

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?

States a specific verb and resource ('Get TikTok's autocomplete for a keyword') and clarifies the payload ('the exact phrases people type, including the site's own ranking'). The mention of 'full search' implicitly distinguishes it from the many search_* siblings without ambiguity.

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?

Gives clear usage context: it is 'the durable keyword-discovery path' that works 'even when full search is rate limited', and explains when to flip user_only. It stops short of naming specific sibling alternatives to prefer for other tasks, so it is strong but not fully explicit routing.

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

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

With no annotations, the description carries the burden and does well: it discloses the return fields, that only one page is fetched, and the pagination contract (continue with nextOffset only when hasMore is true). It omits auth/rate-limit behavior, but the read-only nature and paging semantics are clearly conveyed.

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?

Four dense sentences, front-loaded with the core purpose, then return shape, then routing, then pagination. No filler or repetition.

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?

No output schema exists, and the description compensates by naming the returned fields (queryId, queryText, popularity, searchVolume, videoCount, trend). Combined with routing and pagination guidance, an agent has everything needed to call and chain it correctly.

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 schema already documents keyword, limit, offset and language. The description adds only indirect value by explaining the pagination concept (nextOffset/hasMore), though it uses 'nextOffset' which does not match the schema's 'offset' param name.

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?

States a specific verb (search) and resource (CSI topic records) with explicit scope exclusions ('not videos or accounts'). The agent can distinguish this from search_videos and search_users without opening any schema.

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?

Explicitly names the alternative for finding videos (search_videos) and enumerates six downstream tools that consume queryId. It gives both when-to-use and when-not-to-use guidance with concrete routing.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the returned fields, warns that follower bounds, verification and sorting apply only to the current page rather than all matching creators (a genuinely non-obvious semantic), and instructs continued paging via nextCursor/searchId even when filters empty the page. That last note is exactly the kind of edge-case behavior an agent would otherwise get wrong.

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?

Four tight sentences with no filler; the core purpose leads, the sibling routing comes second, and the caveats about page-scoped filtering and pagination are grouped at the end where they belong. Every sentence carries information the agent needs.

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 8-parameter search tool with no output schema and no annotations, the description covers purpose, return shape, alternative tool, pagination contract and a subtle filtering-scope caveat. An agent has everything required to call it correctly and interpret the result.

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 and the schema already documents count, cursor, search_id, min/max_followers and verified_only. The description adds meaning beyond the schema by explaining that these filters are page-scoped and by tying cursor to nextCursor/searchId, though it does not clarify the count 1-20 vs maximum 50 mismatch or the maxLength on non-string-ish fields.

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?

Specific verb + resource ("Find TikTok accounts matching a keyword") with the entity types named (creators, brands, competitors) and an explicit enumeration of what comes back (handle, nickname, followers, likes, verification). It is clearly differentiated from the video/hashtag/search siblings by operating on accounts, and it names creator_profile as the drill-down companion.

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?

Gives concrete use cases (build creator lists, size competitors, find partners in a niche) and routes to creator_profile for deeper profile data. It stops short of saying when NOT to use it versus near-neighbors like search_all or user_profile, so it is clear context rather than full when/when-not coverage.

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

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

No annotations are provided, so the description carries the full burden. It discloses return contents (author, counts, media URLs, raw upstream fields like authorStats, music, poi, subtitleInfos) and pagination via searchId – useful behavioral detail. However, it doesn't mention auth requirements, rate limits, or read-only nature beyond inference. Solid but not comprehensive for a no-annotation tool.

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?

Four tight sentences, front-loaded with purpose and scoping, then return contents, then pagination. No filler; every sentence earns its place.

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 no annotations, no output schema, and 100% schema coverage, the description is nearly complete: it explains purpose, when to use, return fields, and pagination. It stops short of covering edge cases (e.g., empty results, rate limits, auth), but for a search tool it is sufficiently complete.

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 100%, so the schema already documents every parameter. The description only adds the searchId pagination mechanism ('pass back the searchId from the first page'), which the schema already implies via 'search_id' description. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

Precise verb (Search) + resource (TikTok's ordinary video results/feed) with an explicit scoping contrast: 'the real feed, not topics'. This clearly distinguishes it from siblings like search_topics, browse_topics, and explore_videos.

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?

Explicitly states when to use it: 'use it to see what content is actually ranking' and contrasts with topics. It does not name alternative siblings (e.g., search_all, explore_videos, search_sounds) or say when NOT to use it, but the usage context and pagination guidance are strong.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return shape (one native itemList with video, creator, music, engagement fields), that similarity and ordering are TikTok's rather than a computed score, and the paging behavior (one request, no automatic pagination, no cursor support). It stops short of stating auth or rate-limit behavior, but the operational traits it does cover are substantial.

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?

Four sentences, each carrying distinct information: purpose, return shape, sibling differentiation, and paging/ordering behavior. Front-loaded with the core action and no filler.

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 no-annotation, no-output-schema tool, the description supplies exactly the missing context: return fields, ordering provenance, and pagination limits. Nothing needed to invoke it correctly is absent.

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 100%, so both parameters are already documented (count 1-30 default 10; video_id sourced from search or detail). The description only restates the seed video_id concept and adds no syntax or semantics beyond the schema, so baseline 3 applies.

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?

States a specific verb and resource ('Get TikTok's recommended videos for one seed video_id') and explicitly distinguishes itself from the sibling related_videos by describing the different mechanism (video-to-video vs topic lookup plus keyword search). An agent can disambiguate from the many sibling tools without opening a schema.

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 names the alternative (related_videos) and characterizes its different behavior, giving the agent a basis for choosing. It does not state an explicit 'use this when / not when' condition, but the contrast is clear enough to route correctly.

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

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

With no annotations, the description carries the full burden. It usefully discloses the return shape (aweme_list, cursor, has_more unchanged) and the key behavioral trait that results are native and unprocessed ('no aggregation or processing'). It omits auth/permission needs, rate limits, and whether ordering is fixed.

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?

Three short sentences, front-loaded with the core action and scope, followed by return fields and pagination guidance. Every sentence contributes; minimal waste.

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 3-param paginated read tool with no output schema, the description names the return fields and explains the cursor loop, which is what an agent needs to call it correctly. Only minor gaps (ordering, auth) remain.

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 100%, so all three parameters (count, cursor, music_id) are already documented in the schema. The description reinforces the pagination semantics of cursor but adds no syntax or format detail beyond what the schema provides, matching the baseline for full coverage.

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?

States a specific verb ('Get'), a precise resource ('TikTok videos using a sound'), and a scope ('one native page'), which cleanly separates it from siblings like search_sounds (finding a sound) and video_detail. An agent can identify the tool's job without opening the schema.

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 explains the pagination workflow (pass the returned cursor for the next page) and the schema points to search_sounds/video_detail for the music_id, giving usable context. However, it offers no explicit when-to-use vs. alternatives or exclusions relative to sibling tools like similar_videos or search_videos.

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

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

No annotations, so the description carries the behavioral burden. It discloses return content and a non-obvious caveat about usesInsightsVideoEndpoint being metadata rather than a functional promise, which is valuable. It doesn't discuss auth, rate limits, or error cases.

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?

Three sentences, front-loaded with purpose, then returns, then exclusions. No filler; every clause adds actionable information.

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?

No output schema, so the description must explain return values, which it does adequately by listing key fields. It also clarifies boundaries against other tools. Missing details on error handling or pagination, but for a single-object fetch that's minor.

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 baseline is 3. The description adds meaning by specifying this is a CSI queryId and clarifying it's not a video ID, username, or keyword—information echoed in the schema but reinforced in the main description.

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?

Specific verb (fetch) + resource (one CSI topic) + identifier (queryId). It also names the exact fields returned and explicitly disambiguates from siblings by stating it does not fetch videos, popularity charts, or demographics.

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?

Clearly scopes what the tool does not do and implies proper usage (single topic lookup by ID). It references source tools indirectly via 'existing CSI queryId' but doesn't explicitly list which tools generate valid IDs, though the schema description does.

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

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

With no annotations, the description carries the behavioral burden well: it warns that ranking/hotness fields are not measured search volume, notes region/session variance, and states there is no pagination. It still omits any auth or rate-limit context, keeping it below a 5.

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?

Four short sentences, all load-bearing: purpose, return shape, sibling disambiguation, caveats. Front-loaded with the core action; slightly dense but nothing is wasted.

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?

No output schema exists, so the description steps in by naming the returned fields (trending_search_words plus source metadata) and flagging interpretation pitfalls. Enough to call it correctly, though return structure detail is only partial.

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% and the single parameter is already documented, so the baseline is 3. The description adds real meaning by framing the call as 'one native batch' with no pagination parameter, clarifying that count is a soft page-size request rather than a traversable cursor.

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?

States a specific verb and resource ('Get one native batch of TikTok web trending search phrases') and explicitly distinguishes itself from the sibling trending_topics with its queryId records. An agent can tell it apart without opening any schema.

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?

Names the alternative ('separate from CSI trending_topics') and characterizes its own scope as web search discovery, giving clear context for selection. It stops short of an explicit 'use this when / not when' rule, but the routing intent is unambiguous.

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

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

With no annotations, the description carries the full burden and delivers substantive traits: what comes back (topic records and queryId values), what does not (videos, sounds, hashtags), that ranking is supplied by TikTok rather than a TokConnect growth calculation, and the pagination rule (continue only when hasMore is true). It omits auth requirements or rate limits, so it is strong but not exhaustive.

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?

Four tightly packed sentences with the identity of the tool front-loaded and no filler. Slight redundancy between 'fetch one page' and the returns clause, and the younger-sibling reference to nextOffset costs a bit of precision, keeping it out of the top band.

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 no output schema, the description steps in and names the returned records and queryId, plus the hasMore gate for pagination, which is what an agent needs to drive the loop. It never defines hasMore or nextOffset as fields (and nextOffset is inconsistent with the schema's offset), leaving a small gap for a paginated read tool.

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 schema already documents limit, offset and the category enum. The description adds the pagination continuation rule but references 'nextOffset', a name that does not match the declared 'offset' parameter, which introduces minor ambiguity rather than clarity. Baseline 3 applies when the schema does the heavy lifting.

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?

Names a specific verb and resource ('fetch one page of TikTok Creator Search Insights trending topics for a category') and scopes it to a single page. It explicitly rules out sibling confusions ('not trending videos, sounds or hashtags') and identifies browse_topics as a routing alias, so an agent can distinguish it without opening another schema.

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?

States the relationship to a sibling clearly: this is the dedicated Trending feed, and browse_topics with 'trending' or a supported category routes here. It does not spell out when this tool should be preferred over browse_topics (the routing is stated as bidirectional-ish but not as a decision rule), so it stops short of a full when-to-use/when-not pair.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the shape of the returned data, which is real value given no output schema, but it says nothing about read-only safety, authentication, rate limits, or behavior on an unknown/nonexistent handle.

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?

Two sentences, front-loaded with the action and returned fields, then the use case. No filler or repetition; every clause adds information.

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 no output schema and no annotations, the description compensates well by listing the returned fields in place of a return-value spec. Remaining gaps are minor operational details (auth, errors, read-only confirmation) rather than anything needed to invoke it correctly.

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 100% and the single 'handle' parameter is already documented in the schema, including the leading-@ tolerance and an example. The description only restates 'by handle' and adds no syntax or format meaning beyond that, so baseline 3 applies.

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?

States a specific verb and resource ('Get a creator or brand profile by handle') and enumerates the exact data returned (followers, following, likes, video count, bio, verification, region, avatar). The 'by handle' framing plus the field list clearly separates it from query-driven siblings like search_users and relation-list siblings like creator_followers.

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?

Gives a concrete decision context: 'qualify a partner or size up a competitor before committing,' which tells the agent when this lookup is worth making. It stops short of naming alternatives or exclusions (e.g., when to use search_users instead), so it is clear context without full routing guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses key traits: 'Returns original timed caption text,' 'URLs expire,' and 'Only approved TikTok CDN URLs are accepted.' These are important operational constraints. However, it does not describe error handling or whether the response is paginated.

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?

Three sentences, front-loaded with the core action. The negative constraints are compact and each sentence adds distinct value without 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?

Given a single required parameter, no output schema, and no annotations, the description is nearly complete: it explains what is returned, what is not done, and key limitations (URL expiration, CDN restriction). It could mention that the output is a WebVTT file or how the result is structured, but otherwise it is thorough.

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 100%, so the schema already documents the subtitle_url parameter fully. The description reinforces the source of the URL (subtitleInfos) and the expiration/acceptance constraints, which adds contextual meaning beyond the schema. Baseline 3 is appropriate when schema does the heavy lifting.

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?

States a specific verb and resource ('Fetch an existing TikTok WebVTT subtitle file') and explicitly distinguishes what it does NOT do (does not look up a video, transcribe audio, translate, or generate missing captions), clearly separating it from video_transcript and video_detail.

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?

Provides explicit prerequisites: 'Supply subtitle_url from video.subtitleInfos[].Url in native video data or subtitleInfos from video_detail.' It names the sibling tool (video_detail) as the source and states the condition under which this tool is appropriate.

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

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

With no annotations, the description carries the full burden. It does disclose pagination and the shape of each returned item (author, like count, reply count), which is genuinely useful. It says nothing about auth requirements, ordering, rate limits, or whether replies to comments are included, leaving meaningful behavioral gaps.

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?

Two compact sentences, front-loaded with what the tool returns before the motivational use case. The phrase 'about content that is working' is slightly promotional but still short and does not bloat the definition.

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 no output schema it does name the per-comment fields, which partly compensates. However, it omits whether the result is top-level comments only versus replies (a live sibling distinction), ordering, and the nextCursor contract mentioned in the schema, leaving modest gaps for a paginated read tool.

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 100%, so aweme_id, count and cursor are already documented with defaults and ranges. The description adds only the concept of pagination, which the schema already conveys via the cursor field, so baseline 3 is appropriate.

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?

States a specific verb and resource ('Read a video's comments, paginated') and names the returned fields, so the agent knows exactly what it retrieves. It does not distinguish itself from the sibling comment_replies or clarify whether replies are included, so it stops short of a 5.

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 second sentence gives implied usage ('hear the audience's own words... for hooks, objections and demand signals'), which frames intent but not operational selection criteria. It never says when to prefer this over comment_replies, video_detail or pick_comment_winners, and gives no exclusions.

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

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

With no annotations, the description carries the full burden and delivers real behavioral context: image and caption URLs expire, no OCR or transcription is performed, and native subtitleInfos/captionInfos are only present 'when available'. It omits auth/permission requirements and rate-limit behavior, so it is strong but not exhaustive.

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 return payload, then photo-post specifics, then expiration/no-OCR caveats, then id sourcing and intent. Dense but effective; the long field enumeration is justified by the absence of an output schema.

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 no output schema and no annotations, the description is nearly complete about return values (author, counts, duration, hashtags, sound, media URLs, captions, photo slide order) and caveats. Missing only operational details such as permissions, pagination, and failure behavior.

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 aweme_id semantics are already documented in the schema (baseline 3). The description adds meaning beyond it by stating the id originates from specific sibling tools and is a numeric post id, which helps the agent source the value correctly.

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?

Opens with a specific verb+resource: 'Get the record for a single video or photo/slideshow post', then enumerates exactly what the record contains. It is clearly distinguishable from sibling list/search tools (search_videos, related_videos) because it is the single-item detail resolver and names the tools whose ids it consumes.

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 tells the agent where the id comes from (search_photos, search_videos, related_videos, hashtag_videos) and gives a use intent ('vet a video or benchmark one that is performing'). It stops short of explicit when-not-to-use or a direct comparison to nearest siblings like similar_videos or video_comments.

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

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

No annotations are provided, so the description carries the full burden and does so richly: it discloses the two upstream requests, the CDN download, the language fallback ordering ('requested language, then English, then the first track; original tracks win over machine-translated'), the auto-generated caveat, the empty-caption case, and the unresolved short-link limitation.

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?

Dense and front-loaded — the core action leads, followed by provenance, fallback rules, and edge cases. Every clause earns its place, though the single long paragraph packs several distinct concerns together and could be segmented for faster scanning.

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 no output schema, the description compensates by specifying the return shape ('plain text, timed segments (seconds) and the available languages') and the no-caption response behavior. Nothing needed to call or interpret this tool 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 100%, so both parameters are already documented (URL-or-id format, language example). The description adds value beyond the schema by explaining the fallback selection logic for `language`, which the schema does not convey.

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?

States a specific verb and resource: 'Video captions as text ... takes a TikTok video URL or id, reads the video's own caption tracks ... downloads one WebVTT file from TikTok's CDN.' An agent can distinguish this from the large sibling set without opening the schema.

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?

Gives clear context for when this applies and its limits: 'These are TikTok's existing captions ... nothing is transcribed', 'Many videos have no captions; the response says so clearly', and 'Short links (vm.tiktok.com) are not resolved.' However, it never names or contrasts the closest sibling (video_captions), leaving the agent to infer which of the two to pick.

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