SocialDataX 抖音 Douyin MCP

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

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

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

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

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

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

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

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

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

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

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

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

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

The description clearly states it retrieves the Douyin main hot search list, using specific verb and resource. The name and description align perfectly, and it is distinct from all sibling tools which deal with user info, videos, or search, making selection unambiguous.

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

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

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

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

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

Annotations (readOnlyHint: true, openWorldHint: true) already establish this as a safe read operation. The description adds no behavioral detail beyond the input context; it does not mention behavior when the ID is not found or any unusual limitations. With annotations covering the main safety profile, this 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?

A single, focused sentence that conveys the essential purpose without redundancy. It is front-loaded and every word carries meaning.

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 single-parameter lookup, the description combined with the detailed parameter schema, annotations, and an output schema provides sufficient context for an agent to select and invoke the tool correctly. No critical elements are missing.

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

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

The sole parameter is fully described in the schema (100% coverage), including a detailed explanation and exclusions. The description's mention of 'douyin_id' adds no new information beyond the schema, so score is at 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 states '根据用户主页展示的抖音号 douyin_id 获取用户资料' ('Get user profile based on the douyin_id shown on the user's homepage'), clearly specifying the action (get), resource (user info), and input identifier (douyin_id). This distinguishes it from sibling tools that use profile URLs or sec_user_id.

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

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

The description identifies the correct input type (the public douyin_id visible on the profile), and the parameter schema explicitly lists exclusions ('不要传昵称、搜索关键词、sec_user_id、用户主页链接或作品链接'), guiding proper usage. However, it does not explicitly name alternative tools for when another identifier is available.

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 agent understands this is a safe read operation with variable results. The description adds no additional behavioral context (e.g., data freshness, error cases). With annotations covering the safety profile, the description does not go beyond what is already 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 sentence, front-loaded with the core purpose, and contains zero unnecessary words. It achieves conciseness without sacrificing 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 low complexity (1 required parameter, strong annotations, presence of output schema), the description is nearly complete. The only minor gap is that it does not explicitly mention the return structure, but the output schema covers that. The embedded parameter description compensates for disambiguation needs.

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 the parameter thoroughly. The tool description itself adds no parameter information. Baseline 3 is appropriate as the schema carries the burden.

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 (用户资料/user profile) along with the method (by profile URL). It also implicitly distinguishes from siblings like douyin_get_user_info_by_douyin_id and douyin_get_user_info_by_sec_user_id by specifying the input type.

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

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

While the main description lacks usage guidance, the parameter description in the input schema explicitly advises against passing video links and recommends using the sec_user_id entry when available. This provides strong when-to-use and when-not-to-use guidance relative to sibling tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows it is a safe read operation with potentially dynamic results. The description adds no additional behavioral traits beyond the purpose. It does not contradict annotations, nor does it require further disclosure for a simple read operation. Score is baseline as it adds no extra 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 sentence that is concise and front-loaded. It contains no filler or redundant information. Every word serves a purpose: stating the action and providing usage guidance.

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

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

Given the tool's simplicity (one parameter, read-only, output schema exists), the description is sufficient. It covers the purpose and usage preference. The presence of an output schema means the return value does not need further explanation. It is slightly above baseline because it includes sibling differentiation, which helps context.

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% coverage with a detailed description for the only parameter sec_user_id, explaining how to obtain it. The tool description does not add any information beyond what the schema already provides. Therefore, the description adds no extra semantic value, resulting in a baseline score of 3.

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

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

The description clearly states the tool's purpose: '根据抖音用户 sec_user_id 获取用户资料' (get user profile by Douyin user sec_user_id). It further distinguishes from sibling tools by explicitly stating '已知 sec_user_id 时优先使用此入口' (when sec_user_id is known, use this entry point first), which differentiates it from other user info tools like douyin_get_user_info_by_douyin_id or douyin_get_user_info_by_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 provides clear usage guidance: '已知 sec_user_id 时优先使用此入口' (when sec_user_id is known, prefer this entry point). This implies when to use this tool over alternatives. It does not explicitly state when not to use it, but the preference is clear and sufficient for an agent to decide.

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, confirming a read-only, potentially incomplete result set. The description adds valuable context about pagination behavior and URL types. No contradiction found with annotations. Minor gap: does not describe rate limits or result count limits.

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

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

