SocialDataX 抖音 Douyin MCP

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

Annotations already indicate readOnlyHint=true, so the read-only nature is covered. The description adds that pagination is not supported, which is a useful behavioral detail beyond 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 short, front-loaded sentences with no unnecessary words. Every sentence adds value: the first defines purpose, the second notes a key limitation.

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

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

Given no parameters and the presence of an output schema, the description fully covers what the tool does and its pagination limitation. No gaps remain.

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

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

There are no parameters, and schema coverage is 100%. The description adds nothing about parameters, but none are needed. Baseline score of 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 tool retrieves the Douyin main hot list. It adds the limitation of no pagination support, which enhances clarity. However, it does not explicitly distinguish it from sibling tools, though the name alone suffices.

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

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

No guidance on when to use this tool versus alternatives like search-based tools. The description only notes a limitation (no pagination) but does not provide context for selection.

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. The description adds no further behavioral context (e.g., no mention of rate limits, authorization, or error behavior). It is consistent but does not add value beyond annotations.

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

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

The description is a single, concise sentence that front-loads the purpose. Every word is necessary and no extraneous information is 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?

Given the tool's simplicity (one parameter, output schema exists, annotations present), the description is adequate. It tells what it does and the input type. Minor improvement could include noting the output type, but it's not necessary due to 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 coverage is 100%, and the parameter description already specifies acceptable link types and warns against video links. The tool description does not add additional meaning beyond the schema's parameter description, so baseline 3 applies.

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

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

Description clearly states it gets user profile based on Douyin homepage long link, short link, or shared copy. The verb 'get' and resource 'user info' are specific, and it distinguishes from sibling tools that use 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 main description does not explicitly state when to use this tool versus alternatives. However, the parameter description hints to prefer the ID entry when sec_user_id is known, providing implicit guidance. But it's not explicit in the tool description.

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 description adds no new behavioral context. While the safety profile is covered, the description does not elaborate on any additional behavioral traits beyond the annotations.

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

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

The description is a single, concise sentence that conveys the purpose and usage guidance with no wasted words.

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

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

Given the presence of an output schema (not shown but indicated) and the tool's simplicity (single parameter), the description is complete enough. It covers purpose and usage, and the output schema handles return values.

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

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

Schema coverage is 100%, but the description adds value by explaining the parameter can be reused from other contexts (author.sec_user_id or previous results), which aids understanding beyond the schema's description.

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

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

The description clearly states the tool retrieves user info based on sec_user_id, and explicitly distinguishes from sibling tool douyin_get_user_info_by_profile_url by advising to prioritize this entry when sec_user_id is known.

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

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

The description provides explicit guidance: when sec_user_id is known, prefer this tool, implying alternatives for other identifiers. This effectively differentiates from 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, indicating no destructive actions. The description adds value by explicitly stating pagination support via `page_token`, which helps the agent understand the iterative data retrieval behavior. No behavioral contradictions 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 sentence that efficiently conveys the tool's purpose and key feature (pagination). No unnecessary words. All information is front-loaded and relevant.

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 has only 2 parameters and a clear output schema (not shown but known to exist), the description is sufficiently complete. It covers the core function and pagination. It does not mention error handling or invalid URL behavior, but those are less critical when output schema is present and annotations indicate read-only safety.

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 tool description does not add any extra meaning beyond the schema's parameter descriptions. The parameter `page_token` and `profile_url` are adequately described in the schema, and the description restates only high-level functionality without enriching parameter semantics.

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

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

