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

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely new context beyond annotations: it is a live TikTok request, billed per call, and hits GET /v1/hashtag/info — material for cost-aware planning.

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 clauses, front-loaded with the core action, then the routing dependency, then the cost/endpoint note. No filler.

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

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

For a single-param read with no output schema, the description covers input format, the dependency on get_v1_hashtag_medias, and cost. It does not hint at the response payload (e.g., that the hashtag id is returned), a minor gap.

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

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

With one required parameter and 0% schema description coverage, the description carries the burden and does so usefully: it tells the agent to pass the hashtag name without the '#' prefix. It omits the 1-50 length constraint present in the schema, so not a full 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?

States a specific verb and resource ('Get a TikTok hashtag (challenge) by name'), which is clearly distinct from sibling user/media tools like get_v1_media_by_id.

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: 'Use it to get the hashtag id that get_v1_hashtag_medias needs', naming the dependent sibling and the condition for calling it. No when-not or exclusion guidance is given, 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds operationally important context: it is a live request to TikTok, billed per call, and returns a single page driven by cursor. It stops short of describing rate limits, error modes, or the response 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 compact sentences, front-loaded with what the tool does and the id prerequisite, then pagination, then the alternative, then billing/cost. Nothing is redundant and the endpoint is appended as a compact footnote.

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

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

For a paginated read tool with no output schema, the description covers the essentials: source of the id, page sizing, cursor paging, cost, and the sibling alternative. It does not hint at the shape of the returned video objects, which is a minor gap given no output schema exists.

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 0% and the schema only carries bare titles, so the description carries the full burden — and it does: `id` must be the hashtag id rather than the name, `count` is the page size (default 30), and `cursor` drives pagination. All three parameters gain meaning absent from the schema.

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

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

States a specific verb and resource ('List videos under a TikTok hashtag') plus the per-call granularity ('one page per call'). It is clearly distinguishable from the nearest siblings: get_v1_hashtag_info (hashtag metadata) and get_v2_search (free-text search).

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 an explicit prerequisite ('Pass the hashtag id (from get_v1_hashtag_info, not the name)') and an explicit alternative with its selecting condition ('Use get_v2_search to search by free text instead'). An agent can route correctly without opening any 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structured context: this is a live request to TikTok and it is billed per call, which an agent needs for cost/rate decisions. It does not, however, describe failure modes or rate 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?

Four short sentences, each with a distinct job (purpose, selection rule, related tool/return, cost), front-loading the identifier requirement before the routing 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?

Covers what it returns, which sibling to use instead, which sibling to use next, and the billing/network reality, with no output schema needed since the return is described. Nothing an agent needs 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 description coverage is 0%, so the description must carry the burden; it characterizes the id as numeric and as coming from another tool, which clarifies the ^\d{19}$ pattern the schema only encodes silently. It stops short of stating the 19-digit format or example, but adds real meaning.

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

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

States a specific verb and resource ('Get a TikTok video by numeric video id') and immediately differentiates itself from the sibling get_v1_media_by_url. An agent can pick the right tool without opening either schema.

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

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

Explicit when-to-use ('when you have the id from another tool') and when-to-use-the-alternative ('use get_v1_media_by_url when you have a link'), plus a routing hint to get_v1_media_comments_by_id for comments. Nothing is left 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 declare readOnly/openWorld/destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond annotations: it is a live request to TikTok and is billed per call. It also discloses the downstream workflow (pass the returned id to comment tools), though it doesn't describe result fields or rate/error behavior beyond the schema's 400 note.

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

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

Three tight sentences with zero waste. Purpose and sibling routing are front-loaded, followed by workflow, then billing/endpoint metadata.

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

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

There is no output schema, but the description states what is returned and how to chain it. Combined with the fully documented param and the safety annotations, this is nearly complete; only concrete return fields or pagination detail are absent, which is minor for a single-resource 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% and the single `url` param already documents accepted link forms and the 400 behavior for non-media links. The description adds no parameter semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb+resource ('Get a TikTok video by its link') and immediately distinguishes itself from the sibling get_v1_media_by_id by input type. An agent can route between the two without opening either schema.

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

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

