SocialDataX 抖音 Douyin MCP

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

Annotations already indicate readOnlyHint and openWorldHint. The description adds a behavioral constraint (no pagination), which is valuable beyond the annotations. There is 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 concise with two sentences, front-loading the purpose. It could be slightly more structured but is efficient and contains 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 tool has no parameters and returns a simple hot list (output schema exists), the description is complete enough. It covers the purpose and a key limitation.

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?

No parameters exist, so schema coverage is 100%. The baseline for 0 parameters is 4, and the description does not need to add parameter information.

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 (获取抖音主热榜), which is a specific verb-resource combination. It is easily distinguishable from sibling tools that focus on user info, video details, or search.

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

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

The description mentions a key limitation (no pagination support), which provides usage guidance. While it does not explicitly state when to use versus alternatives, the sibling tools are semantically distinct, making the context clear.

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

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

Annotations already declare readOnlyHint and openWorldHint. The description does not add behavioral context beyond the annotations, 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 sentence that efficiently conveys the tool's purpose with no unnecessary words. It is front-loaded and to the point.

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, the presence of an output schema, and annotations covering read-only and open-world behavior, the description is fully adequate. No additional context is needed for correct usage.

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 parameter description in the schema already provides detailed guidance. The tool description adds minimal extra meaning beyond naming the parameter.

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 user info) and the input source (Douyin profile URL, short link, or shared text). It distinguishes itself from sibling tools that use sec_user_id or handle 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 parameter description advises against passing video links and recommends using the sec_user_id tool when available, providing context for when to use this tool. However, the main description does not explicitly state when not to use it or list 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?

The description does not add behavioral details beyond the annotations. Annotations already indicate readOnlyHint=true (safe read), and the description simply confirms the operation. With annotations covering safety, the description adds minimal extra 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 sentence that conveys the purpose and usage guidance efficiently. No unnecessary words, front-loaded with the core 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?

Given the low complexity (one parameter, simple read operation) and the presence of an output schema, the description provides sufficient context. No further details are needed for the agent to use 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?

The schema coverage is 100% with a single parameter. The description provides additional context on where to obtain sec_user_id (from author.sec_user_id or previous results), which adds meaning 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 gets user info by sec_user_id, and explicitly indicates it is the preferred entry when sec_user_id is known. This distinguishes it from sibling tools that use profile_url or other identifiers.

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 to use this tool when sec_user_id is known ('已知 sec_user_id 时优先使用此入口'), which provides clear usage guidance. However, it does not explicitly state when not to use it or list alternatives, though the sibling context implies those.

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 and openWorldHint=true. The description adds context that the tool supports pagination via page_token and accepts multiple URL formats (long, short, share text), which are useful behavioral details 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, clear sentence that front-loads the primary action and pagination capability, 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?

With an output schema present and the description covering key aspects (purpose, input variations, pagination), the tool is well-documented. Minor omission: doesn't explicitly mention it's read-only, but annotations 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% (both parameters have detailed descriptions in the schema). The tool description itself does not add parameter specifics beyond what the schema provides, so 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?

Description clearly states the tool's function: retrieve a user's posted videos using a Douyin profile URL (long link, short link, or share text), with pagination support. This distinguishes it from siblings like douyin_get_user_posted_videos_by_sec_user_id which uses 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 parameter description for profile_url explicitly advises not to pass video links and to prefer the ID entry (sec_user_id) when known, providing clear guidance on tool selection. However, the main description lacks an explicit when-to-use statement, though the schema detail compensates.

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 pagination detail but no further behavioral context like rate limits or data freshness. 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?

