SocialDataX 抖音 Douyin MCP

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

Annotations declare readOnlyHint=true (read-only) and openWorldHint=true (open-world result set). The description adds beyond this by stating pagination is not supported and it retrieves the 'main' list, suggesting possible sub-lists or limitations. This is valuable behavioral context not present in annotations.

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

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

The description is two short sentences with zero wasted words. The primary purpose is front-loaded, and the pagination limitation is succinctly stated. Every sentence earns its place.

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

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

For a simple tool with no parameters and an output schema, the description is complete. It states the exact action and the only important behavioral constraint (no pagination). Since an output schema exists, no return value explanation is needed.

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?

There are zero parameters, so the description cannot add meaning beyond the schema. Schema coverage is 100% (empty object). Per guidelines, baseline is 4 for no parameters, and the description does not need to provide additional param info. It is adequate.

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 it retrieves the Douyin main hot search list, using specific verb and resource. The name and description align perfectly, and it is distinct from all sibling tools which deal with user info, videos, or search, making selection unambiguous.

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

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

No explicit guidance on when to use this tool versus alternatives is provided. However, the tool is the only one for hot search lists among siblings, and with no parameters, usage is straightforward. Implied usage is clear but lacks explicit when/when-not 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?

The description is consistent with the readOnlyHint annotation and adds some context about not needing to search first, but does not disclose additional behavioral traits such as rate limits or error conditions. The annotation already covers read-only safety, so this is adequate but not exceptional.

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 compact and front-loaded with the main purpose, and every additional sentence provides actionable guidance without fluff.

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 that an output schema exists, the description sufficiently covers input requirements and decision logic, making it complete for an agent to invoke correctly.

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

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

The parameter description is highly detailed: it specifies that a full product ID should be used as-is, can be copied from search results, and explicitly excludes sku_id, links, and search terms. This goes well beyond the basic 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 states the action (读取/read) and the resource (抖音商品详情/product details), and distinguishes it from the URL-based alternative by explicitly telling when to use 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?

Provides explicit when-to-use instructions: use directly when a full product ID is available, fall back to search_products if not, and use the by_url variant for links or share text. This fully eliminates ambiguity.

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 states the tool reads product details, consistent with the readOnlyHint annotation. However, it does not add additional behavioral context such as side effects, rate limits, or error conditions beyond what the annotation already implies.

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 concise and well-structured, with a single clear sentence conveying the purpose and usage condition. The parameter description adds essential detail without redundancy.

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

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

The tool is simple with a single parameter, and the description fully covers its purpose and input constraints. Given the presence of an output schema, no further explanation of return values is necessary.

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 parameter description is highly informative, detailing the accepted URL types (short link, product page link, or shared copy containing the link) and explicitly excluding product_id, sku_id, and search terms. This goes far beyond the basic 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 explicitly states the tool reads product details based on a Douyin product link or shared copy. It also distinguishes itself from other tools by specifying this entry is for link-type inputs only, which clearly differentiates it from the product_id variant.

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 and parameter description provide explicit when-to-use guidance: use this tool only when the input is a link, and avoid passing product_id, sku_id, or search terms. This clearly routes the agent to the correct tool among siblings.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds no additional behavioral detail such as data freshness, rate limits, or failure behavior, but it does not contradict 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?

One short sentence with no filler; the essential identifier constraint is front-loaded and the schema adds the negative examples. Every word earns its place.

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

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

For a one-parameter read-only lookup with an output schema and safety annotations, the description is nearly complete. It misses only an explicit pointer to the alternate-identifier sibling tools, but that is not essential for making a correct call.

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

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

The schema already covers 100% of the single parameter, including its format and exclusions, so the description adds no new parameter semantics. 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 action ('获取用户资料' – get user profile) and a precise resource keyed by the homepage-displayed douyin_id. This distinguishes it from sibling tools that use profile_url or sec_user_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?

The description implies when to use the tool – when you have the douyin_id shown on the user's homepage – but it never names alternatives such as douyin_get_user_info_by_sec_user_id or douyin_get_user_info_by_profile_url. The schema's 'do not pass' list helps, but the description itself provides no explicit when-not-to-use guidance.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true, which already communicate that this is a safe, read-only operation. The description adds no additional behavioral context beyond stating it retrieves user info, so it does not exceed what annotations provide but also does not contradict them.

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

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

