TokConnect: TikTok Research

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

Annotations already declare read-only, idempotent, open-world behavior. The description adds a meaningful operational caveat: search is not market-filtered and country data requires method=detail, with a tested-date note. It does not cover rate limits or pagination, but the schema handles paging.

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 front-loaded with purpose and the method list, followed by a useful global-search caveat and two examples. The caveat is somewhat detailed but earns its place by preventing a market-filtering mistake.

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 a full input schema, an output schema, and rich annotations, the description supplies the remaining method-selection and global-search context needed to invoke correctly. Nothing material is missing for correct use.

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 7 parameters, including the method enum meanings. The description's examples illustrate method/keyword/period and method/id, but add little semantic detail beyond the schema; 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 names the resource ('TikTok's library of top-performing ads') and enumerates four specific modes (search, detail, analysis, similar), so the agent knows the tool's scope. It does not explicitly distinguish this tool from sibling tools such as video_search or hashtag_search, 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?

It gives method-level routing ('search by keyword', 'check countries with method=detail') and worked examples, plus a caveat that search is worldwide. It stops short of naming sibling alternatives or explicit when-not-to-use conditions, 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?

Annotations already declare this as read-only, idempotent, and open-world, so the safety burden is low. The description adds useful behavioral caveats about market_size scope and region default, but its opening claim of 'last 7 days of data' conflicts with the schema's default window of 30d, which is a notable transparency 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 purpose and method breakdown are front-loaded, and the example is placed at the end for illustration. Despite covering multiple methods and conditional behaviors, every sentence carries useful information without unnecessary 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?

Given the 10 parameters, multiple method modes, rich schema coverage, annotations, and an output schema, the description is largely complete: it explains method routing, region behavior, and a key scope caveat. The only material gap is the 7-day framing versus the 30d default window.

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 10 parameters in detail. The description repeats method meanings and adds an example, but the 'last 7 days' phrasing contradicts the schema's 30d default window, so it does not add reliable semantics beyond the schema.

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

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

The description states a specific resource and metric (top TikTok Shop categories by estimated revenue with revenue, units, growth, and shop-share splits) and clearly enumerates what each method returns. It also distinguishes itself from sibling tools by explaining how category ids from method=tree are passed to product_top_selling or creator_top_selling.

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 routes between methods: tree for category ids, products for a category's top products, and market_size for tracked-entity counts. It names downstream alternatives and clarifies that market_size counts what Shop Analytics tracks rather than all of TikTok Shop.

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 read-only, open-world annotations, the description discloses important behavioral constraints: hashtags are empty for PL, NL and IE, videos only exist for US, JP, TH, ID and VN, and sounds/live are not per market. It does not cover auth or rate-limit behavior, but the availability caveats 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?

The description is dense but appropriately sized for five methods and numerous caveats, with the high-level purpose front-loaded. The method labels make it scannable, though the semicolon-list format is not maximally structured.

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

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