Explicitly names the condition that selects this tool ('when you have a tiktok.com URL') and the alternative with its own condition ('use `get_v1_media_by_id` when you already have the numeric video id'). Nothing is left 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 declare readOnly, non-destructive, and open-world. The description adds meaningful context beyond that: one page per call, cursor-based pagination, and that this is a live TikTok request billed per call. Rate limits and error behavior remain unstated, keeping it short of a 5.

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

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

Front-loads the core purpose, then sibling routing, then parameter roles and the billing caveat. No redundant or filler sentences; every clause earns its place.

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

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

With no output schema, the description still conveys pagination behavior and per-call billing, which is enough to invoke it correctly. Return-shape specifics are absent but a paged read tool rarely needs them spelled out.

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 0%, so the description carries the burden, and it does well: media_id and comment_id are sourced from the comments tool, count is the page size, cursor pages through. It omits the 19-digit pattern constraint, but that lives 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?

States a specific verb and resource: 'Get replies under one comment of a TikTok video.' It explicitly distinguishes itself from the sibling top-level comments tool, so an agent can route correctly without opening either schema.

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

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

Gives explicit when-to-use ('read a thread') and names the alternative ('use get_v1_media_comments_by_id for the top-level comments'). It also explains where the required IDs come from (the comments tool), removing ambiguity about prerequisites.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint=false, so safety is covered. The description adds genuinely new context: 'Live request to TikTok, billed per call' and one-page-per-call pagination behavior. It stops short of rate-limit or return-shape detail, but the cost/billing disclosure is valuable.

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

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

Front-loads the core action, then sibling routing, then parameters, then the billing caveat, closing with the raw endpoint. Every sentence earns its place with 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?

No output schema exists, but annotations cover the safety profile and the description covers parameters, pagination, and billing. It is complete enough for correct invocation, though the id format and count bounds are left to 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 0%, so the description must carry the burden, and it largely does: it explains id (video id), count (page size, default 30), and cursor (pages through). It omits the 19-digit id format constraint and any bounds on count, so it does not fully compensate.

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

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

States a specific verb and resource ('Get comments on a TikTok video') and immediately distinguishes itself from the sibling that handles replies. An agent can tell it apart from get_v1_media_comment_replies_by_id without opening either schema.

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

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

Explicitly names the alternative tool and the condition that selects it ('Use get_v1_media_comment_replies_by_id for replies under one comment'), and explains how to iterate pages via cursor. The routing decision is fully specified.

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 only declare readOnly/openWorld/non-destructive; the description adds genuinely new behavioral facts: the response is a URL plus HTTP headers rather than the file, the file is not downloaded, it is a live request to TikTok, and it is billed per call. These are the traits an agent needs before invoking a metered network call.

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

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

Three sentences, each load-bearing: what it returns, which siblings to use instead, and the billing/live-call caveat. The core purpose is front-loaded and there is no filler.

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

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

With no output schema, the description compensates by explaining exactly what is returned (file URL and the headers to send with it) and what is not (the file itself). For a one-parameter read tool, an agent has everything needed to call and interpret it correctly.

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

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

Schema description coverage is 100% and the single 'id' parameter already carries a pattern and an example, so the schema does the heavy lifting. The description only restates 'by video id' without adding format or validation meaning beyond the schema, which is the baseline-3 case for full coverage.

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

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

States a specific verb (get), resource (download link for the audio track of a TikTok video) and the key input (by video id). It explicitly differentiates itself from the sibling tools that fetch the video file or take a URL, so an agent can distinguish it without opening any schema.

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

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