The description is a single, concise sentence that states the action and input types without any unnecessary words. It is front-loaded and efficiently conveys the core purpose.

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

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

Given the tool's simplicity (one parameter), the presence of an output schema, and annotations covering read-only behavior, the description is adequate. It does not explain return format or error conditions, but these are covered by the output schema and the tool's low complexity.

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 single parameter 'profile_url' has 100% schema description coverage, including details on accepted formats, exclusions, and a recommendation to prefer the ID entry. The description itself adds nothing 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?

The description clearly states the tool's purpose: to retrieve user profile data based on a Douyin profile URL, specifying accepted formats (long link, short link, share text). It distinguishes itself from sibling ID-based tools by focusing on URL input, making its function unambiguous.

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 itself provides no explicit guidance on when to use this tool versus alternatives. However, the schema parameter description includes clear instructions: do not pass video links and prefer the ID entry when sec_user_id is known. This guidance is present in the schema but not in the description, so the description alone is lacking.

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 openWorldHint=true, so the agent knows this is a safe read operation. The description adds the behavioral note that sec_user_id is an opaque identifier and that the actual field value should be reused from results, which is useful. However, it doesn't describe output shape or any rate-limit/error behavior, but with annotations covering safety, a 3 is appropriate.

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

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

The description is a single sentence that front-loads the core purpose and then adds the key usage preference. The parameter description is also concise and dense with actionable guidance. No wasted words.

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

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

For a single-parameter read tool with a rich schema description and output schema present, the description is nearly complete. It covers what the tool does, when to use it, and how to supply the parameter correctly. The only minor gap is not explicitly naming sibling alternatives, but the guidance is sufficient for an agent to select correctly.

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

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

Schema description coverage is 100%, so the schema already documents the parameter. The description adds meaningful semantics beyond the schema: it clarifies that sec_user_id is opaque, instructs to pass the actual field value from results, and explicitly warns against passing douyin_id, field names, or placeholder text. This goes beyond the schema's basic description.

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

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

The description states a specific verb and resource: '根据抖音用户 sec_user_id 获取用户资料' (get user profile by sec_user_id). It also adds a usage preference ('已知 sec_user_id 时优先使用此入口'), which helps distinguish it from sibling tools like douyin_get_user_info_by_douyin_id and douyin_get_user_info_by_profile_url. However, it doesn't explicitly name those alternatives, so it's clear but not fully differentiated.

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

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

The description gives clear context: use this entry when sec_user_id is already known. The parameter description adds an explicit exclusion: don't pass douyin_id, field names, or placeholder text, and use profile_url entry when only a profile link is available. This is strong guidance, though it doesn't explicitly name the sibling tools for those alternatives.

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, so the safety profile is covered. The description adds pagination support, but that behavior is also visible in the page_token schema, so the incremental disclosure beyond annotations is modest. There is no contradiction with annotations.

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

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

One sentence with no wasted words: it front-loads the purpose and input forms, then mentions pagination. Nothing is redundant with the schema, and it is appropriately sized for a simple two-parameter tool.

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

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

For a read-only, two-parameter tool with an output schema, the description plus rich parameter schema covers input variants, pagination contract, and safety profile. It is complete enough, though alternative routing relies on parameter-level guidance rather than the top-level 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%; page_token is extensively documented and profile_url enumerates valid input types and forbidden inputs. The tool description itself adds little parameter-level meaning, which is acceptable under the high-coverage baseline.

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

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

The description states a concrete verb ('获取'), a specific resource ('用户发布的作品列表'), and the accepted input forms (long/short profile links or share text). This makes the tool's purpose clear and distinguishable from siblings that fetch user info, series, or use a sec_user_id entry point.

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 main text makes clear this tool is for profile-URL-based access. The profile_url parameter description adds explicit exclusions ('不要传作品链接') and an alternative ('已知 sec_user_id 时优先使用 ID 入口'), which helps an agent choose between this tool and the sec_user_id-based sibling.

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 openWorldHint=true, covering safety. The description adds that pagination is supported, which is beyond annotations, but provides no further behavioral details such as rate limits or error handling. This adds modest value.

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

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

The description is a single concise sentence that front-loads the core action and includes the pagination capability. There is no unnecessary verbiage.

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

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