Given the 8 parameters, 100% schema coverage, existing output schema and annotations, the description covers all methods, defaults, examples and key data availability limitations. An agent has enough information to select a method and invoke the 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 coverage is already 100%, so the schema carries most parameter meaning. The description adds useful method-specific context, including examples and the market availability limits that are not fully captured by 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 clearly identifies the resource as TikTok's own leaderboards and enumerates the five chart types with their scope. It does not explicitly name sibling tools such as hashtag_search or sound_search, so differentiation is implied by 'TikTok's own leaderboards' rather than stated.

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 method descriptions give clear context for choosing between sounds, hashtags, searches, live and videos, including defaults and market limitations. However, it does not explicitly say when to use this tool versus sibling search or entity 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, idempotentHint, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the SEO lists are 'public' and that partners data is a leaderboard, which is modest extra context. It discloses nothing about rate limits, data recency/staleness, or the note-reporting behavior for clamped limits (that lives only in the 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 sentences, capability list front-loaded before the example, with zero filler. Slightly more could be trimmed, but the compact example earns its place by showing the method/value contract.

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 11 fully documented parameters, an output schema present, and rich annotations, the description only needs to frame the method families — which it does. Remaining gaps (no cross-references to reference method=creative_markets required for partners markets, no output-shape hint) are carried by structured 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 description coverage is 100%, so every parameter including method, country, sort, period and page is already documented inline with its method-scoped meaning. The description's example does illustrate one valid method/country/sort triple, but adds no syntax or semantics beyond the schema. 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?

The description names the resource (TikTok Creative Center) and enumerates the three data families it exposes — top videos by market, SEO inspiration lists, and Creative Partner agency leaderboards — matching the four method enum values. An agent can tell what it fetches, but nothing distinguishes it from siblings like video_top_selling or category_trends, which likely cover adjacent trending content.

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 worked example ({"method":"top_videos","country":"JP","sort":"engagement"}) implies how to invoke it and the per-method parameter pairing is only discoverable by reading the schema. There is no statement of when to choose this over sibling trending tools, no prerequisites, and no exclusions — guidance is implied 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?

Well beyond the annotations, which only declare read-only/idempotent/open-world: it discloses that counts are rounded the way the app shows them, that likes/followers/following are frequently hidden or empty, that over-limit values are silently lowered and reported in notes, and that unsupported regions are refused. These are real behavioral caveats an agent would otherwise hit at runtime.

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 resource and its contents, then constraints, then routing, then examples — a sensible order. It runs long and the two JSON examples plus the audit/lookalikes sentence partly restate what the method enum already documents, which is the main slack.

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 six-parameter, eleven-method tool with an output schema, the description covers the meaningful gaps: multiplier caveats on hidden data, rounding, region refusal, id resolution, and method selection. Pagination and limits are fully described in the schema, so nothing an agent needs 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 baseline is 3; the description still adds value by explaining the identifier resolution behavior and expanding on the non-obvious methods (audit, lookalikes) with concrete call examples. The method and region semantics largely live in the enum descriptions, so this is additive rather than essential.

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 resource scope — one creator's public account — and enumerates exactly which artifacts come back (profile, posts, reposts, likes, followers, following, playlists, collections). It also names two sibling tools with the conditions that route away from it, so an agent can separate it from creator_search and creator_commerce 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 explicit routing rules with conditions: use creator_search with the handle for exact (unrounded) counts, and use creator_commerce for what the creator sells, earns, links, or their follower demographics. It also states the identifier policy ('Pass any identifier; TokConnect resolves the ids'), removing a common pre-call question.

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 readOnly/openWorld annotations, the description discloses that linked_products has views but 'no sales', that audience 'says so when it has not been built', and that some markets are refused. Those are real behavioral caveats an agent could not derive from annotations alone.

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 one-line purpose, then method inventory, then usage and a worked example. Telegraphic phrasing ([Shop Analytics, any market via region]) is dense but every clause carries 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?

With 10 parameters, an output schema, and rich annotations, the description covers the important gaps: method semantics, region limits, unbuilt-data behavior, and a call example. Only the sibling-selection and pagination story is left 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% and each parameter already documents its per-method applicability, so the description's bracketed '[Shop Analytics]' tags largely restate the schema. It adds only marginal value, such as the example payload showing method/window composition; 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 opening line 'What a creator sells' plus the enumerated method outputs (revenue, units, products, shops, videos, audience) makes the resource and the returned data concrete. It doesn't explicitly name the sibling `creator` or `creator_top_selling`, so an agent must infer that this is per-creator commerce data rather than a creator ranking or profile.

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 vet affiliates' supplies one concrete scenario, and the Live vs Shop Analytics split routes between method families. But there is no guidance about when to prefer `creator`, `shop`, or `product` instead, and no exclusions, so tool-level routing remains 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds the detail-vs-videos distinction and the id provenance, but nothing about rate limits, pagination behavior, or what happens with an invalid/private playlist — gaps the schema partly mitigates.

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?

One sentence plus a compact example, front-loaded with the resource identity before the id-provenance hint. No filler sentences; the example earns its place by making the parameter shape concrete.

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 an output schema present and full schema coverage, the description needn't explain return values, and it correctly limits itself to identity, id source, and the two methods. Adequate for a read-only single-record fetch.

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 every parameter including limit, cursor, detail and method is already documented in the schema; the description only echoes the detail/videos split. The example object is helpful for showing the intended id+kind+method combination, but that is corroboration rather than new 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?

Names a specific resource (one creator playlist or saved collection) and scopes it to either its detail or its videos, so an agent can distinguish it from the broader creator/creator_search siblings. The verb is implicit ('get') rather than stated, keeping it 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?

It tells the agent where the required id comes from (creator with method=playlists or method=collections), which is genuinely useful routing context. It does not state when to prefer this over siblings like creator or creator_search, nor any exclusions, so usage is implied rather than spelled out.

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 readOnly, idempotent, openWorld, non-destructive, so the safety profile is covered. The description adds a real behavioral trait: results reflect TikTok's own account search ordering and the bounds/verified/sort filters apply to the returned page, which matters for pagination expectations. It doesn't restate what the annotations already cover.

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 plus an example, front-loaded with the verb and scope. The clause 'as TikTok's account search returns them now' is slightly awkward and does double duty as behavioral context, but nothing is padded or 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 annotations covering the safety profile and an output schema covering return values, the description only needs scope, filtering behavior, and routing. It delivers all three; only minor gaps remain (per-page filtering vs. global filtering is hinted but not spelled out, and cursor paging relies solely on 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 coverage is 100%, so baseline is 3; the description earns the extra point by clarifying that the keyword matches names, handles, or niches (schema only says 'Search phrase') and by showing a populated example with min_followers and sort. It does not explain cursor or detail semantics, but those are already documented 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 gives a specific verb plus resource ('Searches TikTok accounts by keyword') and narrows the keyword scope to name, handle, or niche. It explicitly contrasts itself with a sibling ('Not a sales ranking (use creator_top_selling)'), so an agent can distinguish 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?

It names one alternative and the condition that selects it ('use creator_top_selling' for sales ranking), plus a concrete example invocation. It stops short of covering the wider sibling set (e.g., creator, creator_commerce), so it isn't fully exhaustive, but the use/avoid guidance 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?

Beyond the readOnly/idempotent annotations, it discloses non-obvious behavior: the window is silently ignored when neither keyword nor category is supplied, category-only queries internally run several keyword sweeps and report sweep/row counts, limit caps at 100 with ~700 rows per keyword, and sort=growth favors brand-new items (>999.9%) requiring a revenue/units filter.

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 purpose, then a compact semicolon-driven map of keyword/category, defaults, paging, sort/order and filters, ending with examples. Efficient overall, but the mid-sentence filter enumeration ('Filters: revenue, followers, engagement, ...') is a dense run-on that partly duplicates the schema and could be trimmed.

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 26-parameter, zero-required analytics query with an output schema, the description covers the axes an agent needs: scoping (keyword/category/both/neither), default window and row count, paging, sort/order semantics, region validity, and filter families. 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; the description earns an extra point by explaining parameter interactions and defaults in one place — keyword excludes product text, category accepts names or numeric ids at levels 1-3 and merges generic sweeps, order=asc should be paired with a revenue/units filter, region defaults to US. Much of this restates schema text rather than adding new meaning, which keeps it below 5.

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 resource (creators/affiliates), the metric they are ranked by (sales driven), and the output dimensions, so it is instantly distinguishable from sibling tools like creator_search or product_top_selling. It also explicitly clarifies what the keyword does NOT search (products they sell), heading off a likely confusion.

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 explicit routing: keyword vs category vs neither, how the two combine, what happens when both are omitted (top 10 for the most recent ~6 days regardless of window), and the alternative path (rank products with product_top_selling and call product method=creators). Two concrete example payloads seal it.

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 readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds real value by clarifying that searchVolume is TikTok's 7-day figure (never monthly) and that videoCount=0 signals a content gap — non-obvious semantics an agent would otherwise misread from the raw fields.

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, then field semantics, then usage and two compact examples — each sentence adds distinct 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 an output schema present, return values needn't be re-explained, yet the description still summarizes the key fields helpfully. It omits the method-max limit-lowering behavior and pagination flow, but those live in the schema; overall complete for calling the 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 coverage is 100%, so the baseline is 3, but the worked examples ({"keyword":"protein snacks"}, {"method":"feed","channel":"content_gap"}) demonstrate how method combines with keyword or channel — guidance the schema alone doesn't convey. It doesn't cover limit/cursor interplay, keeping it at a 4.

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 (finds TikTok search topics via Creator Search Insights) and immediately distinguishes itself from demand_topic by framing itself as the discovery/list tool whose queryId feeds the detail tool. An agent can tell what it returns and how it differs from siblings without touching 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 demand, content gaps and trend research' plus 'Pass a topic's queryId to demand_topic for charts, audience and related searches' give clear selection guidance and route follow-up work to the correct sibling. The only minor gap is no explicit when-not-to-use contrast against other discovery siblings like demand_keywords or category_trends.

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, non-destructive, open-world, so the safety burden is off the description. The description instead adds the interpretive caveat that scores are relative ranks, not search volume — the single most likely source of agent misuse. It does not mention pagination or the limit-lowering behavior (that lives in the 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?

Three short sentences plus a compact example, with the core capability front-loaded and the critical caveat ('not search volume') placed immediately after. Every sentence carries distinct 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?

With an output schema, full annotation coverage and 100% schema coverage, the description only needs to add interpretation and routing. It does exactly that: it explains what the returned rankings mean and where to go for volume instead, which is the one thing structured fields cannot convey.

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%, including per-method limit caps and method enum meanings, so the baseline is 3. The description's note about method=signals largely restates the schema's own 'signals: autocomplete with click-through and shopping-intent signals', and the example JSON is illustrative rather than semantically additive.

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 resource (TikTok / TikTok Shop autocomplete and keyword ideas) and explains the signals variant adds predicted click-through and a shopping-intent flag. It is distinguishable from siblings by naming demand_find_topics as the volume tool, though it only describes 2 of the 6 methods the tool actually supports.

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 routes the agent away for one key need: 'These rank phrases; they are not search volume (use demand_find_topics for volume).' That is a real when-to-use-else signal. It does not explain when to pick method=tiktok vs shop vs trending vs ad_library, leaving that to the schema.

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 this as read-only, idempotent, open-world, and non-destructive, so the safety profile is covered. The description adds meaningful domain context beyond annotations: popularity values are TikTok's readings and must not be summed across days or described as monthly searches. That is an important caveat for correct interpretation, though it does not cover rate limits or response/pagination 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?

The definition is three sentences and front-loads the core scope before the routing detail and the popularity caveat. The example is compact and immediately useful. Nothing is redundant or 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?

With a full output schema, complete input schema coverage, and annotations covering safety and openness, the description needs only to describe scope and notable caveats. It does that: it names the sibling source for id, summarizes the method-specific outputs, and warns about the most dangerous interpretation error around popularity values.

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 and method. The description still adds value with a compact example showing how id, method, days, and countries are combined in practice. It does not add much beyond the schema for the remaining parameters such as cursor or limit, which keeps it from a 5.

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 resource and scope: 'Everything about one search topic', then enumerates the exact data surfaces it returns (detail, popularity chart, demographics, related searches, guidance, videos). It distinguishes itself from the sibling demand_find_topics by explicitly defining id as the queryId produced by that tool, so an agent can route 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 makes the prerequisite relationship explicit: id must come from demand_find_topics, not a video id or keyword. It also provides a concrete example call with method, days, and countries. It does not enumerate when to choose each method or when not to use this tool, but the context needed to invoke it correctly 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 declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds little beyond structured fields — the worked example is the main value-add — and says nothing about result volume or how the three methods differ in cost.

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?

One dense sentence plus a compact example, with the id provenance front-loaded. Nothing is wasted, though the sentence packs three concepts tightly enough that it reads as a list rather than 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?

With an output schema present and full annotation coverage, the description need not explain returns. Combined with the id-source hint and worked example, an agent has enough to call it correctly; only method-selection guidance 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?

Schema description coverage is 100%, so all seven parameters (including enums for method, sort, detail, and the cursor/limit semantics) are already documented in the schema. The description's example reinforces method=videos with sort=newest but adds no new 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?

Names the resource (one hashtag) and enumerates the three things it can return — detail, videos, related hashtags — plus where the id comes from. It routes to sibling hashtag_search for id discovery, though the core verb ('get') is implied rather than stated.

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 parenthetical 'id from hashtag_search or hashtags[].id on a post' gives clear context for when this tool is the right call versus the search sibling, and the sample call illustrates a valid mode. It stops short of stating exclusions or tradeoffs between method=detail vs videos vs related.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new context: the shape of each result (views and video counts) and the drill-down path. It is silent on pagination, but cursor/limit semantics live in the 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?

Three short sentences front-loaded with the core purpose, followed by the drill-down hint and a compact example. Nothing is redundant and nothing needs to be read twice.

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?

An output schema exists, so return values need no explanation, and the description covers purpose, result contents and next step. The only gap is that pagination and the compact/full detail choice are left entirely to the schema, which is acceptable for a simple 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 limit, cursor, detail and keyword are all documented in the schema itself. The description adds only an example value for keyword and no guidance on limit or detail, so it meets but does not exceed 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 ('Finds hashtags by keyword') plus the fields returned ('total views and video counts'), which separates it from the generic 'hashtag' sibling. An agent can identify the search-vs-detail split immediately.

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 instructs to pass a hashtag's id to 'hashtag' for videos and related tags, giving a clear follow-up path to the sibling. It does not state when to prefer this over content-search tools like video_search, but the search-then-detail workflow 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that status may be live or ended and lists analytics outputs, but it gives no auth, rate-limit, pagination, or freshness caveats, and its 'any market via region' wording is narrower than the schema's supported-region rules.

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 front-loaded and compact, moving from resource identification to method options to an example. The bracketed notation and dense method list slightly reduce readability, but every part contributes useful selection 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?

Given the 9 parameters, rich annotations, 100% schema coverage, and an output schema, the description supplies enough to select a method and provide the required id. The main small gap is that region restrictions are left to the schema, but the overall definition is complete enough for correct invocation.

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. The description adds useful id provenance and a concrete example, but method, region, window, cursor, and detail semantics are already fully documented in the input 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 identifies a specific resource, one TikTok LIVE room, and scopes it by requiring an id sourced from live_search or live_top_selling. It also lists the available data methods, making it distinguishable from the search/ranking siblings, though it does not begin with an explicit 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?

It gives clear usage context by saying the id comes from live_search or live_top_selling and by explaining what the method values retrieve. It does not explicitly state when not to use this tool versus those siblings, 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?

Annotations already establish that this is a read-only, open-world, non-idempotent operation. The description adds useful behavioral context by saying results are LIVE broadcasts on now and by naming two returned signals (viewers and Shop product status), though it does not discuss pagination or rate limits directly.

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 short and front-loaded, stating the main search behavior first, then the alternative, then an example. The sentence about passing a room id to live is useful for follow-up but slightly indirect in context.

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 an output schema present, the description need not explain return values in detail, and it still summarizes the important signals. It is complete enough for correct invocation, with only minor gaps around pagination or region behavior that are covered by 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 parameters like cursor, detail, region, and limit are already well documented. The description adds a concrete keyword example but does not add much beyond the schema for the remaining parameters; a 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 uses a specific verb and resource: it finds TikTok LIVE broadcasts that are on now by keyword. It also states key returned attributes (viewers, whether the room sells Shop products) and explicitly distinguishes the tool from live_top_selling.

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 tells the agent to use this for keyword-based LIVE discovery and explicitly names the alternative for sales rankings: live_top_selling. The example reinforces the expected call shape, and the follow-up mention of live helps sequence tool 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 read-only, idempotent, non-destructive, open-world behavior, so the burden is lighter. The description adds two traits not in the annotations: the hard cap of 10 rows and the fact that the ranking cannot be filtered. Return-field listing plus the presence of an output schema covers shape, though nothing is said about ordering ties, empty results, or currency handling.

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: identity, row contents, the no-filter constraint, and the drill-down path, capped with a concrete call example. Front-loaded and free of 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?

With a full schema, an output schema and rich annotations, the description covers the remaining gaps: the 10-row cap, the ranking metric, and the follow-up tool. The one unresolved question an agent might have — which of window/start/end/region actually govern this ranking — is left implicit.

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 window/start/end/region/detail, and the description only adds an example ({"window":"7d"}) plus the phrase 'over a date range.' The 'takes no filters' wording actually creates mild ambiguity about whether window/start/end apply here, especially since the region parameter description does not list this as a Live method that accepts 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?

States a specific resource (LIVE broadcasts), a precise ranking metric (top 10 by estimated revenue), the time scope (date range), and enumerates the returned fields. An agent knows exactly what it gets back and cannot confuse it with live_search or product_top_selling.

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 'This ranking takes no filters,' which warns the agent that segmentation is impossible here, and routes follow-up work to `live` with method=products, sales or history. It does not name live_search or sibling ranking tools as alternatives, so the exclusion side of the guidance is only partly covered.

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 the safety profile (readOnly, non-destructive, closed-world), so the description's real contribution is the cost disclosure: the call consumes no credits and succeeds even at zero balance. That is exactly the behavior an agent needs before spending budget on a check. It stops short of saying anything about freshness or rate limits, so not 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?

Front-loaded with the resource and its contents, then the cost note, then the usage triggers — a sensible order. The enumerated field list is somewhat long for a tool that already ships an output schema, but it earns most of its space by telling the agent what the user can be shown after calling.

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 an output schema present, the description did not need to enumerate return values, yet it does so harmlessly and adds the two things the schema cannot convey: zero cost and the not-a-TikTok-account scope. Nothing an agent needs in order to decide to call it 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 tool takes no parameters, so the baseline is 4 and there is nothing for the description to compensate for. The description correctly avoids inventing filter options the schema does not offer.

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 resource and scope: 'Your TokConnect plan and credit balance', then enumerates what is covered (plan, interval, credits used/limit/left, reset time, connected apps, upgrade links). It also pre-empts the most likely confusion in this toolset by saying it reads the TokConnect account, not a TikTok account, which no sibling name would disambiguate on its own.

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 explicit triggers: when the user asks about credits, cost or their plan, and proactively before multi-step research likely to exceed ~10 calls. It also gives a cost-based reason ('Free: it uses no credits and works with 0 credits left') that tells the agent this call is safe to make preemptively — that is a genuine when-to-use rule, not vague framing.

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, destructiveHint=false, and idempotentHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the draw is random, a seed makes it reproducible, and it reports the eligible comment count. It stops short of explaining what happens without a seed (different results each run), which is the crux of the non-idempotent hint.

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 purpose before the filter/seed/reporting details. Every sentence carries distinct information with no 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?

An output schema exists, so return values need not be explained, and the description usefully notes it reports the eligible comment count. For an 8-parameter tool the coverage is adequate, though the absence of any when-to-use routing keeps it short of 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 eight parameters including filters and seed are already fully documented in the schema. The description names must_include, unique users, exclude creator, and the seed, but restates them rather than adding syntax or format meaning. 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?

States a specific verb and resource ('Draws giveaway winners at random from a video's comments'), plus the scoping mechanism (optional filters, seed). An agent can distinguish this from read-only comment tools like video_comments or comment_replies immediately.

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?

Conveys the use case (a giveaway draw) and lists the filters, but never names when to use this instead of video_comments/comment_replies or what conditions make it appropriate. No exclusions or prerequisites are stated, leaving 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 the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description does not need to repeat that. It adds useful behavioral context by describing what each method returns, including public reviews and videos tagged at the place, though it leaves pagination and limit behavior to the 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?

The description is a compact, front-loaded sentence followed by a useful example. Every clause earns its place by identifying the resource, accepted id sources, available methods, and a concrete invocation pattern.

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

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

Given the rich schema, output schema, and annotations, the description is complete enough for an agent to select and invoke the tool correctly. Return details are left to the output schema, and parameter limits/paging are covered by the input 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 the schema already documents all five parameters, including enums for method and detail. The description reinforces the id sources and demonstrates method usage in an example, but adds little semantic detail beyond the structured 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 clearly identifies the resource ('One tagged place: business, venue or landmark') and the three retrieval modes: detail, tagged videos, and public reviews. It also distinguishes this from place_search by specifying that the id comes from place_search, a post's place.id, or a place link.

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 usage context by naming accepted id sources and the method options, plus an example. It does not explicitly state when to prefer this over siblings or when not to use it, but the single-place scope is evident from 'One tagged place' and the referenced sibling place_search.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds the downstream poi-id usage pattern, but its list of return fields overlaps with the output schema and it says nothing about auth, rate limits, or pagination.

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 primary function and immediately followed by the downstream action. There is no wasted text.

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 an output schema, full annotation coverage, and 100% parameter descriptions, the description is sufficient for an agent to call the tool correctly. It could mention pagination or result-count behavior, but the schema already exposes those details.

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 `keyword`, `count`, and `detail` are fully documented in the schema. The description only reinforces that keyword-based lookup is the core operation and does not add syntax or format guidance beyond the schema.

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

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

The description uses a specific verb and resource: 'Finds TikTok places (businesses, venues, landmarks) by keyword.' It also distinguishes this search tool from the sibling `place` tool by explaining the poi-id handoff.

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 implies a two-step workflow: use this tool to find a poi id, then pass that id to the `place` tool for detail, videos, or reviews. It does not explicitly state when not to use it or name alternative search tools, but the downstream context 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?

Goes well beyond the readOnly/idempotent annotations by disclosing live-vs-analytics data sourcing, per-method limits that are silently lowered and reported in notes, the ~2-day analytics lag, region refusal for unsupported countries, and that detail=full returns a large raw record. These are exactly the operational traits an agent needs before calling.

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 and id semantics are front-loaded, then examples anchor the parameters. It is dense but readable; the main inefficiency is that the long method list largely restates the schema's method description, so a portion of the text is duplicated rather than additive.

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 an output schema present and 100% parameter coverage, the description supplies everything else an agent needs: the two data regimes, the region allow-list behavior, window defaults and lag, and pagination via cursor. Nothing essential to 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; the description adds value with concrete call examples showing method+window+region+ids interplay and reiterating that id accepts a product link. Much of the method text duplicates the schema's enum description, limiting the uplift to 4.

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 resource ('one TikTok Shop product') and enumerates the twelve methods it can return, so the agent knows exactly what data is reachable. It does not, however, contrast itself with siblings such as product_top_selling or shop, so sibling differentiation is left to inference.

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 rich per-method context (page = live price/stock, reviews = public reviews, sales = revenue/units split) which implies when each mode applies, but it never states when to choose this tool over product_top_selling, shop, or shop_browse. No explicit when-not or exclusion guidance is provided.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: the ~700-row cap per keyword, max_rows scanning up to 3,000 (US only, keyword required, not with category), limits above a method maximum being silently lowered and reported in notes, and window ending at the last complete day. It omits how the 'estimated' revenue is derived, which 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?

Front-loaded with what is returned, then defaults, sorting, filters, region, and examples — a sensible order. The mid-sentence filter enumeration ('Filters: revenue, units, growth, price...') largely restates the schema property names and is the least earned portion, but the rest is dense and information-bearing.

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 25-parameter tool, the description covers default behavior, row caps, paging, region support, sort/order interaction, and no-parameter fallback, and an output schema plus annotations carry return shape and safety. An agent has everything needed to call it correctly on the first attempt.

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 goes beyond the schema by explaining interaction semantics — keyword plus category narrows further, category needs keyword sweeps, sort=growth favors brand-new items (>999.9%) and should be paired with a revenue/units filter, order=asc is useful to skip dead listings. Two worked examples make the intended combinations concrete.

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 resource (TikTok Shop products) and the exact ranking/return surface (revenue, units, channel split, growth, price, commission, creators, launch date, daily trend) over a date range. It also names the sibling it is not: 'Shopper's live view: shop_browse.' An agent can distinguish this from shop_top_selling/product 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?

Explicit rules for the key decision: keyword, category, or neither (neither yields the top 10 for the most recent days regardless of window), plus a note that category alone merges generic keyword sweeps. It routes to shop_browse for the live shopper view. It does not explicitly contrast with shop_top_selling or creator_top_selling, so a 4 rather than 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds only the fact that the data is 'static', which usefully signals stability/cacheability, but it says nothing about size, output shape, or the cost implied by detail=full.

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?

One front-loaded sentence that defines the resource, followed by a concrete example call. The enumeration is long but every item corresponds to a real enum value, so it earns its space; a tighter grouping could still trim a few 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?

With a full output schema, 100% parameter coverage, and complete annotations, the description only needs to establish what the tool is and why it exists. It does that; the only residual gap is not explaining what detail=full costs or what the lists look like structurally.

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 both parameters are enums with per-value documentation, so the schema carries the semantics. The description contributes a single example invocation ({"method":"sales_filters"}) but adds no meaning beyond the enum 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 names the resource precisely and enumerates the exact list families returned (CSI channels/languages, explore category ids, LIVE gift coin prices, ad regions, creative markets, sales filters). It implicitly separates itself from siblings by framing everything as 'static lists other tools need' rather than queries, though it never names a sibling explicitly.

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?

'Static lists other tools need' plus the listed mappings (e.g. csi_channels feeding demand_find_topics, explore_categories feeding video_feed method=explore) tell an agent when to reach for this tool: to resolve ids/codes before calling another tool. It lacks an explicit statement of when not to use it, so it falls 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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered; the description adds the meaningful split that 'store' is live shopper-facing data while the other methods are Shop Analytics and market-dependent via region. It also discloses that strategy data leaves individual affiliates unnamed, which is behavioral context the schema does not convey.

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 resource and the id-resolution hint, then the method inventory, then an example. Dense but every clause carries information; the inline method enumeration is long but justified for a 10-method multi-purpose 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?

With an output schema, full annotation coverage and 100%-documented parameters, the description only needs to orient the agent, which it does. Minor gaps remain: paging via cursor and the compact/full detail tradeoff are only in the schema, not reinforced 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 description coverage is 100% and the method enum already carries per-value explanations, so the description's method list largely restates structured data. The one added element is a concrete example invocation showing id + method + window together, which is helpful but marginal against an already complete 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 resource and scope ('Everything about one TikTok Shop seller') and immediately enumerates the two families of data available (live storefront vs Shop Analytics methods). It also tells the agent how the required id is obtained and names siblings (shop_top_selling, shop_regions), so it is distinguishable 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 explicit guidance for the required id (found on products, or via shop_top_selling with keyword=<shop name>) and points to shop_regions for market support, with the constraint that unsupported countries are refused. It does not explicitly contrast this tool with shop_browse, but the method list makes the intended context 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 declare read-only, non-destructive, open-world, non-idempotent behavior, so the bar is lower; the description still adds real value by disclosing that displayed sold counts are lifetime and that results can be a truncated fallback list. It stops short of covering paging semantics or the region-refusal behavior, which are only in the 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?

Three front-loaded sentences: scope, return fields, then the caveat-plus-alternative, closing with a compact example. No filler or repetition of the title.

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 10-parameter, fully documented, output-schema-backed read tool, the description covers what is browsed, what comes back, the main data-quality caveat, and the correct sibling alternative. Nothing needed to select or 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 description coverage is 100% and the enum semantics (method, sort, detail, region) are already documented there, so baseline 3 applies. The description's example adds marginal illustration of keyword+sort but no syntax or meaning beyond the schema.

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

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

States a specific verb+resource+scope: what a shopper sees on TikTok Shop (US) right now, covering search, keyword/category pages, deals and flash sales. It also lists the returned fields (price, discount, units sold, rating, shop), so the agent knows exactly what this yields versus siblings.

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 excludes itself from sales-ranking use and routes the agent to product_top_selling for best sellers, and warns that broad single-word searches return only a short fallback list. The inline example {"keyword":"lip oil","sort":"best_sellers"} demonstrates the intended default invocation.

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 readOnly/idempotent/non-destructive, so safety is covered. The description adds genuine behavioral context not in annotations: the core vs. extended tier split and the hard rejection of unlisted countries downstream. It doesn't describe response size or pagination behavior, though an output schema exists to cover return shape.

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: what it returns, the tier taxonomy, the downstream contract, the refusal/default rule. Front-loaded and zero filler; even the example call earns its place as a minimal-invocation hint.

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-required-param lookup with a full output schema, everything an agent needs is present: how markets are grouped, the default, and the consequence of using an unsupported region elsewhere. The only untouched detail is the optional 'detail' flag, which the schema handles.

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?

One optional parameter with 100% schema description coverage, so the schema already explains compact vs. full. The description never mentions 'detail' at all and instead shows 'Example: {}', implicitly framing the call as parameterless. Baseline 3 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?

States a specific verb and resource ('Lists the TikTok Shop markets Shop Analytics covers') plus what each entry carries (currency, language, tier). It also carves out the tool's role relative to siblings: it is the lookup you consult before passing a region code to a Shop Analytics 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?

Explicitly tells the agent what to do with the output ('Pass the code as region to any Shop Analytics tool'), what is out of scope ('other countries are refused'), and what happens by default ('Default market is US'). No inference required.

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 the read-only/idempotent safety profile, and the description adds real behavioral context beyond them: cursor paging up to 100 per page with roughly 500 rows per keyword, the quirk that omitting keyword returns only the top 10 for the most recent ~6 days regardless of window, and that sort/order only apply with a keyword. These are the non-obvious behaviors an agent would otherwise discover only by failing.

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 purpose and metrics before the conditional rules, and the two inline JSON examples make the call shape concrete. It is a single dense paragraph that partly repeats schema content (filter enumeration, paging limits), so it is efficient but not maximally 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?

With 16 optional parameters, an output schema, and full annotation coverage, the description supplies exactly the missing layer: which parameter combinations are meaningful, what defaults produce, and how to reach seller IDs via sibling tools. Nothing an agent needs before invoking it 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 the baseline is 3; the description goes beyond it by disambiguating keyword (a shop/brand name matched loosely, not a product type, with a concrete 'medicube' example) and by explaining the interaction between type, keyword, sort and order. It still largely restates the filter list rather than adding new semantics for each filter, keeping it short of a 5.

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 and resource — TikTok Shop sellers ranked by estimated sales over a date range — and enumerates the returned metrics (revenue, units, growth, average price, revenue split). It explicitly distinguishes itself from product_top_selling, which covers the product/category angle, so an agent can tell the two apart 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 explicit when-to-use branches: keyword present vs omitted, type=brands versus default shops, and a full workaround path for the shops behind a product type (product_top_selling → product method=page → sellerId). It also states exclusions, e.g. no category scope for shops and that filters/sort do not apply with type=brands.

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 readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds the accepted id formats and a concrete invocation example, but says nothing about pagination behavior or the notes mechanism that the schema mentions for clamped 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 plus a minimal example, with the id sourcing rule front-loaded. The telegraphic phrasing costs a little readability 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?

With an output schema present, return values need not be described, and all five parameters are fully documented in the schema. What remains missing is minor: no guidance on paging through many videos or on the relationship between limit and the method-specific maximum.

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 explains id, limit, cursor, detail and method. The description's example clarifies how id and method combine in practice, but adds no semantics the schema does not already carry; 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?

Names a specific resource (one TikTok sound) and the two modes it supports (detail or videos using it), and points at sound_search as the id source, which separates it from the search sibling. The verb is elliptical ("detail or the videos using it"), so the operation has to be inferred, but the intent is unmistakable.

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?

Implies the precondition (you must already have a sound id or link) and tells you sound_search is how ids are found, plus that method selects detail vs videos. There is no explicit when-not or statement of what the tool returns versus the search tool, so routing 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?

Annotations already declare readOnly, openWorld, non-idempotent, and non-destructive, so the safety profile is fully covered and the description needn't repeat it. The description adds the mode taxonomy and the sibling hand-off, but says nothing about result volume, paging behavior, or region-refusal edges beyond what the schema states. 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?

Three short sentences, front-loaded with purpose and mode enumeration, followed by compact inline examples. The final example clause overlaps slightly with the first sentence but cheaply reinforces how to invoke the tool rather than wasting space.

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 an output schema present and annotations covering safety, the description only needs to convey modes and routing, which it does. The remaining gap is the conditional relationship between `method` and `keyword` (keyword only applies to method=keyword), which an agent must infer from the schema rather than the description.

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 every parameter (limit, cursor, detail, method, region, keyword) is already documented in detail, including the method enum semantics and region restrictions. The description's examples illustrate keyword and method usage but add no syntax or constraint information 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 (finds TikTok sounds) and enumerates the four distinct result sets: keyword matches, hot original sounds, beats, and licensed music. It also explicitly distinguishes itself from the sibling `sound` tool by telling the agent to pass an id there for a sound's 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?

The description makes mode selection concrete with two literal example invocations (`{"keyword":"sped up"}` and `{"method":"hot"}`) and routes id-based lookups to the sibling `sound` tool. It stops short of stating exclusions or preconditions, such as that `keyword` is required when `method=keyword` or that region restrictions apply.

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 read-only, idempotent, non-destructive behavior, so safety is covered. The description adds the non-obvious behavioral split that Shop Analytics methods are region-scoped and priced in the market's currency, which materially affects result interpretation. It omits operational behavior such as capping/pagination consequences, which live only in the 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?

Front-loaded with the scope sentence, then capabilities, then usage, then a targeted comment_themes clarification with its own example. Dense but every clause carries information; the appended comment_themes paragraph is slightly tacked-on after the general examples.

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 an output schema present and 100% schema description coverage, the description need not explain return values, and it covers every method family an agent would need at selection time. The remaining details (limits, cursors, region refusals) are fully handled in the schema, so nothing required 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; the description earns one more by giving concrete invocation shapes for two different methods plus a dedicated comment_themes example, which reduces method/parameter mismatches in a 13-parameter dispatcher. The added meaning is mostly illustrative rather than new 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?

The description names a specific resource — one video or photo post — and enumerates the retrievable facets (detail, comments, replies, transcript, similar, Shop Analytics revenue/products), so an agent can immediately tell it is a single-post lookup rather than a discovery tool. It never explicitly contrasts itself with video_search or video_feed, which is the only thing keeping it from 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?

"Use the post id or link from any other tool" tells the agent this is the follow-up call after a search, and the worked examples show correct id+method pairings. It stops short of stating when to prefer comments over comment_themes or transcript over captions beyond what the method prose implies, and names no alternatives to itself.

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?

Goes beyond the readOnly/openWorld annotations by disclosing that For You is sampled 'as a neutral US viewer' (a geo/personalization caveat an agent cannot infer) and that results are a sample rather than a ranking. Limit-cap lowering is already handled in the schema, so the remaining gap is minor.

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 plus a concrete example, with the most decision-relevant fact ('Samples, not rankings') front-loaded. 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 full schema coverage, rich annotations, and an output schema, the description only needs to cover intent and sampling semantics, which it does. Minor omission: no mention that the different methods have different page-size ceilings (that lives only 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 coverage is 100%, so the baseline is 3; the description adds an example invocation ({'method':'explore','category_id':3}) and reiterates where category_id values originate, which links parameters across tools rather than restating 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 ('samples') and resource ('TikTok's own feeds') and enumerates the three feed families: For You, Explore categories, and Discover (creators/hashtags/sounds). 'Samples, not rankings' plus 'TikTok's own feeds' cleanly separates it from sibling search tools (video_search, hashtag_search) and ranking tools (video_top_selling).

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 a prerequisite dependency — category ids come from reference method=explore_categories — which is genuinely useful routing information. However, it never states when to prefer this over video_search or video_top_selling; the distinction is only implied by the word 'samples'.

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?

The description adds valuable behavioral context by listing the specific data points returned by the search (views, likes, shares, etc.). While annotations handle safety and read-only status, this context helps the agent understand the 'result' behavior of the 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?

The description is highly concise and efficient, dedicating its space to the two most important pieces of information: the core function and the critical differentiation from other available search functions. The example format is also 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?

Given the high schema coverage, the description successfully fulfills its role by focusing on usage context (return fields) and scoping (not sales ranking), providing all necessary information for the agent to select and invoke the tool confidently.

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?

Although the schema is 100% covered, the description adds semantic meaning by providing a practical call example. This example demonstrates how to combine `keyword`, `sort`, and `date`, offering guidance on parameter interaction that the schema does not detail.

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—searching TikTok posts—and immediately distinguishes it from a related sibling tool by noting it is 'Not a sales ranking' tool, directing users to 'video_top_selling' instead.

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 provides a specific usage guideline by stating that this tool retrieves the full suite of TikTok metrics (views, likes, etc.). Crucially, it advises against using this for sales ranking, steering the user to the correct alternative 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 readOnly/idempotent/non-destructive/openWorld, so the safety bar is met structurally; the description adds that the result is a fixed top-10 ranking by estimated revenue and what dimensions it exposes. It does not discuss the estimation methodology or any latency/cost characteristics, 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?

Four dense sentences, front-loaded with the definition and metric, then routing, then an example — no filler. The middle routing clauses are somewhat compressed and could be skimmed past, but every sentence carries 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 an output schema present the description need not describe return values, so the field listing is bonus rather than required; the schema, annotations, and routing advice together cover what an agent needs to invoke it. The one soft spot is the blanket 'takes no filters' claim sitting next to region/start/end/window scoping parameters, which could momentarily confuse the scope of the result set.

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 parameter documentation baseline is 3; the description earns an increment by supplying a concrete call example ({"window":"7d"}) and by clarifying that none of the available parameters act as content filters on the ranking. It does not itself explain region currency behavior, which the schema carries.

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 precise verb+resource+metric: the top 10 shoppable videos ranked by estimated revenue over a date range, and enumerates the returned fields (revenue, units, views, GPM, ad metrics, AI-generated flag, creator). It distinguishes itself from siblings by noting the ranking takes no filters and by routing niche analysis to product_top_selling instead.

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-not to use it ('takes no filters') and names the alternative workflow: rank a niche's products with product_top_selling, then product method=video_sales. It also tells the agent the next hop ('Pass a row's id to video method=transcript or products'), which is actionable routing, not inference.

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