The description clearly states that the tool retrieves the list of posted videos by a user using their profile URL (long link, short link, or share text). The verb '获取' (get) and resource '用户发布的作品列表' (list of user's posted works) are specific. The description implicitly differentiates from siblings like douyin_get_user_posted_videos_by_sec_user_id by specifying the input as a profile URL rather than a 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 main description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, when to choose this over the sec_user_id version, or what types of URLs are valid. The only usage hint is in the parameter description of `profile_url` ('已知 sec_user_id 时优先使用 ID 入口'), which is not part of the tool description itself.

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

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

Annotations already declare readOnlyHint=true, so the description's '获取' is consistent. It adds pagination behavior ('支持 page_token 翻页'), which is not covered by annotations. No contradictions and adds useful context.

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 sentence containing the essential information (what it does and pagination support). No superfluous content; it is efficiently front-loaded.

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

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

Given that an output schema exists, the description need not detail return values. It covers the core functionality and pagination, which is sufficient for a read-only list tool. However, it lacks mention of potential rate limits or error scenarios.

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, especially page_token. The main description does not repeat these details, but the schema itself provides sufficient semantics. 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 action ('获取' / get) and resource ('作品列表' / list of videos) and specifies the input 'sec_user_id', distinguishing it from siblings that use 'profile_url'. It is specific and 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 implies usage when the user has a sec_user_id and mentions pagination, but does not explicitly guide when to use this tool over alternatives like the profile_url variants. No exclusions or when-not conditions are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows it's read-only and results may vary. The description adds pagination behavior, but no further behavioral traits beyond what annotations and schema provide.

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

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

The description is a single sentence that clearly states the action, resource, and pagination support. It is front-loaded and efficient, with no wasted words.

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

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

Given the simple tool (2 parameters, read-only, has output schema), the description provides sufficient context: what it does, input type, and pagination. The output is covered by the output schema, so no further details are 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?

Schema description coverage is 100%, so the schema already documents both parameters with thorough details. The description adds no extra meaning beyond summarizing the input type, which is already clear 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?

Description explicitly states the verb (获取/get), resource (用户短剧列表/user series list), and input type (profile URL or share text) with pagination support. It differentiates from sibling tools like douyin_get_user_posted_videos_by_profile_url by specifying 'short drama list'.

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 indicates when to use (with profile URL or share text). Additionally, the parameter description for profile_url advises preferring the ID entry when sec_user_id is known, providing indirect guidance on alternatives. However, explicit when-not or contraindications are absent.

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=true (safe read) and openWorldHint=true (dynamic results). The description adds pagination behavior, which is useful, but does not disclose further traits like rate limits or potential empty results. 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, focused sentence that front-loads the core purpose and includes pagination support. Every word adds value, with no redundancy or 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?

Given the tool's simplicity (2 parameters, no nested objects, output schema exists) and high schema coverage, the description adequately covers the primary functionality and pagination. It could be slightly enhanced by noting the return format, but output schema likely handles that.

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

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

Schema descriptions cover both parameters (sec_user_id source and page_token constraints) at 100% coverage. The tool-level description does not add significant semantics beyond the schema's own descriptions, 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 verb '获取' (retrieve), the specific resource '用户短剧列表' (user series list), and the required input 'sec_user_id'. It also mentions pagination support. This differentiates it from siblings like douyin_get_user_info_by_sec_user_id or douyin_get_user_posted_videos_by_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 usage for getting a user's series by sec_user_id, but it does not explicitly state when to use this tool versus the alternative by profile URL (e.g., douyin_get_user_series_by_profile_url). No exclusion criteria or prerequisites are provided.

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

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

The annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds behavioral details: it requires both aweme_id and comment_id simultaneously, supports pagination, and provides specific rules for page_token usage (must be opaque, not modifiable). This goes beyond annotations, though it could mention rate limits or error conditions.

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 in Chinese that front-loads the core purpose and key requirements. Every word contributes meaning; there is no redundant or extraneous text.

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

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

Given the tool has 3 parameters (2 required), 100% schema coverage, and an output schema, the description covers the essential input constraints and pagination. It could be enhanced by clarifying that replies are scoped to a single top-level comment, but overall it is adequate 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%, with detailed parameter descriptions for aweme_id, comment_id, and page_token (including token handling rules). The top-level description reiterates the requirement for both IDs and pagination support, adding marginal value beyond what the schema already 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?

The description clearly states the action (获取/Get), resource (抖音评论回复/Douyin comment replies), and the required input combination (aweme_id + comment_id). It distinguishes from sibling tools like douyin_get_video_comments_by_aweme_id by specifying it retrieves replies to a top-level comment, not the comments themselves.

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 this tool: when you have both aweme_id and comment_id and need replies. It implies pagination support via page_token. However, it does not explicitly contrast with alternatives or state when not to use it, though sibling tool names provide 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 already declare readOnlyHint=true and openWorldHint=true. The description adds pagination behavior but does not disclose rate limits, authentication needs, or error handling beyond the schema. It does not contradict 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?

A single sentence that front-loads the core purpose (get comments by aweme_id) and mentions pagination. No unnecessary words, but could benefit from slight expansion on usage context.

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

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

For a simple read-only tool with 2 params and output schema present, the description is mostly complete. It covers the primary function and pagination. However, it does not specify output format or error conditions, though the output schema may cover that.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema; it briefly mentions pagination but the schema already describes page_token in detail. No extra semantic value provided.

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 top-level comments using aweme_id with pagination support. It specifies the resource (comments) and identifier (aweme_id), distinguishing it from siblings like 'douyin_get_video_comment_replies_by_comment_id' (replies) and 'douyin_get_video_comments_by_url' (URL-based).

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

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

The description implies usage when aweme_id is available but does not explicitly guide when to prefer this tool over siblings. No when-not-to-use or alternative selection criteria are provided, relying on the tool name and context signals.

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. Description adds transparency about pagination behavior and input format constraints, but doesn't disclose any potential failure modes or rate limits. No contradictions 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?

Single sentence delivers all key info (input types, pagination support, usage hint) without extraneous words. Information is front-loaded 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?

For a simple 2-param tool with output schema present, the description covers all necessary information: input formats, pagination mechanism, and a usage tip. No gaps remain.

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

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

Schema coverage is 100%, but description adds crucial context beyond schema: for 'url', it specifies what not to pass and when to use ID entry; for 'page_token', it details the opaque nature and rules for reuse. This significantly aids correct usage.

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?

Description uses specific verb '获取' and resource '一级评论列表', and clearly differentiates from sibling 'douyin_get_video_comments_by_aweme_id' by noting to prefer ID entry when aweme_id is known.

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?

Description explicitly states the input types (URL, short link, share text) and gives a when-not guidance to not use for user profile links or play URLs. It also suggests using the ID-based tool when aweme_id is known, though it does not list all sibling 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 label this as read-only (readOnlyHint=true) and open-world (openWorldHint=true). The description adds no further behavioral details beyond stating it fetches details. It does not contradict annotations, but it offers minimal additional transparency.

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 consists of two short, front-loaded sentences with no extraneous words. Every word serves a purpose, clearly stating the function and providing a usage preference.

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 (not shown but indicated) and annotations that cover behavior, the description is sufficient for a simple lookup tool. It could briefly mention what kind of detail is returned, but the output schema likely covers that. The sibling context is well covered by the usage hint.

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 schema parameter description is detailed, specifying what aweme_id is, how to obtain it, and what not to pass. The description itself does not add parameter information, but the schema compensates fully. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves video details using the aweme_id. It explicitly distinguishes itself by noting to prefer this entry point when the aweme_id is known, differentiating it from the URL-based 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 provides a clear usage context: 'when aweme_id is known, prefer this entry point.' This implicitly guides the agent to choose this tool over the URL-based alternative. However, it does not explicitly state when not to use it or mention alternatives beyond the hint.

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 include readOnlyHint=true, making the safe read nature clear. The description adds no behavioral details beyond that, so it meets the baseline for annotated tools.

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?

Single sentence, front-loaded with action and input types, no redundant information. Perfectly concise.

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

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

For a simple read tool with output schema, the description covers the input adequately. Minor gap: no mention of error cases or rate limits, but not critical for this tool's 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 schema has 100% description coverage, and the parameter description already explains valid URL types and what to avoid. The main description does not add extra semantic value.

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

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

The description clearly states the action: '获取作品详情' (get video details) and specifies the input types (page link, short link, sharing text). It distinguishes from siblings like douyin_get_video_detail_by_aweme_id by mentioning URL-based input.

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 parameter description advises: '已知 aweme_id 时优先使用 ID 入口' (prefer ID endpoint if aweme_id is known), providing a clear usage alternative. However, the main description lacks explicit when-to-use or 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 already mark readOnlyHint=true. Description adds that it does not trigger reprocessing or long wait, reinforcing behavioral safety. Missing detail on behavior for invalid job IDs, but acceptable for a simple query.

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?

Single sentence in Chinese, efficient and covers key points without waste. Could be structured with bullet points but fine for its simplicity.

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 simple functionality, one required parameter, readOnlyHint, and existing output schema, the description is largely complete. It lacks potential job states or error details, but not critical for a status query.

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 job_id described as '口播转文字任务 ID'. Tool description does not add further meaning, so 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?

Description clearly states it queries the status of a speech-to-text job, distinguishing it from submission tools. It explicitly says '只查询当前 job' (only query current job), 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?

Description indicates when to use (after job submission to check status) and what it does not do (no reprocessing or long wait). However, it does not explicitly mention alternative tools for resubmission, though sibling names make it 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 and openWorldHint. The description adds no additional behavioral context beyond what is in the schema and annotations, such as rate limits or mutation implications.

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, clear sentence front-loaded with the action. It is concise but could be slightly shorter without losing clarity.

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 annotations, the description covers the essential search functionality and filters. Pagination is documented in the schema, so the description is sufficiently complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats some parameter meanings but does not add significant new semantic value 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 clearly states the tool searches for Douyin users by various identifiers (nickname, Douyin ID, etc.) and explicitly distinguishes from searching for videos, differentiating it from sibling tools like douyin_search_videos.

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

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

The description explains when to use the tool (search users with filters) and explicitly excludes searching for works. However, it does not mention when to use sibling tools for user info retrieval after search.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds minimal behavioral context beyond noting that works may include image-text. No contradiction.

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 covering the core purpose without redundancy. It is front-loaded and efficient.

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

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

For a 6-parameter tool with output schema, the description is too sparse. It lacks details on scope, returned data structure, pagination behavior, or edge cases. The schema descriptions help but overall completeness is low.

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 parameter descriptions. The tool description adds only a general statement about searching by keyword and content type, not supplementing the schema meaningfully. 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 'search Douyin works by keyword' with a specific verb (search) and resource (works). It distinguishes from sibling tools focused on user info, hot lists, comments, etc.

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

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

No guidance on when to use this tool versus alternatives like douyin_search_users or hot search. No context about prerequisites or exclusions.

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

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

With no annotations, the description discloses key behaviors: waiting up to 15 seconds, returning job_id and next query action if incomplete. It lacks details on error handling or prerequisites but covers core behavior adequately.

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, efficient sentence conveying all essential 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?

Given the simple one-parameter tool and existing output schema, the description covers the necessary workflow and expected output sufficiently.

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

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

The input schema covers the parameter fully with a detailed description. The tool description adds no extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: submitting a video speech-to-text task by aweme_id. It distinguishes from the sibling tool 'douyin_submit_video_speech_text_by_video_url' by specifying the input method.

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

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

The description implies usage when you have an aweme_id, but it does not explicitly exclude the URL-based sibling or provide when-not scenarios. However, the sibling tool name offers clear differentiation.

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

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

No annotations exist, so the description fully covers behavioral aspects: it is an asynchronous submission that may complete quickly or return a job_id for polling. It does not mention destructive actions, which is appropriate for a submission tool.

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

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

The description is two sentences, conveying the core action, timing, and follow-up without any fluff. Every sentence is essential.

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 (not shown), the description adequately covers the submission flow and async behavior. It could mention prerequisites like valid URL format, but the schema field description fills that gap.

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

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

Schema coverage is 100% for the single parameter, and the description adds no extra meaning beyond the schema's explanation of video_url. 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 submits a task to convert video speech text for Douyin works, using a URL. It distinguishes from siblings by specifying the URL-based entry, while the schema parameter description notes to prefer the ID-based tool when the aweme_id is known.

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 advises waiting up to 15 seconds after submission and explains the fallback when incomplete (returns job_id and next query action). It does not explicitly contrast with the ID-based sibling, but the schema parameter description provides that guidance.

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