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 indicate readOnlyHint and openWorldHint, so no need to restate. The description adds constraints on input types but does not discuss error handling or behavior with invalid URLs. The combination is adequate but not rich.

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

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

The description is a single sentence that conveys the core functionality and input. No filler, no repetition. 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?

Given the presence of an output schema and annotations, the description covers the essential: what the tool does, what input to provide, and a key constraint. It implicitly distinguishes from siblings. For a simple read tool, this is sufficient.

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

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

Schema description coverage is 100%, and the parameter description already details accepted input types and constraints. The tool description does not add extra meaning beyond what the schema provides, 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?

The description clearly states 'get user data' and specifies the types of URLs (long, short, share copy). It distinguishes from the sibling tool by mentioning the alternative ID entry, making the tool's purpose unique and specific.

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 provides guidance on when to use this tool vs the ID-based sibling, and explicitly warns against passing work links. However, it does not explicitly state general usage context or when not to use this 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 and openWorldHint, so the bar is lower. The description adds no behavioral details beyond the usage hint, but is adequate given 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?

Extremely concise, single sentence with no unnecessary words, front-loading the key action and usage priority.

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?

Simple tool with one param, good annotations, and output schema exists. Description is minimal but sufficient for the simple use case.

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

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

Only one parameter, schema already provides full description. The tool description does not add extra parameter info; schema coverage is 100%, baseline 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 clearly states the tool retrieves user profile via sec_user_id and explicitly distinguishes it from the sibling tool using profile_url by prioritizing this entry.

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: '当已知 sec_user_id 时优先使用此入口' (when sec_user_id is known, prioritize this entry), helping the agent choose between this tool and its 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 and openWorldHint. Description adds no additional behavioral context beyond stating it is a read operation and supports pagination. 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?

Description is a single sentence in Chinese, concise and front-loaded with the core action and inputs. No filler or redundant information.

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

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

Given output schema exists and annotations cover behavioral aspects, description is adequate to understand the tool's purpose and input requirements. Could mention that it only works with profile URLs not sec_user_id, but that is evident from sibling names.

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. Tool description adds 'supports page_token pagination' but this is already implied by the page_token parameter. 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 the action (get list of user's posted videos), resource (user's works), and input method (profile URL). It distinguishes from sibling tools like those using 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?

Description does not explicitly state when to use this tool vs alternatives. However, the parameter description for profile_url hints not to pass video links and to prefer sec_user_id entry when known, providing some guidance but not in the main 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, providing a safety profile. The description adds that pagination is supported via page_token, which is useful behavioral context beyond annotations. No contradictions.

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 efficiently communicates the tool's core function and pagination support, with no unnecessary 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 high schema coverage, annotations, and presence of an output schema, the description is mostly complete for the tool's purpose. It could mention ordering or default results but is adequate.

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 input schema already documents both parameters with descriptions. The tool description adds no additional parameter meaning beyond summarizing the purpose, meeting the baseline expectation.

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 list of user-posted videos by sec_user_id and supports pagination. This differentiates it from siblings like douyin_get_user_posted_videos_by_profile_url, which uses a profile URL instead.

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

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

The description implies when to use (when you have sec_user_id) but does not explicitly mention alternatives or when not to use. The context of sibling tools provides some guidance, but the description itself could be more 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 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 declare readOnlyHint and openWorldHint. Description adds the data source (aweme_id) and result (detail) but no additional behavioral traits. 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?

Two sentences, no fluff, front-loaded purpose and usage hint. 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 one-parameter tool with output schema and clear sibling list, the description is adequate. Provides purpose and priority 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 coverage 100% with detailed parameter description. Description repeats 'aweme_id' without adding new meaning beyond schema, so baseline 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?

Description clearly states the tool retrieves video detail by aweme_id, and advises preference over other paths when aweme_id is known. Distinguishes from sibling like douyin_get_video_detail_by_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?

Explicitly says to prefer this entry when aweme_id is known, providing usage context. Does not enumerate exclusions but is clear enough.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds useful behavioral context about accepting sharing text and parsing it, but does not disclose additional traits like rate limits or extraction logic. Overall, it complements annotations well without 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 in Chinese that packs all necessary information succinctly. Every part adds value, with no wasted words or 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 single parameter with full schema coverage and the presence of an output schema, the description adequately covers input constraints and usage hints. It misses a brief note on what 'details' include, but the output schema likely covers that. Overall, it is sufficiently complete 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?

