TopTik — TikTok data

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds the conditional usage context (reply_count > 0) but doesn't disclose other behavioral traits like pagination behavior or the compact vs. expanded response format, which are partially covered by the schema's expand parameter description. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the key purpose and the critical usage condition. Every word earns its place, and it avoids redundancy with the 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?

For a read-only list tool with a rich schema (100% parameter coverage) and annotations covering safety, the description is mostly complete. The only minor gap is that it doesn't explicitly state the return format or pagination behavior, but the schema's expand and cursor parameters already cover those details. The conditional usage guidance is a strong addition.

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 five parameters are documented in the schema. The description itself doesn't add parameter-level meaning beyond the schema, but the schema already provides detailed descriptions for id, count, cursor, expand, and comment_id. The description's mention of reply_count indirectly relates to the comment_id parameter but doesn't add new semantic value.

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 clearly states the tool's function: retrieving replies under a comment. It also references the sibling tool tiktok_video_comments, which helps distinguish it from other TikTok tools. However, it doesn't explicitly name the resource as 'comment replies' in a fully standalone way, and the title 'Comment replies' is somewhat generic.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to call this tool: only when tiktok_video_comments reported reply_count above 0. This is a clear condition that helps an agent decide whether to invoke this tool, and it implicitly distinguishes it from tiktok_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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses a key behavioral trait: TikTok's paging is unreliable, so this returns only a sample and is not a complete export. This is crucial for setting agent expectations.

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 with zero fluff. The core purpose is front-loaded, and the important pagination caveat follows immediately.

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 sample tool with three well-documented parameters, the description fully explains what the agent can expect and what limitations exist. No critical guidance is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents all parameters with descriptions (id pattern, count range, expand semantics). The description adds context about recency and sample-ness but does not add parameter-specific meaning, matching the baseline for high schema 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?

The description states exactly what the tool returns: a sample of a creator's followers (most recent) plus the total count. The word 'followers' also distinguishes it clearly from the sibling 'following' 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?

It gives clear context: one page only, sample not export, because TikTok does not page reliably. It does not explicitly name alternatives or exclusions, but the limitation is enough to guide appropriate use.

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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds behavioral context by specifying 'sample' (non-exhaustive) and 'one page only' (pagination limit), which goes beyond the annotations. It also references a shared limitation with followers, adding useful context, though it could be more explicit about that reason.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words, and the core purpose is front-loaded. However, the phrase 'for the same reason as followers' is cryptic without the referenced reason, slightly undermining clarity. Still, it is concise and structurally efficient.

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?

The description explains the output (sample plus total) and the pagination constraint, and annotations cover safety and idempotency. However, it relies on an undefined 'same reason' that the agent may not know, leaving a gap in understanding why one page only. Without an output schema, the description could better describe the response structure or the meaning of 'sample' and 'total'. Overall, adequate but with a notable ambiguity.

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 three parameters (id, count, expand). The description does not add any parameter-specific detail beyond the schema; the term 'sample' loosely relates to count but does not clarify syntax or format. Baseline of 3 is appropriate given high schema 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?

The description clearly states the tool returns a sample of accounts a creator follows plus the total count. It distinguishes from the sibling 'followers' by the word 'following' and explicitly notes 'one page only', making the scope specific and identifiable.

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 usage by naming the resource (accounts a creator follows) but does not explicitly state when to use this tool versus alternatives. It references 'the same reason as followers' without explaining that reason, leaving the agent to infer the limitation or seek context from sibling tools. No explicit when-not-to-use guidance is given.

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?

Annotations cover readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is already disclosed. The description adds genuinely valuable behavioral context beyond annotations: the public/private likes constraint and the fact that a private list silently returns no videos — a critical trap that prevents an agent from misreading an empty result as 'creator has no liked videos.'

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, zero waste. The core purpose is front-loaded, followed immediately by the single most important caveat. Every word 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?