Names both alternatives by exact tool name and the condition that selects each: use music_download_by_url when you have a link, and video_download_by_id for the video file. This is explicit when-to-use/when-not guidance rather than implied context.

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 safety (readOnlyHint, openWorldHint, destructiveHint). The description adds that it returns a file URL and HTTP headers (not the file itself) and that it's a live billed request. It doesn't mention rate limits, auth needs, or error behavior, but these are minor gaps given the annotations.

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

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

Two efficient sentences: first states purpose and return format, second gives alternatives and billing context. No wasted words.

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

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

Covers purpose, return value, alternatives, and billing. No output schema exists, so the description's explanation of what is returned (file URL and headers, not the file) is valuable. Could mention pagination or rate limits, but overall complete for a simple GET 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%, and the schema itself details accepted URL forms and rejection cases. The description only says 'by the video's URL', adding no syntax or format detail beyond what the schema provides.

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

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

States a specific verb (Get) and resource (download link for the audio track of a TikTok video) with clear scope. It names sibling tools get_v1_media_music_download_by_id and get_v1_media_video_download_by_url, so the agent can distinguish it without opening schemas.

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

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

Explicitly says to use this tool when you have the video's URL and points to the alternative for video id and video file downloads. It also notes billing: live request to TikTok, billed per call.

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, openWorldHint=true and destructiveHint=false, so the description is not carrying the safety burden. It still adds genuinely useful non-obvious context: it returns a URL plus the HTTP headers to send, the file itself is not downloaded, and each call is a live, billed TikTok request. It stops short of describing failure modes or auth/rate-limit specifics, 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 core purpose, then return behavior, then parameter note, then sibling routing, then cost. Every sentence earns its place, though the trailing '(GET /v1/media/video/download/by/id)' endpoint restates the name and is mildly 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?

For a two-parameter read-only fetch with no output schema, the description covers what the tool returns (URL + headers), what it does not do (no file download), the watermark toggle, cost, and sibling selection. Nothing an agent needs 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 only 50%: `id` is documented with a pattern and example, but `watermark` has no description in the schema. The description fills that gap directly by explaining the default-true behavior and that it 'selects the watermarked version', which is exactly the missing semantics.

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

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

States a specific verb+resource+scope: 'Get a download link for a TikTok video by video id', and explicitly distinguishes itself from the URL variant and the music-track sibling. An agent can tell it apart from get_v1_media_video_download_by_url without opening either schema.

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

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

Names two alternatives with the exact condition that selects each: 'Use `get_v1_media_video_download_by_url` when you have a link and `get_v1_media_music_download_by_id` for the audio track only.' Nothing is left 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 readOnly/openWorld/non-destructive, but the description adds valuable beyond-schema context: the return is a file URL plus headers (the file itself is not downloaded), watermark defaults to true, and requests are live and billed per call. This billing and return-format detail is exactly the kind of behavioral insight the annotation set does not provide.

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

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

Front-loaded with the core purpose, then scoping rules, then routing alternatives, then cost model. Every sentence adds a distinct piece of 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?

For a 2-param read tool with no output schema, this covers the return shape (URL + headers, file not downloaded), parameter default behavior, sibling routing, and per-call billing. Nothing an agent needs 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 50%. The url parameter is richly documented in the schema itself (accepted forms, 400 behavior), so the description needn't repeat it. The description does add meaning for watermark ('default true' selects the watermarked version), which is not in the schema. Baseline 3 is appropriate given the schema does the heavy lifting on url.

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

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

States a specific verb (Get a download link) and resource (TikTok video by URL), and explicitly distinguishes from siblings get_v1_media_video_download_by_id and get_v1_media_music_download_by_url by naming the condition that selects each.

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 alternatives: use by_id when you have the video id, music tool for audio only. Clear when/when-not with 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 already declare readOnly/openWorld/non-destructive, and the description adds real value beyond them: it is a live request, billed per call, may return 404 ProfileUnavailable, and the returned user object carries the secUid needed by the by-secUid tools. That chaining and cost context is exactly what annotations cannot 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?