With 100% schema description coverage, the schema already describes the parameter as 'Douyin video page link, short link, or sharing text'. The description adds further semantic value by specifying what NOT to pass (play resource links, user profile links) and when to prefer the aweme_id variant, significantly enriching the parameter 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 clearly states the tool retrieves video details via Douyin video page links, short links, or sharing text containing a video link. It explicitly distinguishes from the sibling tool `douyin_get_video_detail_by_aweme_id` by noting when to prefer that alternative.

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

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

The description provides explicit guidance on what input types are acceptable (page links, short links, sharing text) and what to avoid (play resource URLs, user profile links). It also advises using the aweme_id entry when the ID is known, aiding tool 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 declare readOnlyHint=true, and the description adds further behavioral context: it does not trigger reprocessing or long waits. This provides value beyond annotations and no contradictions.

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

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

Two sentences, each serving a distinct purpose: stating the function and clarifying behavior. No wasted words, front-loaded with the key action.

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 polling tool with full schema coverage, existing output schema, and clear annotations, the description is complete. It gives the agent all necessary context to decide when and how to use it.

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

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

Schema coverage is 100% with a single parameter (job_id) described as '口播转文字任务 ID。'. The description does not add additional meaning to the parameter, so it meets baseline expectations without enhancement.

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 queries the status of a Douyin video speech-to-text job, using a specific verb (query) and resource (job status). It distinguishes itself from sibling submission tools by noting it only queries, not triggers reprocessing.

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

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

The description explicitly says it only queries the current job and does not trigger reprocessing or long waits, which guides the agent on when to use it (for polling status) and implicitly not to use it for submission. It could be more explicit about alternatives, but the sibling tools 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. Description adds that results may include image-text works, providing useful context beyond annotations but doesn't mention pagination or other behaviors.

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, no fluff, front-loaded with purpose. Could be slightly more structured but effective.

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 output schema present, return values are covered. Description covers basic purpose and content type, but omits pagination behavior which is important for this tool. Moderately complete.

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

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

Schema coverage is 100%, so baseline is 3. Description doesn't add meaning beyond the schema for parameters, though it confirms the keyword search purpose.

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 searches Douyin works by keyword, specifying the resource (works/videos) and distinguishing from siblings like hot search lists or user-specific 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 implies usage for keyword-based search, but lacks explicit guidance on when to use alternatives like user info tools or hot search lists. No exclusions 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?

With no annotations provided, the description carries the full burden. It discloses the submission action, waiting behavior, and expected outputs (job_id and next query action). It does not cover error conditions, rate limits, or idempotency, but the waiting behavior and response pattern are clearly stated.

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, front-loaded with the core function and immediately followed by behavioral details. Every sentence serves a purpose 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 (unprovided but known) and low complexity (1 parameter), the description is adequate. It explains the submission process and expected outcomes, though it could clarify whether completed tasks return results directly instead of just mentioning job_id for incompletion.

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 adds value by clarifying what not to pass (links, quoted strings), which is meaningful guidance beyond the schema's own parameter 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's purpose: submitting a video speech-to-text task based on the aweme_id. It specifies the action (submit), resource (video speech-to-text task), and identifier, effectively distinguishing it from sibling tools like the URL-based submission.

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 guidance on post-submission behavior (wait up to 15 seconds, return job_id if incomplete). However, it does not explicitly state when to use this tool versus the URL-based alternative, nor does it mention 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?

No annotations are provided, so the description carries full burden. It reveals that the tool waits up to 15 seconds and returns a job_id if not done, implying asynchronous behavior. However, it fails to explicitly state that it's an async task requiring polling, nor does it disclose potential errors or limits. This is adequate but not fully transparent.

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 concise sentences that convey purpose and key behavior. It is front-loaded and earns its place, though could be better structured with bullet points or clearer separation of steps.

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 asynchronous nature and existence of an output schema, the description adequately conveys the submission process and post-submission actions. However, it does not cover error handling, rate limits, or explicit polling instructions, leaving minor gaps for a task-oriented tool.

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

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

Schema description coverage is 100%, and the parameter description is detailed, specifying acceptable URL formats and exclusions. The tool description adds no extra parameter information, so baseline 3 applies. The schema itself provides sufficient 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 the tool submits a video speech-to-text task for Douyin works. It uses specific verb 'submit' and resource 'video speech text task'. The parameter description in schema further clarifies acceptable URL types, helping distinguish from the ID-based sibling tool, though not explicitly in the tool description itself.

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 some usage guidance: wait up to 15 seconds and if incomplete, use the returned job_id for next query action. However, it does not explicitly state when to prefer this tool over the aweme_id variant, nor does it mention that polling with douyin_get_video_speech_text_job is needed, leaving room for confusion.

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