For a read-only list tool with no output schema, all four parameters are documented in the schema and the main behavioral failure mode is disclosed. The only minor gap is that the description does not hint at what the compact vs. expanded response difference means for output handling, but expand's purpose is already covered in the schema.

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 id, count, cursor, and expand are already fully documented in the input schema. The description adds no parameter-level meaning beyond the schema, and per the calibration baseline this is an adequate 3.

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?

"Videos a creator has liked" states a specific verb and resource. It is clearly distinguishable from sibling tiktok_creator_videos (posted videos vs. liked videos), though the description does not explicitly name that sibling for contrast. Purpose is unambiguous 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 gives decisive when-to-use context: the tool only works when the account keeps likes public, and most accounts do not. This tells the agent when results will be empty and frames expectations before invocation. It stops short of naming an alternative tool, but the situational 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is handled by structured data. The description adds genuinely useful behavioral context: most creators have no playlists and the API returns total 0, which sets expectations for a common empty result despite the resource being valid. This goes slightly beyond the annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, roughly 24 words, with zero filler: the first establishes resource and terminology, the second sets empty-result expectations. Both sentences earn their place, and the content is front-loaded with the core purpose. This is an appropriately sized description for a simple list tool.

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 fully documented schema and three safety annotations, the description is nearly complete for correct invocation: the agent knows the tool is read-only, idempotent, takes a sec_uid/numeric uid, supports pagination and expand, and may legitimately return zero results. The only real gap is the absence of an output schema (mitigated slightly by the 'total 0' hint), which is a schema responsibility rather than a description failure.

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 of 3 applies. The description itself adds no parameter detail, but the schema thoroughly documents all three parameters: the id pattern (sec_uid with MS4w prefix or numeric uid), cursor pagination semantics (omit for page one, default 0), and the expand flag's size warning (can exceed 500 KB for list tools). No compensation is needed.

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 names the resource ('creator's playlists') and disambiguates TikTok's terminology ('mixes or series'), which distinguishes it from every sibling tool — none of the 24 siblings cover playlists. However, the verb is only implied ('A creator's playlists' rather than 'List a creator's playlists'), so an agent must infer that the tool retrieves, not creates or modifies. The 'returns total 0' line reinforces that it is a read-style list operation.

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?

There is no guidance on when to use this tool versus alternatives — no when-to, when-not-to, or sibling routing. The only usage hint anywhere is inside the expand parameter's schema description (ask for the full API response only when a needed field is missing), not in the tool description. The 'most creators have none' line manages expectations but does not help an agent decide between this and any other creator-centric tool.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the operation's safety profile is clear and the description does not contradict it. The description adds no behavioral context beyond listing the data contents—no mention of response size, pagination, or API behavior—but the annotations lower the burden considerably.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single compact sentence that front-loads the resource and then itemizes its contents with no filler or repetition. Every word 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?

For a simple read-only profile lookup, the field list plus the well-documented schema and annotations are sufficient. The lack of an output schema is offset by the explicit enumeration of returned fields; a slightly more explicit note that this returns profile metadata only, not videos or followers, 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 description coverage is 100%: both 'id' and 'expand' are fully documented with patterns, defaults, and usage guidance. The description itself adds no parameter-specific meaning, 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?

The description states the exact resource ('a creator's profile') and enumerates the returned fields: handle, nickname, bio, follower/following/video counts, privacy/verification flags, and avatar. This clearly distinguishes it from sibling tools like tiktok_creator_videos or tiktok_creator_followers, even though it uses a noun phrase rather than a verb.

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?

There is no explicit when-to-use or when-not-to-use guidance in the description. The schema's id description provides a useful prerequisite ('from tiktok_resolve_username'), which implies the intended flow, but the description itself does not route agents away from alternatives such as tiktok_creator_videos or tiktok_creator_followers.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds behavioral context beyond annotations: pagination via max_cursor/has_more, pinned posts only on page one, and the expand parameter's size implications. It doesn't mention rate limits or auth, but the annotations cover the read-only/idempotent nature.

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 with no waste. The core purpose is front-loaded, pagination instructions are concise, and the pinned-post caveat is a single clause. 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?

For a read-only list tool with 100% schema coverage and no output schema, the description covers the essential behavior: what it returns, ordering, pagination, and the expand option. It doesn't describe the exact stats fields returned, but the compact form is described as a summary and the expand option covers missing fields. The lack of an output schema is partially mitigated by the description's mention of max_cursor and has_more.

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. The description adds value by explaining the pagination flow (max_cursor as cursor, has_more=0) and the expand parameter's trade-off (compact vs. complete response, can exceed 500 KB). This goes beyond the schema's basic parameter 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 states a specific verb and resource: 'A creator's posts, newest first, with stats.' It clearly distinguishes this from sibling tools like tiktok_creator_profile or tiktok_creator_liked_videos by focusing on the creator's own posts with stats. The pagination detail further clarifies the scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear pagination instructions: 'Page by passing the previous response's max_cursor as cursor until has_more is 0.' It also notes that pinned posts appear on page one only, which is useful context. However, it doesn't explicitly state when to use this tool versus alternatives like tiktok_creator_liked_videos or tiktok_search_videos, though the resource is clear enough.

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 annotations already declaring readOnlyHint, openWorldHint, and idempotentHint, the description adds valuable behavioral context: it is not cached, each call returns a fresh set, and pagination is supported via repeated calls. This goes beyond the annotations and helps the agent understand call semantics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, information-dense sentence. It front-loads the purpose and immediately distinguishes the feed from cached/personalised alternatives, then notes pagination. Every clause earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with two optional parameters, no output schema, and annotations covering read-only/idempotence, the description provides the essential context: freshness, non-caching, and pagination. It does not detail the compact response structure, but that is minor for a trending feed.

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% for both parameters (count and expand), so the schema fully documents them. The tool description adds no additional parameter context beyond what the schema provides, which meets the baseline for high 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?

The description clearly states the tool returns TikTok's Explore/Discover feed, i.e., trending content. It adds 'what is trending now' to specify the resource. It differentiates by noting it's not personalised, which separates it from search tools, but 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?

The description implies usage: use when you want a fresh, non-personalised set of trending videos, and call again for more. It does not explicitly state when not to use it or compare to alternatives, leaving the agent to infer the decision.

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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds value beyond those annotations by disclosing the return contents (id, total video count, view count) and the recommended chaining behavior, which is especially useful given there is no output schema.

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 with no filler. The core mapping is stated first, followed by the output details and the next-step guidance. Every clause 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?

For a simple resolver with only one required parameter and a well-documented schema, the description is complete: it explains what input is needed, what output to expect, and how to use that output next. The lack of an output schema is mitigated because the description names the key returned fields.

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%: both the `name` and `expand` parameters already have detailed descriptions, including the '#' allowance and the 500 KB warning for expanded responses. The tool description itself adds no additional parameter-specific semantics, so the baseline score of 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?

The description states a clear conversion task—'Hashtag name to its id'—and specifies the useful extra outputs ('total video and view counts'). It also distinguishes the tool from tiktok_hashtag_videos by explicitly saying the id should be fed there, though it lacks a formal verb and does not contrast with tiktok_search_hashtags.

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 concrete workflow guidance: resolve the hashtag id first, then use tiktok_hashtag_videos. This makes the intended calling context clear. It does not, however, explicitly say when to prefer this over search_hashtags or other lookup/resolution tools.

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?

Annotations already cover readOnlyHint, openWorldHint, and idempotentHint. The description adds a valuable behavioral detail: TikTok caps page size near 12 regardless of the requested count, and pagination uses a cursor. This goes beyond the schema's count note and helps the agent handle paged results correctly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, each earning its place: the first states the purpose, the second communicates the pagination behavior. No filler, front-loaded with the core purpose. This is model-efficient and easy to parse.

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?

The tool is read-only, idempotent, has a fully documented schema, and annotations cover safety. The description supplies the essential pagination quirk. The expand parameter's output-size tradeoff is documented in the schema, so the description is sufficient for an agent to call the tool correctly. The lack of an output schema is mitigated by the simple, predictable nature of the 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 fully documented. The description adds no new parameter semantics; it only repeats the page-size cap that already exists in the count parameter description. Baseline of 3 is appropriate when the schema carries the semantic load.

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 the action and resource ('Videos under a hashtag'), clearly identifying this as a read/list operation for hashtag videos. It is distinct from siblings like tiktok_hashtag_resolve or tiktok_search_hashtags, though it does not explicitly name an alternative, so it earns a 4 rather than 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?

No guidance is given on when to use this tool vs. alternatives. It does not mention that the hashtag id comes from tiktok_hashtag_resolve, nor does it route the agent to other search tools when hashtag videos are not the target. The pagination note is behavioral, not usage 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context: URLs are signed with an expires_at, rooms usually end before signatures expire, and FLV is always available while HLS is conditional. This explains failure modes and fallback behavior beyond what annotations 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?

Three sentences with zero waste. The core purpose is front-loaded, followed by the most important behavioral caveat (signed URLs, room lifetime) and a practical fallback tip. 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?

For a read-only list tool with 100% schema coverage and no output schema, the description covers the key operational details: what you get (stream URLs per quality, title, viewer count), the caveats (signed URLs, room lifetime), and the fallback strategy. The only minor gap is not describing the compact response structure, but the expand parameter's schema description covers that.

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 three parameters (q, count, expand). The description adds context about the expand parameter's purpose (compact vs. complete response) and the practical implication of large responses, but this is already partially in the schema. The description doesn't add much 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?

The description states a specific verb and resource: 'Live rooms matching a keyword' with playable stream URLs, title, and viewer count. It clearly distinguishes itself from sibling tools like tiktok_search_lives by focusing on playable stream URLs and quality formats, not just search results.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context on when to use this tool: when you need playable stream URLs for live rooms matching a keyword. It doesn't explicitly name alternatives or exclusions, but the focus on stream URLs and quality formats implies when it's appropriate versus other search tools. The guidance about trying another quality if one fails is practical usage advice.

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?

Annotations already establish readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description goes beyond the annotations by specifying that the tool searches by name and returns a concrete set of fields like address, rating, and video count. It could mention data freshness or ranking, but that is a minor gap given the strong 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?

The description is a single sentence with no filler, front-loading the action and resource, and appending only the most relevant output fields. Every word 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?

For a 3-parameter search tool, the schema fully covers required inputs, count bounds, and expansion behavior, while the description covers the returned content. Since there is no output schema, the field list helps compensate. The only notable gap is the lack of explicit guidance for choosing this over sibling search tools.

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% with detailed parameter explanations for q, count, and expand, including the important warning that expand=true can produce responses over 500KB. The main description only adds 'by name' and does not need to compensate for schema gaps, so a baseline of 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?

The description uses a specific verb ('Search'), names the resource as 'TikTok places (points of interest)', and lists concrete result dimensions (address, coordinates, rating, review count, video count). This makes it clearly distinct from the sibling search_* tools without requiring schema inspection.

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 use when an agent needs to find TikTok places by name or keywords, but it does not explicitly state when to choose this over sibling search_* tools or when not to use it. There is no exclusion or alternative routing, so guidance is only implicit.

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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering the safety profile, so the description's burden is lighter. It adds a genuinely useful behavioral detail beyond annotations: an empty user_list signals no exact match. It could say more about response shape, but with rich annotations a small gap is acceptable.

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, each earning its place: the resolution purpose, the workflow entry-point role, and the no-match failure semantics. Purpose is front-loaded and there is zero 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 2-parameter resolver with full schema coverage and strong annotations, the description covers the essential operational context: what it returns, how it feeds the creator family, and what an empty result means. The only notable absence is a fuller compact-response shape, but the expand parameter and workflow note cover most agent needs.

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 fully documents handle and expand (including the 500 KB warning and leading-@ behavior). The description's mention of sec_uid output mildly reinforces handle's purpose, but it adds no new parameter-level meaning beyond the schema — baseline 3 is correct.

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 first sentence names a specific verb (resolve), resource (@handle), and concrete outputs (numeric uid and sec_uid). The 'Start here' sentence anchors its role relative to the tiktok_creator_* sibling family, and the mention of 'handle' clearly separates it from the other resolve-style siblings (hashtag, sound).

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?

'Start here: every tiktok_creator_* tool takes the sec_uid this returns' is explicit when-to-use guidance that names the downstream consumers. The empty user_list note adds result-interpretation guidance. It stops short of explicit when-not-to-use phrasing, but the sibling naming makes the routing 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?

Annotations already convey read-only, open-world, and idempotent behavior. The description adds useful behavioral detail beyond that: pagination uses offset rather than a cursor, and results include follower counts. This meaningfully extends what structured annotations alone 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?

Two sentences with no filler: the core purpose is front-loaded, the key behavioral caveat is second, and the alternative routing is third. 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?

For a 4-parameter search tool with fully documented schema properties and read-only annotations, the description covers the essential behavioral details and the primary alternative tool. Nothing needed to call it 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%, so the baseline is 3, but the description adds semantic value: 'keyword search over accounts' clarifies what q targets, and 'pages by offset, not cursor' gives practical meaning to the offset parameter beyond the schema's skip-count 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?

The description clearly states this is a keyword search over accounts and that it returns follower counts, which identifies both the operation and the resource. It also distinguishes itself from tiktok_resolve_username, making it easy to tell apart from a near-neighbor sibling.

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 explicitly gives the alternative for exact @handle lookups and explains why that alternative is preferable (cheaper and more reliable). This gives an agent a concrete routing rule: use this tool for keyword search, but switch to tiktok_resolve_username for exact handles.

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?

Annotations already cover read-only, open-world, and idempotent behavior. The description adds meaningful behavioral context beyond annotations: results include post and view counts, and only one page is returned. This is particularly useful because there is no output schema to convey return shape or pagination limits.

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 with no filler. The core action is front-loaded, followed by the two most decision-relevant facts: output contents and the one-page limitation. Every word 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?

For a simple keyword search tool, the description is complete enough: it identifies the resource, the kind of results returned, and the pagination constraint. The expand parameter is fully explained in the schema, and annotations cover the safety profile, so no critical information 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 description coverage is 100%, so the schema already documents q, count, and expand thoroughly, including defaults and the expand size warning. The description adds no parameter-specific meaning, but that is acceptable given the schema carries the full burden.

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, resource, and scope: 'Keyword search over hashtags'. Adding 'with post and view counts' and 'One page only' gives the agent useful expectations about result content and pagination. It does not explicitly name a sibling to differentiate from, so it falls just 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 makes the tool's context clear: keyword-based search over hashtags rather than ID-based resolution or hashtag videos. However, it does not explicitly state when not to use this tool or point to alternatives like tiktok_hashtag_resolve, leaving some routing to inference.

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?

Annotations already cover read-only, idempotent, and open-world hints. The description adds valuable behavioral context beyond those: results are limited to one page, and the data is a real-time snapshot of live rooms. This helps set expectations about output shape and pagination without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two tight sentences with zero filler. The primary purpose is front-loaded, followed by a key limitation ('One page only') and a direct pointer to the relevant sibling tool. 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?

For a simple search tool with well-documented parameters and safety annotations, the description is largely complete: it states what is returned, that it is limited to one page, and where to go for stream URLs. It could mention result ordering or more about the compact response shape, but the expand parameter and schema partially cover that 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 input schema fully documents q, count, and expand. The description adds no additional parameter-level meaning beyond what the schema already provides. A baseline score of 3 is appropriate since 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?

The description clearly states the tool searches for live rooms currently on air matching a keyword and includes the host's account. It names the specific resource ('live rooms') and directly distinguishes itself from the sibling tiktok_live_streams. This leaves no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'One page only' and directs users to tiktok_live_streams when playable stream URLs are needed. This provides a concrete when-to-use/when-not-to-use distinction and names the alternative tool. The context for using this tool versus its siblings 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?

Annotations already provide readOnlyHint, openWorldHint, and idempotentHint, so the description does not need to repeat safety traits. It adds value by disclosing 'One page only' (a pagination limitation not captured in annotations) and specifying the output includes image URLs and stats. This goes beyond the annotation set without contradicting it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, tight sentence that front-loads the core purpose and a key limitation. There is no wasted wording, and every element ('keyword search', 'photo-mode', 'image URLs and stats', 'one page only') contributes directly to agent understanding. It is exemplary in brevity and structure.

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 straightforward search tool with no output schema, the description covers the essential aspects: what it searches, what it returns, and the one-page constraint. It does not mention error handling or alternative output formats, but these are not critical for basic invocation. The description is sufficiently complete for an agent to call 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%—all three parameters (q, count, expand) are documented in the schema. The description adds no parameter-specific detail beyond what the schema already provides, so it does not enhance parameter understanding. Baseline 3 is appropriate because 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?

The description clearly states the verb ('search'), the resource ('photo-mode (carousel) posts'), and the output ('image URLs and stats'). It distinguishes this tool from sibling search tools by explicitly narrowing to photo-mode content, which separates it from tiktok_search_videos, tiktok_search_sounds, etc.

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 usage for photo posts but does not explicitly contrast with alternative search tools or provide conditions for when not to use it. The 'One page only' note is a limitation, not a usage guideline. There is no mention of when to choose this over tiktok_search_videos or other searches, leaving the agent to infer based on the content type.

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?

Annotations already convey read-only, open-world, and idempotent behavior. The description adds genuinely useful pagination behavior by explaining that cursor is an offset and must be passed from the previous response, which goes beyond the schema's generic wording.

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?

A single front-loaded sentence conveys the core operation and the most important pagination detail. There is no wasted wording.

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?

The description covers what the tool does and how pagination works, and the rich schema covers parameters and the compact-vs-expanded response choice. With no output schema, a bit more detail about the result shape would be ideal, but the 'usage counts' hint plus expand parameter make it 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%, so the schema already documents q, count, cursor, and expand thoroughly. The description adds little parameter meaning beyond restating the cursor offset behavior, which the schema already covers.

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 names a specific verb ('search') and resource ('sounds'), and adds the distinctive detail that results include usage counts. This is enough to set it apart from sibling search tools like tiktok_search_creators or tiktok_search_hashtags.

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 phrase 'Keyword search over sounds' clearly establishes when the tool applies, and the sibling set contains no other sound keyword-search tool, so confusion is unlikely. It does not explicitly name alternatives or exclusions, but the context 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description reveals a non-obvious external trait: 'TikTok search is a bounded, re-ranked pool, not an endless list.' It then translates that into defensive behavior (dedupe on video_id, stop on diminishing returns) — exactly the kind of trait annotations cannot express. No contradiction with the annotations; re-ranking reflects external data volatility covered by openWorldHint, not a side effect.

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 with zero filler. Purpose is front-loaded in the first sentence, and the second packs a dense, actionable heuristic (count, cursor, dedupe key, stop condition) with 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?

For a 5-parameter open-world list tool with no output schema, the description supplies the most critical non-obvious knowledge an agent needs: results are finite and re-ranked, so it must page, dedupe on video_id, and know when to stop. It slightly under-serves the no-output-schema case by not sketching the compact result shape, though the dedupe instruction implicitly confirms video_id is returned.

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% — all five parameters carry descriptions, so the schema fully documents q, count, cursor, expand, and sort_type. The description adds only light reinforcement ('ask for count 30, page with cursor') that largely echoes the schema's existing '30 yields the most distinct results per call' and cursor paging notes, so it stays at the high-coverage 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?

Opens with 'Keyword search over videos' — a specific verb, resource, and modality in one phrase. This cleanly separates it from sibling search tools like tiktok_search_creators, tiktok_search_hashtags, and tiktok_search_lives (different resource types) and from lookup-style tools such as tiktok_video_stats or tiktok_hashtag_resolve.

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 is a concrete operational recipe — 'ask for count 30, page with cursor, dedupe on video_id, and stop when two pages add nothing new' — which tells the agent how to drive the tool correctly. However, it never names alternatives or says when to prefer this over tiktok_hashtag_videos, tiktok_creator_videos, or tiktok_explore_feed; the 'keyword search' qualifier only implies the use 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds that results are 'closest candidates,' which signals fuzzy matching and plural returns, but it does not describe no-match behavior or candidate count. 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 with zero filler: the core transformation is front-loaded and the downstream pointer is a single clause. Every word 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?

For a two-parameter read-only resolver, the schema covers the parameters and annotations cover side effects. The description states the output (music id) and the desired next tool, which is most of the contract. It does not spell out the exact return shape, but the tool is simple enough that this 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 coverage is 100%, so both title and expand are already documented in the input schema. The description adds no additional parameter syntax, constraints, or format details beyond echoing the title's role. 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 the resource ('Sound title') and the result ('music id'), and 'closest candidates' signals fuzzy resolution rather than exact search. It is terse but unambiguous, though it lacks a verb like 'resolves' and does not explicitly contrast with tiktok_search_sounds.

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?

'Feed the id to tiktok_sound_videos' provides a concrete downstream instruction and implies this is the resolution step before fetching videos. It does not explicitly say when not to use it or compare it with tiktok_search_sounds, but the intended 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?

While annotations already mark this read-only, idempotent, and open-world, the description discloses a non-obvious behavioral trait: some returned videos may use a different sound, so callers must verify music_id. This is exactly the kind of caveat an agent needs and goes well beyond the annotations.

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 with no filler. The core purpose comes first, and the crucial caveat about feed behavior follows immediately. Every sentence adds value and is easy to scan.

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 low-complexity, read-only tool with full schema parameter coverage, the description covers purpose, behavior, and the key output field to verify. There is no output schema, so a bit more detail about the return shape could help, but the caveat and 'feed' framing keep this adequately complete for an agent.

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 parameters are already well documented. The description adds no new parameter-level semantics; 'music_id' refers to an output field rather than an input parameter, so this dimension stays at 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?

The description states the resource clearly: videos TikTok associates with a sound. It lacks an explicit verb like 'list' or 'fetch', but the phrase 'Videos TikTok associates with a sound' conveys the operation well enough and distinguishes it from sound resolution or hashtag video tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives important context on how to interpret results ('feed seeded by the sound, not a strict filter') and instructs checking music_id. It does not explicitly name sibling alternatives or state when to choose this tool over tiktok_sound_resolve or tiktok_search_sounds, leaving the selection logic mostly 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?

Annotations already mark the tool readOnly/idempotent, so the description's main contribution is pagination behavior: cursor offset, continuation via previous response, and re-ranking instability. That is genuinely useful behavioral context beyond the annotations.

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, each earning its place: what the tool returns, how pagination works, and a dedupe warning. No filler or repetition of schema details.

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 primary behavior, pagination, and a stability caveat despite no output schema. It stops short of describing the exact response shape or field names beyond comment_id, but what an agent needs to call and paginate correctly is present.

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; the description adds meaning by explaining how cursor relates to the previous response and why comment_id should be used for deduplication. This is practical semantics not fully captured in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource ('comments on a video') and narrows scope to 'Top-level comments' with like/reply counts, making it easy to distinguish from tiktok_comment_replies. It also defines the purpose in a single front-loaded phrase.

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 gives clear operational guidance: pass the previous cursor to continue and dedupe on comment_id because TikTok re-ranks between pages. It does not explicitly name sibling alternatives or exclusion conditions, though 'top-level' plus sibling tiktok_comment_replies implies the boundary.

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?

Annotations already supply readOnlyHint and idempotentHint. The description adds meaningful behavioral context beyond those annotations by disclosing that the tool returns links only, that links are signed, and that they expire, with an instruction to fetch promptly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two tight sentences with no filler. The core purpose is front-loaded, and the critical caveat about signed, expiring links is delivered immediately after.

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 read-only tool with two well-documented parameters, the description is complete: it names the resource, enumerates returned media types, and warns about link expiration. There is no output schema, but the description covers the main return value shape sufficiently.

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 fully documents both 'id' and 'expand'. The description does not add parameter-specific semantics beyond the schema, but that is acceptable because the schema already carries the load.

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: returning 'direct media URLs for one post.' It enumerates exactly what is included (no-watermark video, watermarked video, audio, covers, images) and distinguishes this from sibling tools like stats, comments, or transcript by emphasizing that it provides links only, not bytes.

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 usage: call it when you need media URLs for a single post. It also gives a practical constraint ('fetch promptly' because links expire), but it does not explicitly name alternatives or state when not to use this tool versus sibling tools.

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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering the safety profile. The description adds the specific fields returned, which is useful context, but does not disclose additional behaviors like error handling, rate limits, or response size. Given the annotations, a 3 is appropriate—the description contributes some value but not rich behavioral details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the resource and action, then enumerates the returned fields without waste. It is appropriately concise for a simple read tool.

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 two parameters, no output schema, and read-only annotations, the description is nearly complete. It states what it returns and covers both video and photo posts. Minor gaps like error handling are not critical given the simple nature. The expand parameter is explained in the schema, so the description need not repeat it.

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%—both id and expand are fully described in the schema. The description does not add meaning beyond the schema, though it lists output fields which indirectly help understand the expand parameter's purpose. Baseline 3 applies when the schema handles parameter documentation.

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 clearly states the tool retrieves a single video or photo post by ID and lists the exact data fields returned (caption, plays, likes, etc.). This distinguishes it from sibling tools like tiktok_video_comments or tiktok_video_transcript, which serve different purposes.

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 usage for retrieving post stats but does not explicitly contrast it with alternatives. There is no 'use this for X, use that for Y' guidance. The expand parameter in the schema offers some context for when to request the full response, but the description itself lacks explicit when-to-use vs. when-not-to-use advice.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context: it explains the meaning of has_transcript false (common, not an error), which prevents an agent from treating a missing caption track as a failure. It also describes the output as 'one joined string plus timed cues', giving a clear picture of the return shape. It does not mention rate limits or pagination, but for a read-only transcript tool this is a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no wasted words. The first sentence states the core purpose and output shape, and the second sentence clarifies a common edge case (has_transcript false). Every sentence earns its place, and the most important information is front-loaded.

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 transcript tool with 100% schema coverage and no output schema, the description is nearly complete. It explains the output shape, the meaning of a missing transcript, and the expand parameter's trade-off is already in the schema. The only minor gap is that it doesn't explicitly state what happens when lang is omitted (the schema says 'Omit to get the original track', which covers it). Overall, an agent has everything needed to call this tool 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 all three parameters (id, lang, expand). The description adds meaning beyond the schema by explaining the output structure ('one joined string plus timed cues') and the semantics of has_transcript false, which helps an agent interpret the response. The expand parameter's behavior is fully documented in the schema, and the description reinforces the compact-vs-complete distinction. The description does not add much about lang, but the schema already covers it.

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: it retrieves a video's spoken text from TikTok's own caption track, and specifies the output shape (one joined string plus timed cues). It also clarifies the meaning of has_transcript false, which distinguishes this from a generic transcript tool. The title 'Video transcript' is consistent and the description adds detail beyond the title.

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 when to use the tool (to get a video's spoken text from TikTok's caption track) and clarifies that has_transcript false is common and not an error, which helps an agent avoid misinterpreting a missing transcript. It does not explicitly name sibling alternatives or state when not to use this tool, but the sibling list shows many other TikTok tools with distinct purposes, and the description's specificity is sufficient for most selection decisions.

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