For a simple paginated list tool, the description covers the essential function. An output schema exists, so return values are defined. It doesn't mention error cases or usage constraints, but these are not critical given the low complexity and annotations.

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% with detailed descriptions for both parameters. The description only restates that sec_user_id identifies the user and page_token enables pagination, adding little 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 states a specific action (获取作品列表 = get video list) on a specific resource (user by sec_user_id) and mentions pagination. It clearly distinguishes from the profile_url sibling by the identifier used, making the purpose unambiguous.

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 mentions pagination support but does not explicitly state when to use this tool versus the profile_url variant or any exclusion criteria. The identifier difference is implicit, but no direct guidance is given.

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

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

Annotations already disclose readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds that page_token pagination is supported, a behavioral detail not in the annotations, giving agents useful context for iterating through results.

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

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

The description is a single sentence that states the resource, input variants, and pagination capability with no redundancy. It is properly front-loaded and 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?

The output schema exists and the input schema fully documents both parameters, so the description only needs to convey the tool's purpose and main behavior. It does so adequately; a minor gap is not mentioning the sec_user_id alternative explicitly in the description, though the schema instructions cover it.

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

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

With 100% schema description coverage, the parameter meanings are already fully documented. The main description only reiterates the profile URL formats and pagination without adding new semantic detail, matching the baseline for high coverage.

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

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

The description clearly states the tool retrieves a user's short drama/series list (用户短剧列表) from a Douyin profile URL, specifying long link, short link, or share text as inputs. It does not explicitly contrast with the sec_user_id-based sibling tool, so differentiation is implicit through the input type.

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

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

The description provides no direct guidance on when to use this tool versus alternatives such as douyin_get_user_series_by_sec_user_id. It only lists accepted input types and pagination support, without any conditions, exclusions, or references to sibling tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds the specific behavioral detail that pagination is supported via page_token, which is not in the annotations. It does not contradict the annotations and provides useful operational context for the agent.

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

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

The description is a single concise sentence that front-loads the resource and input, and includes the pagination key point. There is zero filler or repetition, making it efficient and easy to parse.

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

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

Given the high schema coverage, an output schema, and read-only annotations, the description is largely sufficient for an agent to invoke the tool correctly. It does not explain the distinction from the profile_url sibling, but that is not necessary for calling this tool correctly. The missing guidance on when to choose sec_user_id vs profile_url is a minor gap but not a blocker.

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

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

Schema description coverage is 100%, with both sec_user_id and page_token having detailed descriptions in the schema. The tool description simply restates the main input and pagination support without adding any new meaning beyond what the schema already provides. Thus 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?