Description is concise at one sentence but covers the core purpose and pagination. The parameter descriptions within the schema are more verbose but necessary for detailed rules. Could be slightly more front-loaded with the key differentiator (URL-based vs sec_user_id).

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 minimal parameters (2), 100% schema coverage, and annotations, the description is largely complete. The pagination details in the parameter schema are thorough. Minor gap: no mention of response structure (but output schema exists to cover that). Could clarify whether the list includes all public videos or only a subset.

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 descriptions). The description provides additional context for 'profile_url' (acceptable formats and what to avoid) and for 'page_token' (detailed usage rules including not modifying or reusing tokens). This adds meaningful value beyond the schema alone.

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 action ('获取...作品列表'), the resource ('抖音用户主页链接、短链接或分享文案'), and the pagination mechanism ('支持 page_token 翻页'). This clearly distinguishes it from siblings like 'douyin_get_user_posted_videos_by_sec_user_id' which uses a different identifier.

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 specifies the types of URLs that can be used (长链接、短链接或分享文案) and explicitly mentions what not to use ('不要传作品链接'). It also advises preferring the sec_user_id entry point when available, but lacks explicit when-not-to-use or alternative tool recommendations for edge cases.

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 mention of pagination support ('支持 page_token 翻页'), which is useful but does not disclose ordering, rate limits, or other behavioral details. With good annotation coverage, the bar is lower; this 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 concise sentence that is front-loaded with the purpose. Every word adds value; no fluff 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 existence of an output schema, the description is largely complete for a simple list retrieval tool. However, it omits mention of authentication requirements, maximum items per page, or whether the list is sorted. Still, it covers the core functionality well.

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 both parameters have detailed descriptions (especially page_token). The tool description adds no additional parameter meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the verb (获取/get), the resource (用户发布的作品列表/list of posted videos), and the key identifier (sec_user_id). It implicitly distinguishes from the sibling tool douyin_get_user_posted_videos_by_profile_url by specifying the input type.

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

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

The description implies usage when a sec_user_id is available and pagination is needed, but it provides no explicit guidance on when to prefer this tool over alternatives (e.g., the profile_url variant) or any prerequisites/restrictions.

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 provide readOnlyHint and openWorldHint, so the description's addition of pagination support (page_token) adds relevant behavioral detail without contradicting annotations. No negative traits disclosed, but the description aligns well with the read-only, open-world nature.

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

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

Single sentence that efficiently conveys core purpose and pagination capability. No wasted words. Slightly under-described for a full standalone definition, but conciseness is a strength.

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 annotations cover safety, the description adequately explains input types and pagination. It doesn't cover potential errors or data freshness, but for a lightweight fetch 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 coverage is 100% with detailed parameter descriptions. The tool description provides overall context but doesn't add new parameter meaning beyond what the schema already covers. 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 a user's short drama series list based on profile URLs (长链接、短链接或分享文案) with pagination support. It distinguishes from siblings like douyin_get_user_series_by_sec_user_id by specifying the input type (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?