Three sentences, all load-bearing: purpose, fallback routing, return/chaining plus cost. The endpoint annotation is appended compactly and nothing is repeated from structured fields.

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

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

No output schema exists, and the description covers the return value ('the user object'), the key field to extract (secUid), the error case, and the cost model. Nothing an agent needs to invoke or chain this call 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?

Only one parameter with 0% schema description coverage, so the description must compensate. It does so meaningfully by specifying the format constraint '(without @)', which the schema's bare string type does not express, though it omits the 2–24 length bounds.

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

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

States a specific verb and resource ('Get a TikTok profile by username') and explicitly distinguishes itself from the sibling get_v3_user_by_username by naming the fallback relationship. An agent can tell the two apart without opening either schema.

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

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

Gives an explicit ordering rule ('Use it first for any account') plus the exact trigger for switching tools ('404 ProfileUnavailable'), naming the alternative. Both when-to-use and when-to-switch are 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond them: one page per call, live request to TikTok, billed per call, and the default page size. It doesn't mention rate limits, follower ordering, or what happens at the end of pagination, keeping it short of a 5.

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

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

Three dense sentences, front-loaded with the primary action and scope, then routing, then pagination mechanics. Every clause carries information and nothing is repeated from the schema.

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

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

There is no output schema, and the description partially compensates by naming the response field next_page_id and the pagination contract. It stops short of describing the follower record shape or end-of-list behavior, which would fully close the gap for a paged read tool.

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

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

Schema coverage is only 33%, so the description must carry weight, and it does: it defines count as page size with a default of 30 and explains that page_id should be fed from the previous response's next_page_id. Only the secUid format (pattern/length, already in schema) is left unelaborated.

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

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