The description is a single concise sentence (22 characters) that covers the essential functionality and pagination. 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 that output schema exists, the description need not explain return values. It adequately covers the tool's purpose and pagination, though it lacks details on prerequisites like authentication.

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. The description adds no new meaning beyond restating the parameter names. 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 resource '用户发布的作品列表' (list of user's posted videos), and specifies the key identifier 'sec_user_id'. It distinguishes from sibling tools like those using profile_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?

The description indicates when to use this tool (when you have a sec_user_id) and mentions pagination. However, it does not explicitly state alternatives or when not to use it, but the context is clear.

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

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

Annotations already declare readOnlyHint=true. The description adds pagination behavior via '支持 page_token 翻页' and input constraints, providing useful 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 concise sentence that front-loads the core action and input, with no redundant words. Every part is necessary.

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

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

With an output schema present, the description correctly focuses on input and behavior. Pagination is covered, but error handling or rate limits are not mentioned. Still, for a read-only list tool, this 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%, but the description adds significant value for profile_url by clarifying accepted types (long link, short link, shared text) and warnings, which the schema does not include. The pagination hint reinforces page_token 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 clearly states the tool retrieves a user's series list (short drama list) using profile links or shared text, distinguishing itself from sibling tools that use sec_user_id. The verb '获取' (get) and resource '用户短剧列表' (user series list) are 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?

Description explicitly instructs not to pass video links ('不要传作品链接') and recommends using sec_user_id entry when known ('已知 sec_user_id 时优先使用 ID 入口'), guiding toward the correct sibling tool. However, it does not elaborate on other scenarios.

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=true and openWorldHint=true. The description adds pagination behavior but does not disclose other traits like rate limits, error states, or data scope. It does not contradict annotations, so 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 very concise (two clauses) and front-loaded. No wasted words, though it could be slightly more structured (e.g., separating purpose and pagination).

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 2 parameters, no nested objects, and an output schema present, the description is adequate but minimal. It does not explain the concept of 'series' or usage patterns, but the output schema reduces the need for return value 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 coverage is 100%, and the schema already thoroughly describes both parameters, especially page_token. The description adds marginal value by confirming the purpose of sec_user_id and page_token, but does not enhance semantics beyond the schema.

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

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

The description clearly states the verb ('获取', obtain) and resource ('用户短剧列表', user series list) for a given sec_user_id. It also mentions pagination support, and distinguishes from sibling tools that use profile_url or different endpoints.

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 only implies usage: to get series by user sec_user_id. It does not specify when to use this over sibling tools like douyin_get_user_series_by_profile_url or douyin_get_user_posted_videos_by_sec_user_id, nor does it mention prerequisites or 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 indicate readOnlyHint=true, so the description is not required to reiterate safety. It adds useful context about pagination (page_token) and the necessity of both IDs, though it does not cover rate limits or auth. Overall, it complements the annotations well.

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 Chinese sentence that efficiently conveys purpose, requirements, and pagination support. Every part is necessary; 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 moderate complexity (3 required params, pagination) and the presence of an output schema, the description adequately covers what the tool does and its essential usage. It lacks explicit error conditions but is otherwise 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% with detailed parameter descriptions. The description reiterates the requirement to pass both IDs and explains pagination usage, but adds little beyond what the schema already provides. Baseline 3 is appropriate given the high schema coverage.

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

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

The description specifies the verb '获取' (get), the resource '抖音评论回复' (Douyin comment replies), and the required parameters (aweme_id and comment_id), clearly distinguishing from sibling tools like douyin_get_video_comments_by_aweme_id which gets comments rather than replies.

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 states the requirement to pass both aweme_id and comment_id, and mentions pagination support. However, it does not explicitly contrast with alternative tools or provide when-not-to-use guidance, leaving usage context implicit.

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

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

Annotations already declare readOnlyHint=true (safe read) and openWorldHint=true (unexpected behavior possible). The description adds behavioral info about pagination support via page_token, which is beyond annotations. It does not disclose other details like rate limits or empty result handling, but given annotations, the description provides adequate supplementary 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?

The description is a single, concise sentence that immediately conveys the core action and resource. It is front-loaded with the most important information. Minor improvement could be adding a note about return format, but it remains efficient and clear.

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 an output schema exists (though not shown), the description need not detail return values. It covers the essential aspects: what the tool does (get first-level comments), the key identifier (aweme_id), and pagination support. It lacks mention of possible limitations like pagination size, but for a simple tool with complete schema and annotations, it is adequately comprehensive.

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 (including what not to pass) and page_token (clear pagination rules). The tool description adds no additional parameter semantics beyond a brief mention of pagination. Baseline score of 3 is appropriate as schema already explains parameters fully.

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 first-level comments by aweme_id, using the specific verb '获取' (get) and resource '一级评论列表' (first-level comment list). It distinguishes itself from sibling tools like douyin_get_video_comment_replies_by_comment_id (replies) and douyin_get_video_comments_by_url (comments by URL) by specifying it returns only top-level comments via 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 description implies usage context by specifying '一级评论' (first-level comments) and support for page_token pagination, which indirectly guides the agent to use this tool for top-level comments rather than replies. However, it does not explicitly state when not to use it or compare with alternatives like the URL-based comment tool, though the context from sibling names is sufficient.

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 the description reinforces by focusing on read operations and pagination. It adds context on acceptable URLs but doesn't cover rate limits or auth requirements.

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 main description is a single efficient sentence. Parameter descriptions are thorough yet concise, with no redundant or missing information.

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

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

With 2 parameters, 100% schema coverage, and an output schema present, the description fully covers the needed context for correct invocation, including pagination mechanics and input validation.

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 descriptions add significant value: for url, it specifies acceptable types and exclusions; for page_token, it explains usage, constraints, and reuse rules in detail.

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

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

The description clearly states the action (获取/get), resource (一级评论列表/first-level comment list), and input type (by URL). It distinguishes from sibling tools like the aweme_id version.

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 lacks explicit when-to-use vs alternatives, but the url parameter provides negative guidance (e.g., avoid play URLs, prefer ID when known) and implicitly differentiates from the 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 the behavioral profile. The description adds no further behavioral context, such as response format or rate limits, which is acceptable given the annotations' completeness.

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 purpose, and every word serves a purpose. No redundancy or verbosity.

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 only one parameter and an output schema present, the description provides complete context: purpose, when to use, and precise parameter guidance. All information needed for correct invocation is present.

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

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

The schema description covers the parameter at 100%, and the description adds valuable context: specifying that the aweme_id should be a numeric string from search/detail/comment results, and explicitly stating what not to pass (links, share text, quoted strings). This exceeds 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 clearly states the verb '获取' (get), resource '作品详情' (video detail), and method 'by aweme_id'. It also distinguishes from the sibling 'douyin_get_video_detail_by_url' by specifying preference 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?

The description explicitly advises to prefer this entry when aweme_id is known, providing clear usage context. However, it does not explicitly state when not to use it or provide alternatives beyond the sibling tools mentioned.

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. The description does not add behavioral details beyond input constraints, but it does not contradict annotations. No additional disclosure on error handling or data freshness is provided.

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 delivers the core purpose without extraneous words. It is effectively front-loaded.

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

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

Given the simple input (one parameter) and the presence of an output schema, the description is mostly complete. It lacks an explicit statement about what the tool returns, but the output schema fills that gap. Minor improvement could be mentioning output details.

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

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

The description does not add parameter information beyond the schema; the schema already provides a detailed description of the 'url' parameter. With 100% schema coverage, the baseline is 3, and the description offers no 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 that the tool retrieves video details from various Douyin URL formats (work page link, short link, sharing text). It distinguishes from the sibling tool douyin_get_video_detail_by_aweme_id by specifying URL 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 description and parameter schema explicitly state when to use this tool (given a URL) and when not to (avoid video.play_url, user profile; prefer aweme_id entry). This provides clear guidance and 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 and openWorldHint=true, but the description adds behavioral detail: it supports long polling and explicitly states it does not trigger reprocessing. This goes beyond the annotations and provides useful safety and behavior info.

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: two sentences, no wasted words. Front-loaded with the primary purpose, followed by the key optional behavior. 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?

Given the output schema exists and the tool is simple (status query with optional polling), the description covers the core functionality adequately. It could mention what the response contains or error cases, but the output schema presumably covers that. It is close to complete for its complexity level.

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% (both parameters described). The description adds minimal extra semantics beyond the schema: it restates the wait_seconds behavior (0=one query, max 240). Baseline of 3 is appropriate as the schema already does the heavy lifting.

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

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

The description clearly states the tool's purpose: querying the status of a Douyin video speech-to-text job. It specifies the action (query) and resource (job status), distinguishing it from sibling tools that submit jobs or retrieve other data.

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 optional long polling and clarifies that it does not trigger reprocessing, which gives some usage context. However, it does not explicitly state when to use this tool versus alternatives (e.g., after submission, or when to poll vs. not). More explicit guidance would improve usability.

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. The description adds that it supports filtering but does not disclose additional behavioral traits. 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 sentence that covers the main purpose and exclusions. No wasted words, very 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 4-parameter schema and output schema, the description is fairly complete. It explains the core functionality and what it is not for. Pagination behavior is left to the parameter description, which is acceptable. Could mention return format but output schema covers 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 coverage is 100%, so the schema already documents all parameters in detail. The description adds context that the keyword can be various names and that filtering is supported, but this adds only marginal value beyond the parameter descriptions themselves.

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 Douyin users by nickname, ID, or account name, and distinguishes it from sibling tools like search for works. It uses specific verbs and resources, 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?

The description explicitly says 'not for searching works', which guides against using for videos. However, it does not differentiate among the many sibling user-info tools (e.g., get_user_info_by_profile_url), leaving ambiguity about when to use this search vs specific user lookups.

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, indicating safe read and potentially changing results. The description adds that content may include both video and image formats, which is consistent with annotations and provides useful context beyond 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 sentence that clearly conveys the tool's purpose. It is concise and front-loaded, with no wasted words 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 the 6 parameters and presence of an output schema, the description adequately sets context for the search operation. However, it could briefly mention pagination (page_token) to aid understanding, though the parameter description covers it fully.

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 has 100% description coverage for all 6 parameters, including detailed descriptions for sort_type, page_token, content_type, etc. The tool description adds minimal extra semantics beyond the schema, meeting the baseline expectation 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 explicitly states the action (search), resource (Douyin works/videos), and scope (by keyword). It also clarifies that results may include both videos and image-text content, distinguishing it from sibling tools focused on users, hot searches, or specific 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 clearly indicates this is for general keyword-based search of Douyin works, while sibling tool names (e.g., douyin_get_user_info_*, douyin_get_video_detail_*) imply more targeted use cases. However, there is no explicit 'when not to use' or mention of 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?

With no annotations, the description discloses the async submission, wait period, and fallback to job_id for polling. This provides essential behavioral context beyond the schema, though it omits details like rate limits or error handling.

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

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

The single-sentence description is concise, front-loaded with purpose, and every phrase adds value (submit, wait, job_id, next action). 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 and sibling tools, the description provides adequate context for the async task. However, it could be improved by explicitly naming 'douyin_get_video_speech_text_job' as the follow-up query 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?

The schema already has 100% coverage and description, but the tool description adds crucial context: aweme_id must be numeric, reusable from other endpoints, and not be links or quoted strings. 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?

The description clearly states the tool submits a video speech-to-text task using aweme_id, with specific behavior (wait 240s, return job_id). It distinguishes from sibling tools like 'douyin_submit_video_speech_text_by_video_url' which uses URL 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 description implies when to use this tool (when aweme_id is available) and mentions the async flow (wait, then query), but does not explicitly contrast with alternatives or state when not to use.

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

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

With no annotations, the description carries full burden. It discloses the wait time (240s) and the asynchronous behavior (return job_id and next action if not completed). It is transparent about the submission process but could clarify what happens upon completion within the wait period.

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 concise sentences, front-loaded with the primary action. No wasted words; every sentence adds value. Efficient structure.

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 with one parameter and an output schema, the description covers the submission intent, async behavior, and next steps. It is complete for an AI agent to understand how to invoke and proceed.

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 detailed parameter description. The main description does not add parameter information, so baseline 3 applies. The schema already provides clear guidance on what constitutes a valid video_url.

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

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

The description explicitly states it submits a video speech-to-text task, specifies the source (video URL), and outlines the behavior (wait up to 240s, return job_id if pending). It distinguishes from the sibling tool that uses 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?

Description implies use when you have a video URL and hints at preferring the ID entry when available. However, it does not explicitly state when not to use it or fully compare with alternatives. The parameter description adds clarity but the main description alone could be more direct.

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