No explicit when-to-use guidance in the main description. The schema's profile_url parameter note hints to prefer sec_user_id tools when that ID is known, but the description itself does not state this or contrast with siblings. Usage context is implied but not direct.

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 pagination behavior ('supports page_token'), which is a useful extra detail beyond annotations. No contradictions, but no disclosure of rate limits, authentication needs, 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 description is a single concise sentence with no unnecessary words. It is appropriately sized for a simple tool. However, it lacks structural elements like bullet points or clear sections that might improve scanability. Still 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 simple two-parameter tool, with an output schema and annotations present, the description covers the basic purpose and pagination. However, with many sibling tools, some usage context would improve completeness. It is adequate but not fully 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%, so the schema already documents both parameters thoroughly. The description does not add new semantic meaning beyond what the schema provides; it merely restates the identifier and pagination concept. 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 action (get), resource (user's series list), and method (by sec_user_id, with pagination). It effectively distinguishes the tool from siblings like douyin_get_user_series_by_profile_url (different identifier) and douyin_get_user_posted_videos_by_sec_user_id (different resource).

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

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

No explicit guidance on when to use this tool versus alternatives. It mentions pagination support but does not explain when to choose sec_user_id over profile_url for series, or compare with other user data tools. Usage context is purely implied.

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 adds behavioral context beyond the readOnlyHint and openWorldHint annotations: it states that both identifiers must be passed simultaneously and that pagination is supported via page_token. These operational details help the agent avoid errors and understand repetition behavior, though it does not cover errors or rate limits.

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

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

The description is a single sentence that front-loads the core purpose, then states the required input combination and pagination support. Every clause adds necessary information with no 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 paginated read-only nature, the existence of an output schema, and the high-quality parameter descriptions, the description is sufficient. It covers the main purpose, the required ID pairing, and pagination capability, leaving no obvious gaps for an agent to misuse the 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 input schema already provides 100% descriptive coverage for all three parameters, including detailed explanations for aweme_id, comment_id, and page_token. The description adds no parameter-specific meaning beyond what the schema contains, so the 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 the tool gets Douyin comment replies using aweme_id and first-level comment_id. It uses a specific verb (获取) and resource (评论回复), and distinguishes from sibling tools that fetch top-level video comments by aweme_id/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 provides clear context: both aweme_id and comment_id are required together, and page_token is supported for pagination. It does not explicitly name alternatives or exclusion cases, but the distinction from sibling tools is implicit in the name and 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 agent knows it is a safe read operation. The description adds meaningful behavioral context by stating '一级评论列表' (only first-level comments, not replies) and '支持 page_token 翻页' (supports pagination), clarifying the scope and pagination behavior 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, front-loaded sentence: '根据抖音作品 aweme_id 获取一级评论列表，支持 page_token 翻页。' Every word earns its place, conveying the core action, resource, and a key capability (pagination) with zero padding.

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 a full input schema with 100% parameter coverage, annotations (read-only, open world), and an output schema, the description is complete. It covers the essential purpose, scope (first-level comments), and pagination. No critical information is missing for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, providing detailed explanations for both aweme_id and page_token. The tool description itself does not add parameter details beyond what the schema already specifies, so the baseline 3 is appropriate. It does not compensate for any gaps because there are none.

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: getting a first-level comment list based on aweme_id, with pagination support. The verb '获取' (get) plus resource '一级评论列表' (first-level comment list) and key parameter 'aweme_id' make it specific. It also distinguishes from siblings like douyin_get_video_comments_by_url by the 'by_aweme_id' mechanism.

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 conditions usage on having an aweme_id ('根据抖音作品 aweme_id'), which gives clear context for when to use this tool. It does not explicitly mention alternatives or exclusions, but the sibling tool names (e.g., douyin_get_video_comments_by_url) make the differentiation obvious. No misleading 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?

The annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to reiterate that this is a read operation. The description adds useful behavioral context beyond annotations: it specifies the pagination mechanism, how page_token should be handled (including strict prohibitions on modification), and what types of URLs are valid. The description does not contradict annotations. The only minor gap is that it does not clarify that '一级评论列表' does not include replies (which is probably handled by the sibling replies tool), but the sibling name makes this clear.

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 front-loaded with the core purpose and pagination feature. Every element earns its place: the verb, the resource, the three accepted URL formats, the explicit exclusions, the guidance to use ID-based alternative, and the pagination support. No redundancy or 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?

The description covers the essential aspects: input URL types, pagination, and a sibling recommendation. However, given output schema exists (not shown but indicated) and a sibling for fetching replies exists, the description does not need to explain return values or the difference between comments and replies. The slight gap is not specifying that it returns first-level comments only, which is implied but could be misinterpreted as including nested replies.

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 fully. The description adds marginal value by clarifying the URL parameter's three valid formats and explicitly excluding 'video.play_url' and user profile URLs. For page_token, it reinforces the schema's prohibition on modification. These additions are helpful but not extensive, raising the baseline from 3 to 4.

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

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

The description clearly states the verb '获取' (get), the resource '一级评论列表' (first-level comment list), and the input method '通过抖音作品页面链接、作品短链接或包含作品链接的分享文案' (via Douyin video page link, short link, or sharing text containing a video link). It also mentions the pagination feature '支持 page_token 翻页', distinguishing it from siblings like 'douyin_get_video_comments_by_aweme_id' which takes an 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 provides clear usage context: it specifies the types of URLs that are acceptable and explicitly warns against using video playback URLs or user profile URLs: '不要传 video.play_url 这类播放资源链接，也不要传用户主页链接'. It also recommends using the ID-based tool when the aweme_id is known: '已知 aweme_id 时优先使用 ID 入口'. However, it does not explicitly state when NOT to use this tool versus its siblings, only an implicit preference for the ID-based alternative.

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, indicating a safe read operation with possibly changing results. The description does not add additional behavioral traits beyond stating it gets details. Since annotations cover the safety profile, the description's minimal addition earns a 3; it is consistent and not misleading.

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

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

The description is two short sentences with no wasted words. It is front-loaded with the purpose and includes the usage guideline efficiently. 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 simplicity (1 parameter), presence of annotations, and existence of an output schema (so return values are documented elsewhere), the description is complete. It clearly states what it does, when to use it, and how to provide input.

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 a detailed parameter description specifying that aweme_id is numeric, reusable from other results, and not to be confused with links or quoted strings. The tool description does not add significant meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool gets video details by aweme_id, specifying the verb (获取), resource (作品详情), and scope (by aweme_id). It distinguishes from sibling tool douyin_get_video_detail_by_url, which uses a 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 explicitly says '已知 aweme_id 时优先使用此入口' (when aweme_id is known, prefer to use this entry), providing direct guidance on when to use this tool versus alternatives. The parameter schema further instructs not to pass video links or quoted strings, clarifying proper input.

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 about acceptable input formats and rejections but does not go beyond what annotations imply—it's a safe, read-only retrieval. 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 one sentence with clear structure: what to input, what NOT to input, and a tip. It earns its length without waste. However, it could be slightly more concise by removing '不要传' 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 single-param schema, rich annotations, and presence of an output schema, the description is complete enough. It covers input validation and alternatives. No need to detail return values as output schema exists.

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

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

Schema description coverage is 100% for the single parameter 'url'. The description adds meaningful usage guidance (e.g., avoiding play_url, preferring ID) and clarifies acceptable formats, going beyond the schema's basic description.

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

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

The description clearly states the verb ('获取', get/retrieve) and resource ('作品详情', video details), specifying three input formats (page link, short link, share text). It distinguishes from siblings like 'douyin_get_video_detail_by_aweme_id' by mentioning '已知 aweme_id 时优先使用 ID 入口', but does not explicitly differentiate from the sibling 'douyin_get_video_detail_by_aweme_id' in terms of use cases.

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 tells what NOT to pass (video.play_url, user profile links) and when to use an alternative (aweme_id preferred). However, it does not explain when to use this tool versus the sibling tools for comments or user info.

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

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

Annotations indicate readOnlyHint=true and openWorldHint=true, but description adds behavioral details: it waits up to 240 seconds, does not trigger reprocessing, and should not be used to resubmit. This goes beyond the annotation hints and provides valuable operational context. 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?

Single sentence that packs in purpose, usage, and behavioral warnings without redundancy. Every word earns its place and the key action (query status) is front-loaded.

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

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

Has output schema, so return values are covered. Description includes when to use (after submit), wait behavior, and constraints (not resubmit). For a single-parameter polling tool, all essential context is provided; annotations cover safety. 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?

The only parameter, job_id, is already thoroughly described in the schema (must be from submit tool, not other IDs). The description does not add new meaning beyond repeating the schema's guidance. With 100% schema coverage, baseline 3 applies; description adds no extra value here.

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 queries task status for speech-to-text conversion using a job_id, with a specific verb and resource. It distinguishes itself from sibling submit tools by referencing the submit tool's return value. The purpose is unambiguous and not a tautology.

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 says '用于继续未完成任务' (for continuing incomplete tasks), gives a wait time cap of 240 seconds, and warns not to trigger reprocessing or resubmit. However, it does not explicitly name alternative tools or contrast with them, though the context implies it is the only polling 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 include readOnlyHint=true and openWorldHint=true, which already indicate a safe read operation. The description adds the pagination constraint (page_token must be passed exactly as returned) and clarifies this is a search operation. However, it does not detail return value structure or potential rate limits, but the output schema exists, so the description adds acceptable context beyond annotations 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 concise (two sentences) and front-loaded with the core purpose and pagination. It efficiently mentions usage guidelines and excludes. It could have been slightly more structured but overall is efficient with zero 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 has 4 parameters, 100% schema coverage, an output schema, and read-only annotations, the description covers the essential behavior. The description adds usage boundaries and pagination caveats, and given the rich annotations and schema, it is reasonably complete. It doesn't explain return fields but the output schema 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 description coverage is 100%, so the schema already documents all parameters. The description adds meaningful semantics for keyword by specifying acceptable types (昵称、抖音号、账号名等) and explicitly excluding non-search inputs like links or sec_user_id, which is valuable. The pagination parameter is also explained in detail in the schema. Since coverage is high, the baseline is 3; the extra clarification on keyword usage and page_token handling justifies a 4.

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/accounts/creators and supports pagination via page_token. It uses a specific verb (搜索) and resource (用户/账号/博主/创作者/达人), and distinguishes itself by explicitly noting it is not for searching works and by referencing alternatives when sec_user_id or profile URL are already 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 states when to use this tool ('用户需要按搜索词查找用户时使用') and when not to ('已有 sec_user_id 或用户主页链接时使用相应用户资料或列表工具；不用于搜索作品'). It also names alternatives implicitly via sibling tools, giving clear usage context.

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

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

The readOnlyHint and openWorldHint annotations already signal read-only and open-world behavior. The description adds practical behavioral notes: works are typically videos but may include image/text content, and pagination is supported via page_token. No contradictions; the added content-type note and pagination mention go slightly beyond schema, but no auth or rate-limit details are provided. Score 4 is fair given the annotations cover the core safety profile.

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, compact sentence that front-loads the purpose, immediately provides usage alternatives, notes content-type variability, and mentions pagination. Every clause earns its place; no fluff 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?

The description is complete for a search tool with an output schema present. It covers the core use case, exclusion criteria, content-type nuance, and pagination. The parameter schema is fully enriched with detailed semanticsholmgren, so no further return-value explanation is needed. All necessary context 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 input schema provides 100% parameter coverage with rich descriptions for every field, including enum explanations, exclusions for keyword (no URLs), and detailed page_token handling rules. The description adds no additional parameter semantics because the schema already handles it thoroughly, which meets the high-coverage baseline.

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

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

The description uses a specific verb (搜索/search) with a clear object (抖音作品/Douyin works) and explicitly states when to use this tool (when searching by keyword) versus when not (when you already have a link or aweme_id, use detail/comment/speech tools). This directly distinguishes it from sibling search and detail tools.

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

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

The description explicitly states the tool is for keyword-based search, gives a clear condition for use (need to find works by search term), and explicitly advises using different tools when a link or aweme_id is available. This provides solid contrast with the sibling tools for details, comments, and speech-to-text.

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.

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds 'current' indicating real-time balance and specifies the scope as the API Key account's balance, which aligns with openWorldHint. It does not disclose additional behaviors like rate limits, but given the simple nature, this is sufficient.

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

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

The description is a single, front-loaded sentence that says exactly what the tool does with no wasted words. It is appropriately 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?

The tool is very simple, with no parameters and an output schema present, so the description does not need to explain return values. The combination of the description and structured fields fully covers the tool's behavior.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. According to the baseline, with 0 params the score is 4, and the description doesn't need to add parameter details.

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 'Query' and the resource 'current API Key account's SocialDataX points balance', making its purpose unambiguous. It distinguishes itself from sibling tools that all target douyin data, as this concerns the API key holder's own balance.

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 clear context: this tool is for checking your own SocialDataX points balance, which is distinct from all sibling douyin data retrieval tools. It does not explicitly exclude alternatives, but the scope is so specific that usage is clear.

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