The description clearly states the verb '获取' (get) and the specific resource '该用户短剧列表' (the user's short drama series list), with the input being sec_user_id. It distinguishes from sibling tools like douyin_get_user_posted_videos_by_sec_user_id and douyin_get_user_info_by_sec_user_id by naming the series list explicitly, and the name already disambiguates from the profile_url variant.

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 does not explicitly state when to use this tool versus alternatives. It implies usage via the sec_user_id input, but there is no mention of the sibling tool douyin_get_user_series_by_profile_url or guidance on when to prefer one entry point over the other. The pagination note is helpful but does not address selection criteria.

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?

readOnlyHint=true already covers the safety profile, and the description adds useful behavioral constraints: both IDs must be supplied together and belong to the same video, reply-level comment_ids must not be passed, and page_token pagination is supported. No mutation or side-effect disclosure is needed given the read-only annotation.

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 dense single sentence with semicolon-separated guidance, but every clause conveys essential information: core operation, required pairing, fallback path, user interaction, and pagination. It is compact enough for the amount of workflow guidance provided.

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

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

For a read-only paginated lookup tool, the description covers the exact callable precondition, the alternate resolution path, the negative case (reply's own comment_id), and pagination. With an output schema present, no return-format explanation is needed.

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

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

The schema already documents all three parameters at 100% coverage, so the baseline applies. The description reinforces important constraints (same-video ownership, not using reply IDs) but adds little parameter-level meaning beyond what the schema property descriptions already contain.

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

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

The description states the specific operation ('获取抖音评论回复') scoped to a first-level comment_id plus aweme_id, which clearly distinguishes this from siblings like douyin_get_video_comments_by_aweme_id (first-level comments) and URL-based variants. The required ID combination is explicit.

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 defines when to call directly (complete valid combination provided), when to fall back to a first-level comment tool to obtain missing IDs, and when to ask the user for missing video-locating information. It also warns not to pass reply-item comment_ids, giving the agent actionable selection and exclusion rules.

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 openWorldHint=true, so the read-only nature is covered. The description adds behavioral context beyond annotations by specifying that only top-level comments are returned and that page_token pagination is supported. It does not mention rate limits or error behavior, but these are secondary for a simple read operation.

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

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

The description is a single, focused sentence that front-loads the primary action and resource, then states the pagination capability. There is no filler, repetition, or unnecessary detail, making it easy to scan.

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

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

For a two-parameter read-only tool with a full output schema and annotations covering read-only/open-world behavior, the description is complete. It states the core function, the identifier, and pagination support, which is all an agent needs to correctly invoke and page through results.

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 no parameter-level meaning beyond the schema; it merely restates that pagination is supported, which the page_token schema description already explains in greater 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 uses a specific verb (获取/get), names the resource (一级评论列表/top-level comment list), and specifies the key identifier (aweme_id). It clearly differentiates from siblings by stating it fetches top-level comments by aweme_id, as opposed to by URL or replies by comment_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?

No explicit when-to-use or when-not-to-use guidance is provided, nor are alternatives named. The intended context is implied through the resource and identifier, but the description does not state exclusions or direct an agent to sibling tools when appropriate.

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

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

Annotations already indicate readOnlyHint and openWorldHint, so no mutation risk needs explanation. The description adds value by clarifying that only first-level comments are returned and that page_token pagination is supported, which are behavioral traits not captured by the annotations.

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

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

The description is a single front-loaded sentence that communicates the core purpose and pagination capability with no filler. Every word is informative, and detailed parameter nuances are appropriately left to the schema.

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

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

For a two-parameter read-only tool with an output schema present, the description plus detailed schema fully covers what an agent needs: accepted URL forms, pagination semantics, and the top-level comment scope. Return-value details are already handled by the output 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 fully documents both parameters. The description's reference to supported link formats and pagination aligns with the schema but does not add substantial meaning beyond it, matching the baseline of 3.

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

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

The description states a specific verb ('获取'/'get'), resource ('一级评论列表'/'first-level comment list'), and input method (video URL/short link/share text). It distinguishes from sibling tools by making the top-level scope explicit and by noting the URL-based entry point, which contrasts with the aweme_id-based sibling.

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

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

The description and url schema condition together give explicit usage guidance: accept video page URLs, short links, or share text; explicitly exclude video.play_url playback URLs and user profile links; and recommend the aweme_id entry when the ID is known. This clearly routes the agent to the correct input mode and sibling tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the tool handles both video and image-text works, which is minor useful context, but it does not disclose additional behavioral details such as pagination, response shape, or failure modes. With annotations carrying the main burden, a 3 is appropriate.

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

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

A single, well-structured sentence that front-loads the core purpose and ends with a clear usage preference. There is no filler or redundancy, and 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?

The tool is simple with one documented parameter, annotations cover read-only behavior, and an output schema exists to describe return values. The description provides the key routing decision and parameter guidance, leaving no critical information missing for an agent to call it correctly.

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

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

Schema coverage is 100%, so the parameter is documented structurally. The description goes beyond this by warning against passing links, share text, or quoted strings, and by explaining that aweme_id can be reused from search/detail/comment results. This practical guidance meaningfully helps the agent invoke the tool correctly.

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

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

The description clearly states the verb '获取' (get), the resource (抖音作品详情 via aweme_id), and the scope (视频或图文作品). It also differentiates itself from the sibling douyin_get_video_detail_by_url by specifying the key-based entry, so an agent can distinguish it 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?

The phrase '已知 aweme_id 时优先使用此入口' explicitly tells the agent when to use this tool: when the aweme_id is already known. It implies the by-url sibling should be used otherwise, though it does not name the alternative explicitly. This is clear context without exclusions.

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

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

Annotations already mark the tool as read-only and open-world; the description adds useful behavior context by stating that it resolves short links and parses share copy containing a link. No side effects or hidden mutations are implied, and the read-only annotation is consistent.

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 one focused sentence that states the input forms and expected output with no filler. The critical exclusions and ID-preference guidance are placed in the parameter description rather than bloating the main description.

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

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

For a single-parameter, read-only lookup with an output schema and explicit usage constraints, the definition is complete. It covers input variants, exclusions, alternative entry point, and expected result type, leaving no essential decision unresolved.

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 url parameter is already richly documented with accepted forms and exclusions, so the main description adds little beyond the structured schema. The tool's single parameter is fully specified, satisfying the baseline.

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

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

The description uses a concrete verb ('获取') and names the exact resource: video or image-text work details. It also lists accepted URL forms, which clearly distinguishes the URL-based entry from sibling tools like douyin_get_video_detail_by_aweme_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?

The definition explicitly says to use this tool when you have a work URL, short link, or share text, and directs agents to prefer the ID entry when an aweme_id is already known. It also gives a when-not-to-use rule by excluding user profile links and media URLs such as video.play_url.

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

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

Annotations already provide readOnlyHint and openWorldHint, and the description adds that the output is a short link plus copyable share text and that no prior search/detail call is needed. It does not go into failure modes or rate limits, but for a read-only generation tool the added context is sufficient.

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

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

Two sentences with the primary action first and no filler. Every clause earns its place, and the routing guidance is compactly included.

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

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

The tool is simple (one required parameter), has an output schema, and carries safety annotations. The description plus schema is enough for an agent to invoke it correctly; the by_url sibling is inferable from the tool name and the instruction not to pass links.

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

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

Schema coverage is 100% and the aweme_id parameter description already explains the expected format, reuse source, and exclusions. The tool description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description uses a specific verb ('生成') and resource ('抖音分享短链接和可复制的完整分享文案') and clearly scopes the operation to aweme_id input. This distinguishes it from siblings like douyin_get_video_share_link_by_url and the detail tools.

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

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

It explicitly states when to use the tool ('用户已提供 aweme_id 时直接使用') and what not to do first ('无需先搜索或读取详情'). It also points to the detail tool as the alternative for reading content, and the parameter schema adds the when-not of passing links.

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

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

Annotations already mark the tool as readOnlyHint, and the description does not contradict this. It adds useful behavioral context by clarifying that the tool converts URLs into share links and share text rather than fetching content, and it warns against invalid URL types.

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 compact and front-loaded, leading with the core function and output, then immediately providing routing guidance. Every sentence earns its place, and no redundant filler is present.

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

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

Given the single parameter, fully detailed schema, output schema presence, and safety annotations, the description covers all needed operational context. It explains accepted inputs, rejected inputs, the alternative ID-based entry, and the boundary with content-reading tools.

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

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

Schema description coverage is 100%, and the schema already fully explains the accepted URL forms and exclusions. The tool description repeats some of this but does not add significant new meaning beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description names a specific verb ('生成') and resource (抖音分享短链接和完整分享文案), and clearly distinguishes this URL-entry tool from the aweme_id entry point. It also differentiates from detail/content-reading tools by explicitly routing content reads elsewhere.

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

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

The description explicitly states when to use the ID entry instead ('已知 aweme_id 时使用 ID 入口') and when to use the detail tool for content ('读取作品内容请使用详情工具'). The schema description adds clear negative constraints, such as not passing play resource links or user profile links.

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 openWorldHint=true. The description adds valuable behavioral details: maximum 240-second wait per call and that it does not trigger reprocessing. This goes beyond the annotations and informs the agent of polling behavior and side-effect-free nature.

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

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

The description is a single sentence but packs in the purpose, usage context, and key constraints. It is front-loaded with the core action and avoids redundancy. Could be split for readability but is efficient overall.

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 presence of an output schema and the simplicity of a status-polling tool, the description covers what the tool does, when to use it, and key behavioral limits. No critical missing information for correct invocation, though it omits any note about invalid job_id handling, which is minor given the schema guidance.

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 job_id parameter is already fully explained in the schema (use user-provided or submit tool's job_id, not aweme_id or links). The description repeats this but adds no new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool queries the status of a Douyin video speech-to-text task, with specific verb '查询' and resource '任务状态'. This distinguishes it from sibling tools like user info or video detail fetchers, and from the submit tools that create the task.

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 instructs to use a valid job_id from the user or the submit tool, and explicitly says to use it for continuing unfinished tasks. It also warns against resubmitting tasks, which guides the agent toward correct workflow integration with the submit siblings.

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 readOnlyHint annotation, the description discloses key behavioral aspects: it returns a 'normalized product list' and an 'opaque pagination token', and warns that it does not represent a complete search chain within the mall channel. It could be more explicit about rate limits or data freshness, but it gives sufficient behavioral context for an agent to set expectations.

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

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

The description is concise, using only two sentences. It front-loads the core purpose, then summarizes filter capabilities and returns, and concludes with guidance and limitations. No redundant or filler content; every sentence serves a purpose.

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 complexity of 11 parameters and the presence of an output schema, the description provides sufficient context: it summarizes the filter dimensions, mentions the opaque pagination token (which is further detailed in the schema), and gives explicit alternatives for detail retrieval. It also notes the limitation of not being a complete mall search, addressing potential edge cases. The output schema covers return value details, so none are needed 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?

With 100% schema coverage, the baseline is 3. The description adds meaning by grouping parameter categories (sorting, price, service, selling point) and by clarifying the relationship between search and detail tools, which helps an agent understand when to use which parameters. However, it does not introduce new parameter-specific details beyond the schema, so a 4 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 clearly states the primary action ('搜索商品' by keyword) and identifies the resource (Douyin products). It explicitly differentiates from sibling tools by noting it is not for searching videos or users, and directs users to detail tools when a product_id or URL is already available, making its purpose unambiguous.

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 explicit usage guidance: when to use this search tool versus the detail tools (douyin_get_product_detail_by_product_id and douyin_get_product_detail_by_url) based on whether product_id or link/share text is available. It also states exclusions (not for videos/users) and a limitation (not a complete mall channel search chain), giving an agent clear decision rules.

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 openWorldHint=true, covering the safety profile. The description adds the scope restriction that this is only for suggestions and not general search, but does not add much behavioral context beyond the annotation-provided read-only signal. No contradiction exists.

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 one concise sentence that front-loads the core purpose and immediately provides essential exclusions. Every part earns its place with no wasted wording.

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

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

The tool has one well-documented parameter, an output schema, and annotations covering read-only behavior. The description supplies the necessary scope and usage guidance, making it complete for an agent to select 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 description coverage is 100%, and the schema already explains the keyword parameter and warns against passing links, IDs, or page_token. The description repeats some of this guidance but does not add significant new 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?

The description uses a specific verb ('获取') and a specific resource ('普通搜索输入框联想词'), clearly stating what the tool returns. It also explicitly excludes searching for works, users, or products, which differentiates it from the sibling search tools.

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

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

The description clearly states when to use the tool: to get search-suggestion words for Douyin's normal search box. It also gives explicit when-not-to-use guidance by ruling out searching videos, users, and products, and instructs not to pass page_token.

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 openWorldHint=trueebt, and the description adds behavioral context beyond those: it supports page_token pagination and clarifies the semantic boundary of the search. It does not contradict any annotation, and the output schema covers return-value expectations.

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

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

The description is compact and front-loaded: it states the core capability first, then pagination, then usage boundaries and alternatives. Every sentence adds useful routing or scoping information without redundancy.

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

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

With a full input schema, an output schema, and clear annotations, the description completes the picture by adding search intent, pagination behavior, and sibling-tool routing. No critical information needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema alone fully documents keyword, user_type, page_token, and follower_count_range. The description reinforces search scope and pagination, but does not materially add meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: search Douyin users, accounts, bloggers, creators, and talents. It also differentiates from sibling tools by explicitly noting that profile or list tools should be used when sec_user_id or profile URL is already available, and that this tool is not for searching works.

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 explicit when-to-use guidance: use when the user needs to find users by search term. It also gives explicit when-not-to-use guidance and names alternatives: use profile/list tools if sec_user_id or profile URL is available, and do not use for searching works.

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 the tool as read-only and open-world, so the description adds value by noting that results may include both video and image content and that page_token pagination is supported. This enriches the behavioral picture beyond the structured fields, though it does not go into rate limits or result-set nuances.

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 compact and front-loaded with the core purpose and use case. Every sentence earns its place: usage trigger, alternative routing, content-type nuance, and pagination support are all covered without redundancy.

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

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

Given the rich schema descriptions, annotations, and presence of an output schema, the description provides all necessary decision-making context. It covers the main selection criterion, alternative tool routing, and pagination behavior, so nothing critical is missing 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%, and the schema itself provides thorough per-parameter explanations, especially for sort_type and page_token. The tool description does not add substantial parameter meaning beyond the structured schema, which fits the baseline-3 case.

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 begins with a specific verb-resource pair ('搜索抖音视频和图文作品') and clearly identifies the tool as the keyword-driven search entry point. It explicitly distinguishes itself from detail, comment, and speech-to-text tools, making it easy for an agent to select this over 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?

It states the primary use case ('按搜索词查找作品时使用') and explicitly excludes cases where a link or aweme_id is already available, directing the agent to detail or transcript tools. This gives clear when-to-use and when-not-to-use guidance with named alternatives.

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?

注解没有提供异步等待或返回 job_id 的信息，描述补充了“最多等待 240 秒”和“未完成时返回 job_id 和下一步查询动作”，这增加了对异步行为的透明度和后续调用的指导，且与注解（readOnlyHint=false）无矛盾。

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?

描述仅一句话，直接说明了核心动作和关键行为，没有冗余信息，信息密度高且易于理解。

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?

工具是异步提交任务，有输出 schema（可能包含 job_id 等），描述提供了必要的等待时间和返回内容，足以让 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?

唯一的参数 aweme_id 在 schema 中已有详细说明（包括来源和排除项），描述本身没有额外补充参数语义，schema 覆盖 100%，基线为 3 是合适的。

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

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

描述明确说“根据抖音 aweme_id 提交视频口播转文字任务”，动词“提交”和资源“视频口播转文字任务”都很具体，且和兄弟工具 `douyin_submit_video_speech_text_by_video_url` 在用途上形成清晰区分（按 ID 提交 vs 按 URL 提交）。

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?

描述了提交后的行为（等待 240 秒、返回 job_id 和下一步查询动作），间接暗示了后续应使用 `douyin_get_video_speech_text_job` 查询状态，但没有明确说“当你有 aweme_id 时使用此工具，而不是按 URL 提交”，不过名字已经足够区分，用户只需根据输入类型选择。

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 indicate readOnlyHint=false and idempotentHint=false, confirming a non-idempotent mutation. The description adds specific behavioral context: it waits up to 240 seconds and returns a job reference if incomplete, which is useful for an agent deciding whether to call this synchronously or poll later. No contradiction with annotations.

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

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

The description is a single, well-structured sentence that front-loads the primary action and then clearly states the wait/timeout behavior. Every part adds value and there is no redundancy 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?

The tool has an output schema, so return values do not need to be explained. The description covers the essential flow (submit, wait, get job_id if not done) and implicitly communicates asynchronous behavior. It does not explicitly mention what happens on immediate completion, but that is left to the output schema. Overall, it is sufficiently complete for an agent to invoke correctly.

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

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

There is only one parameter (video_url) and its schema description is highly detailed (100% coverage), specifying acceptable URL forms and exclusions. The tool description adds no additional parameter meaning beyond what the schema already provides, 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?

The description states a specific verb ('提交' meaning submit), a concrete resource (video speech-to-text task), and explains the follow-up behavior (wait up to 240 seconds, return job_id if incomplete). It clearly distinguishes this submission tool from query tools like douyin_get_video_speech_text_job.

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 mentions waiting and returning job_id with a next query action, which implies using a query tool, but it does not explicitly differentiate when to use this URL-based submission vs the aweme_id-based alternative (douyin_submit_video_speech_text_by_aweme_id). The parameter schema separately recommends the ID entry, but that is not in the tool description. Guidance is implied but not explicit.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces that this is a read-only balance query. It adds useful context by tying the balance to the current API Key and pointing to the billing dashboard for recharges. No contradictions or hidden side effects are indicated.

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

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

The description is two short sentences: the first states the core purpose, and the second provides an actionable billing link. Every word earns its place without unnecessary detail.

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

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

For a zero-parameter, read-only balance query with an output schema, annotations, and a billing link, the description is fully sufficient. No additional information is needed for an agent to select and 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?

The tool has zero parameters Belarusand schema coverage is 100%, so parameter semantics are not a burden on the description. The description still adds value by explaining what the returned balance represents.

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 a specific action (query) and resource (current API Key account's SocialDataX points balance), including Chinese and English terms. It is unambiguous and obviously distinct from the YouTube-focused sibling tools.

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

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

The description identifies the exact context: querying the balance for the current API Key accounttons. It also provides a relevant follow-up URL for recharging. There are no competing sibling tools for balance checking, so no explicit alternatives are needed.

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