The description states a specific verb and resource ('List a TikTok user's followers by secUid'), scopes the behavior ('one page per call'), and names the sibling it is not ('use get_v1_user_followers_by_username when you only have a handle'). An agent can distinguish it from the many other get_v1_user_* siblings 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?

It gives an explicit trigger ('use it when you already have the secUid from a profile') and an explicit alternative with its own selecting condition. It also explains the pagination workflow (pass next_page_id as page_id), leaving 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 already declare read-only, non-destructive, open-world behavior. The description adds real value beyond them: one page per call, the pagination handoff (next_page_id -> page_id), and that it is a live billed request to TikTok. It stops short of describing rate limits or failure modes, 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?

Roughly three dense sentences, all front-loaded with purpose first, then routing, then pagination and cost. Every sentence carries distinct information with 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?

No output schema exists, and the description still conveys the relevant return mechanic (next_page_id for pagination). Combined with the annotations, an agent has enough to invoke and page correctly, though response shape beyond the cursor is unstated.

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

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

Schema coverage is only 33%, so the description must compensate, and it does: it explains page_id chaining from the previous response and defines count as page size with a default of 30. Only username's format is left unstated, which is minor.

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

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

States a specific verb ('List'), resource ('TikTok user's followers'), and lookup key ('by username'). It explicitly differentiates from the secUid variant and the following variant, so an agent can pick it without opening any schema.

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

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

Gives an explicit selection rule ('use it when you have a handle') and names two alternatives with the conditions that favor them (secUid variant when you already have a secUid; following variant for accounts the user follows). Nothing is left 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 declare readOnlyHint, openWorldHint and destructiveHint=false, so safety is covered; the description adds genuinely useful context beyond them: it is a live TikTok request billed per call, and it discloses pagination semantics (one page per call, next_page_id chaining). It does not describe rate limits or failure modes, but the added operational context is substantial.

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

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

Four tightly packed sentences, front-loaded with purpose and the routing decision, then pagination mechanics and cost, then the endpoint. No filler; every clause carries information an agent needs.

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

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

For a three-parameter read tool with no output schema, the description supplies everything needed: how to identify the target, when to pick this tool over its sibling, how to paginate, and the cost model. Return structure is only partially implied, but the pagination field is called out explicitly.

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 only 33% (only `page_id` is described), but the description compensates by explaining that `page_id` should carry `next_page_id` from the previous response and that `count` sets page size with default 30. That covers all three parameters, though it adds little about `secUid`'s format beyond the schema's pattern/length constraints.

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

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

States a specific verb and resource ('List accounts a TikTok user follows by `secUid`') with explicit scope, and names the sibling it is not (get_v1_user_following_by_username) so an agent can distinguish the two without opening either schema.

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

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

Gives a clear when-to-use condition ('when you already have the `secUid` from a profile') and names the exact alternative plus the condition that selects it ('when you only have a handle'). Nothing is left 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 declare readOnly/openWorld/non-destructive, so safety is covered; the description adds real behavioral context beyond them — that each call is a live billed TikTok request and that pagination is one page per call with next_page_id chaining. It stops short of describing the response payload shape (per-account fields), which is the only notable 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-loads purpose then routing then pagination mechanics, with essentially no filler; the trailing '(GET /v1/user/following/by/username)' is mild redundancy against the tool name but harmless. Dense but every clause 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 no output schema, the description correctly carries the pagination contract and the next_page_id handoff, which is the main thing an agent needs to iterate pages. It is complete enough to call correctly, though it never hints at what fields come back per followed account.

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 only 33% (count and username undocumented in-schema), and the description compensates: it defines count as page size with default 30 and explains the page_id/next_page_id continuation contract. Username's format constraints (2-24 chars) are left to the schema only, keeping this below 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?

States a specific verb and resource ('List accounts a TikTok user follows by username') plus the paging granularity ('one page per call'). It explicitly names the sibling tools it is not (secUid variant, followers variant), so an agent can disambiguate without reading schemas.

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

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

Gives an explicit selection rule: use this when you have a handle, use get_v1_user_following_by_secUid when you have the secUid, and get_v1_user_followers_by_username for followers. When-to-use and alternatives are both covered with 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 already cover the safety profile (readOnly, non-destructive, open-world), and the description adds non-obvious operational context: it is a live billed request to TikTok and returns one page per call. It omits rate-limit/error behavior, so it falls just 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?

Three tight sentences, front-loaded with the core purpose, followed by sibling routing, pagination mechanics, and cost/endpoint metadata. No filler.

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

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

For a paginated list tool with no output schema, the description supplies the missing return-value contract (the `next_page_id` field) and the billing/live-request caveat, so an agent has everything needed to call and iterate correctly.

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

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

Schema description coverage is only 33% (just `page_id`), so the description compensates well: it explains where `secUid` comes from and, crucially, that `next_page_id` from the prior response must be passed as `page_id`, plus the `count` default of 30. Minor gap: no mention of the `secUid` length/pattern constraints.

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

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

States a specific verb (List) and resource (a TikTok user's playlists) scoped by `secUid`, and explicitly contrasts itself with `get_v1_user_playlists_by_username`, letting an agent distinguish it from the many sibling user endpoints without inspecting schemas.

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

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

Explicitly states when to use this tool ('when you already have the `secUid` from a profile') and names the exact alternative for the other case ('when you only have a handle'). It also gives concrete pagination guidance for the next call.

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, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds non-obvious operational context: it is a live TikTok request billed per call, and it advances one page per invocation via `next_page_id` -> `page_id`. Auth requirements and rate limits are not mentioned, keeping it short of a 5.

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

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

One dense paragraph with purpose and routing front-loaded, followed by pagination mechanics, cost note, and the raw endpoint as a trailing reference. Every sentence carries distinct information; nothing is restated from the name or 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?

There is no output schema, and the description supplies the one return detail an agent needs (the `next_page_id` field for paging), plus cost and routing context. Missing are return-shape basics beyond pagination and any auth/rate-limit notes, but for a 3-param read-only list tool this is close to complete.

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

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

Schema description coverage is only 33% (only `page_id` is documented), so the description must compensate, and it does: it explains the `next_page_id`->`page_id` handoff and that `count` sets page size with a default of 30. It does not mention the username length bounds (2-24) that the schema enforces, so a small gap remains.

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 ('List a TikTok user's playlists by username, one page per call') and immediately disambiguates from two named siblings covering the secUid variant and the user-videos endpoint. An agent can select this tool without opening any schema.

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

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

Explicit routing rules: use this when you have a handle, use get_v1_user_playlists_by_secUid when you have a secUid, use get_v2_user_medias_by_secUid for videos. It also states the pagination procedure and the `count` default, leaving nothing 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 safety (readOnlyHint, destructiveHint=false) and openness (openWorldHint), so the description's added value is the billing/live-call disclosure ('Live request to TikTok, billed per call') and the one-page-per-call pagination behavior. It does not describe rate limits or failure modes, keeping it short of a 5.

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

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

Four tight sentences: purpose, sibling routing, pagination mechanics, cost. Front-loaded with the core operation and zero filler.

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

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

With no output schema, the description still tells the agent how to paginate (read `next_page_id` from the response) and that the call is billed. Combined with annotations covering safety, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is only 33%, so the description carries real weight: it explains `count` sets page size (default 30) and that `page_id` should be fed the previous response's `next_page_id`. The `secUid` format/length constraints remain schema-only, but the description meaningfully supplements the undocumented params.

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

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

States a specific verb ('List') and resource (TikTok suggested/related accounts) scoped by `secUid`, and explicitly distinguishes itself from the sibling `get_v1_user_suggested_by_username` by identifier type. An agent can select it without opening either schema.

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

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

Gives an explicit condition for use ('when you already have the `secUid` from a profile') and names the alternative tool plus the condition that selects it (only a handle). 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 already declare readOnlyHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: live request to TikTok, billed per call, and the pagination contract (one page per call, next_page_id flows into page_id).

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 tightly packed sentences: purpose first, alternatives second, operational details third. Zero filler, and the distinguishing information is front-loaded.

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

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

With no output schema, the description still conveys the pagination return contract (next_page_id), cost model, and endpoint path. Everything an agent needs to call and chain this tool is present.

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

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

Schema coverage is only 33% (only page_id is described in the schema), so the description must compensate. It clarifies page_id's role via the pagination flow and notes count sets page size with default 30, adding practical meaning beyond the bare integer type.

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

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

States a specific verb and resource ('List the accounts TikTok suggests as related to a user') with the scoping dimension (by username) that separates it from the secUid variant. An agent can distinguish it from get_v1_user_suggested_by_secUid without opening either schema.

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

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

Explicitly routes to alternatives with conditions: use get_v1_user_suggested_by_secUid when you already have the secUid, and get_v2_search for keyword search. This is the when-to-use/when-not guidance done properly.

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

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

Annotations already declare readOnlyHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds context annotations cannot: it is a live, per-call billed request against TikTok, and it discloses the paging contract (next_page_id -> page_id) and that offset is superseded. It stops short of describing result shape or failure/rate-limit 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?

Three compact sentences, each doing distinct work: routing, pagination mechanics, and cost. The disambiguation clause is front-loaded right after the purpose statement.

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

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

For a no-output-schema, read-only search tool, the description covers routing, pagination, and cost — the main things an agent needs. Minor gaps remain on result volume/limits and what a page contains, but nothing blocks 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 coverage is 50%, so the description must carry weight, and it does for the tricky params: it explains the page_id/offset relationship and that offset cannot page alone. `count` (default 20, max 30) is left entirely to the schema with no textual elaboration, 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?

States a specific verb and resource ('Search TikTok by keyword') plus a scope constraint ('one page per call'), and names the sibling resources it is not for (handle, link, id, hashtag). An agent can distinguish it from get_v1_hashtag_info and get_v1_user_by_username without opening either schema.

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

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

Explicit when-to-use ('when you have a topic rather than a handle, link or id') paired with named alternatives for the other cases. It also gives forward guidance on pagination flow and deprecation of `offset`.

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 readOnly/openWorld/non-destructive, and the description adds material context beyond them: 'one page per call', 'Live request to TikTok, billed per call'. Cost and pagination semantics are exactly the kind of thing annotations cannot express.

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

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

Front-loads the resource, then sibling routing, then parameter semantics, then cost/pagination, then the raw endpoint. Every sentence carries distinct information with no filler.

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

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

With no output schema and low schema coverage, the description supplies pagination mechanics and billing, which is what an agent needs to call this safely. Return shape is not described, but the pagination note implies the page structure adequately.

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 only 33% (only secUid is documented in the schema), so the description must compensate — and it does: count = page size, cursor = page-through mechanism, secUid sourced from the profile tool. It omits the count max of 50, 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 specific verb+resource ('List videos a TikTok user has liked') and explicitly distinguishes itself from the sibling get_v2_user_medias_by_secUid. An agent can pick between the two without opening either schema.

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

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

Names the alternative tool and the condition that selects it ('for the user's own videos'), and tells the agent where secUid comes from. No explicit when-not-use guidance beyond the sibling pointer, but the routing 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 readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description adds genuinely new operational context beyond them: it is a live request to TikTok billed per call, and results are paginated one page per call via `max_cursor`. It does not cover rate limits, auth requirements, or quota failure behavior, so it falls short of a 5.

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

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

Three tightly packed sentences, front-loaded with the core action before routing guidance and parameter notes. No filler or repetition of the title, and the trailing endpoint notation is a useful compact reference.

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

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

For a paginated read tool with no output schema, the description covers purpose, routing, pagination mechanics, and cost, with annotations carrying the safety profile. It doesn't characterize the returned video fields, but that is a minor gap for a list endpoint.

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 only 33% (`count` and `max_cursor` have no schema descriptions, `secUid` just says 'User sec_uid'), so the description must compensate. It does: it explains that `secUid` comes from the profile tool, that `count` sets page size, and that `max_cursor` pages through results. It omits the count max of 50 and cursor format details, 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?

Opens with a specific verb+resource and scope: 'List a TikTok user's videos, one page per call.' It explicitly distinguishes itself from the two nearest siblings (`get_v2_user_likes_by_secUid` for liked videos, `get_v1_media_by_id` for a single video), so an agent can route without opening any schema.

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

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

States when to use it ('read an account's content') and names both alternatives with the condition that selects each, including where to obtain the required `secUid` (from the profile tool). Nothing about tool selection is left 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 declare readOnly/openWorld/non-destructive, but the description adds materially new context: it is a live TikTok request, billed at 1 request per call and 2-3 for a restored profile, and the response shape matches the v1 tool. Cost/rate behavior is exactly the kind of trait annotations cannot express. It stops short of describing latency or partial-failure handling, 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?

Three tight sentences, front-loaded with the capability and the sibling routing, then cost and endpoint path. Every sentence carries distinct information with no repetition of the tool name or filler.

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

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

For a single-param read tool with no output schema, the description covers purpose, fallback trigger, cost, and endpoint. The one gap is that 'the response has the same shape' defers the return structure to a sibling rather than stating it, which mildly burdens the agent.

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

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

One parameter with 0% schema description coverage; the schema only supplies min/max length. The description implies a username via the tool name and the GET path, but adds no format, casing, or '@'-prefix guidance beyond what the schema already shows.

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

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

States a specific verb and resource ('Get a TikTok profile by username') and explicitly scopes it against the sibling get_v1_user_by_username, naming the case the v1 tool cannot serve (404 ProfileUnavailable). An agent can distinguish this tool from its nearest sibling without opening either schema.

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

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

Explicitly says 'Use it as the fallback when the v1 tool fails' and names the exact failure condition that selects it. The when-to-use rule and the alternative are both stated, leaving nothing to inference.

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