SocialDataX 小红书 Xiaohongshu XHS RedNote MCP

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

Beyond annotations (readOnlyHint, openWorldHint), description reveals opaque pagination token behavior: must be passed exactly, cannot be reused across different contexts. This adds valuable behavioral insight not captured 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?

Purpose is front-loaded in one sentence, but the pagination token explanation is verbose and repetitive, listing multiple prohibitions. Could be more concise without losing clarity.

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

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

Given presence of output schema, description covers pagination thoroughly and clarifies it returns first-level comments. Minor gaps: no mention of authentication or rate limits, but annotations cover safety profile.

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

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

With 100% schema coverage, baseline is 3. Description adds significant meaning: note_id is a 24-character lowercase hex stable ID that must be copied exactly; page_token must be passed verbatim from previous response. This exceeds the schema's own descriptions.

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

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

Description clearly states the action ('获取', get) and resource ('单篇小红书笔记的一级评论', first-level comments of a single note). It distinguishes from sibling tools like xhs_get_note_comments_by_note_url and xhs_get_note_sub_comments_by_comment_id by specifying 'note_id' and '一级评论'.

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

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

Description does not provide explicit guidance on when to use this tool versus siblings, nor does it mention prerequisites or context for usage. The alternative tools are implied by name but not addressed.

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 detailed behavioral context about pagination token opacity, non-reusability, and strict handling rules, which goes 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 two sentences: first states purpose, second details pagination. It is front-loaded, efficient, and contains no superfluous content.

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

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

Given that an output schema exists (not shown), the description does not need to explain return values. It covers core functionality and pagination behavior. Minor gaps like error handling or prerequisites are acceptable given the openWorldHint annotation.

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 baseline is 3. The description does not add significant new parameter details beyond what is in the schema, but it reiterates the note_url forms and pagination behavior from the schema.

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

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

The description specifies the verb '获取' and resource '单篇小红书笔记的一级评论', clearly indicating it retrieves top-level comments for a single Xiaohongshu note via URL. It distinguishes from sibling tool 'xhs_get_note_comments_by_note_id' by explicitly using note URL as 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 provides explicit pagination instructions and constraints on token usage, but does not directly mention when to use this tool over alternatives like 'xhs_get_note_comments_by_note_id'. The context is clear but exclusions or alternatives are not stated.

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

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

Annotations already indicate readOnlyHint=true, so the description adds value by detailing the required handling of the note_url output. No contradictions with annotations. However, it does not cover other behavioral aspects like authentication 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 concise, with two sentences that front-load the main purpose and critical behavioral instruction. No redundant or extraneous content.

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, the description appropriately focuses on the critical note_url handling. It is complete for a simple read tool, though it omits error handling 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?

Schema description coverage is 100%, and the schema already provides detailed parameter semantics (24-bit hex, exact copy required). The description does not add additional parameter-level information 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 '获取' (get) and resource '单篇小红书笔记详情' (single note details). It distinguishes from sibling tools like xhs_get_note_detail_by_note_url by specifying the input parameter (note_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 context on when to preserve the returned note_url but does not explicitly state when to use this tool over alternatives. However, the parameter name implicitly differentiates it from the URL-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 and openWorldHint. The description adds critical behavioral context: note_url must be preserved verbatim including query parameters, and not to reconstruct from note_id. 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?

Description is concise with 4-5 sentences, front-loading the primary purpose. No redundant information, every sentence adds value.

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 an output schema (not shown but indicated), the description need not explain return values. It covers all necessary usage aspects for correct invocation, including URL handling constraints.

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. Description adds value by detailing the three supported formats (long link, short link, share text), going beyond the schema's description.

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

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

The description clearly states the tool retrieves single note details from Xiaohongshu using note URL, short link, or share text. It differentiates from sibling tools like xhs_get_note_detail_by_note_id which uses note 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?

Provides explicit guidance on preserving the note_url as-is and avoiding reconstruction from note_id. Implicitly suggests when to use this tool (when URL is available) vs. sibling that uses note ID, but no explicit when-not.

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

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

Beyond the readOnlyHint annotation, the description adds important details about the opaque pagination token's binding to user, note, and comment chain, and strict rules against modification, which enhances transparency.

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

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

The description is well-structured with a clear purpose followed by essential pagination rules. While thorough, it is appropriately concise for the complexity involved.

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 an output schema (not shown but indicated), the description covers the necessary behavioral aspects and pagination completely. No gaps for a retrieval tool with sub-comments.

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 crucial constraints, such as not truncating note_id and proper token handling, which are not fully captured in the schema descriptions.

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 gets secondary comments based on note_id and first-level comment_id, distinguishing it from sibling tools like xhs_get_note_comments_by_note_id which retrieves first-level comments.

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

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

The description explains when to use the tool (given note_id and comment_id) and provides detailed pagination instructions, including initial empty page_token and subsequent token passing. It implies alternatives implicitly through sibling tool names.

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

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

Annotations already mark the tool as readOnlyHint=true and openWorldHint=true. The description adds no additional behavioral context (e.g., rate limits, data freshness). With annotations covering safety, a score of 3 is appropriate as it provides no extra value but does not contradict.

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 action and resource. No unnecessary words or redundancy. Perfect conciseness.

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

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

The tool is simple with no parameters and an output schema present. The description covers the essential purpose. Completeness is high given the low complexity and available structured fields.

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

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

There are no parameters (schema coverage 100%). According to guidelines, 0 parameters earns a baseline of 4. The description adds no parameter information because none is needed.

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 verb '获取' (get) and resource '小红书搜索热榜' (Xiaohongshu search hot list). It is specific and distinguishable from sibling tools like xhs_search_notes, which is for searching notes rather than fetching a predefined hot list.

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

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

No guidance on when to use this tool versus alternatives like xhs_search_notes. The description only states what it does, without contextual usage hints or exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety and completeness. The description adds no additional behavioral context (e.g., permissions, error handling, rate limits). It adequately restates the input forms but does not go beyond annotations.

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

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

The description is a single, concise sentence that immediately conveys the core purpose. No filler or redundant information.

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

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

Given the simple input (one required param), presence of output schema, and informative annotations, the tool description is mostly complete. It lacks details on error handling or authentication needs, but these are common across sibling tools and not critical for basic 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?

The input schema already provides a detailed description of the profile_url parameter (100% coverage), including supported formats and guidance to avoid note links. The tool description merely restates the parameter input forms without adding new semantic 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 user info by supporting multiple URL forms (profile link, short link, share text), specifying the verb (get) and resource (user info). It distinguishes itself from siblings like xhs_get_user_info_by_user_id which uses a user ID.

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

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

The description implies usage when you have a profile URL, short link, or share text, but does not explicitly state when not to use it or compare to alternatives. The context is clear, but lacks explicit exclusions or alternative tool mentions.

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 no additional behavioral context, but non contradicts 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 main description is one short sentence, which is efficient for a simple tool. It could benefit from a brief note on what the output contains, but overall it's well-structured.

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 and the detailed parameter description, the tool definition is largely complete. The main description is minimal but sufficient for a straightforward query operation.

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

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

Schema coverage is 100%, and the parameter description provides extensive semantics: exact sources for the user_id, what not to pass (xiaohongshu ID, nickname, etc.), and when to use a different tool. This goes well 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?

The description clearly states the specific action (获取单个小红书用户信息) and resource (user info by user_id). It distinguishes from sibling tools like xhs_get_user_info_by_profile_url which use 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?

The main description lacks explicit usage guidelines, but the parameter description includes guidance on when to use this tool vs. the profile_url alternative, which partially 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 indicate read-only and open world behavior. The description adds critical behavioral context about page_token being opaque, bound to the specific user/note/comment chain, and the strict prohibition on modification, which goes 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 concise with two sentences: the first states the main purpose, the second gives essential pagination instructions. No unnecessary words, and the key information 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?

Given the output schema exists, the description covers input, pagination, and token handling. It lacks mention of error cases or empty results, but the core usage is well explained.

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?

Although schema coverage is 100% with descriptions, the tool description adds extra nuance: profile_url supports various formats and page_token must not be altered. This adds meaning beyond the schema descriptions.

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 gets posted notes by profile URL, short link, or share text, distinguishing it from sibling tools like xhs_get_user_posted_notes_by_user_id which uses 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 explains when to use this tool (to retrieve posted notes from a profile link) and provides detailed pagination instructions. However, it does not explicitly mention when not to use it or compare with alternatives like the user ID variant.

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 and openWorldHint, already conveying safe read behavior. The description adds critical detail about the opaque pagination token's binding and immutability, enhancing transparency beyond annotations.

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

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

Two sentences: first states purpose clearly, second covers the essential pagination rule. No extraneous information, front-loaded and efficient.

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

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

With an output schema present, the description only needs to explain behavior beyond return values. It covers the purpose and the critical pagination constraint, sufficient for a simple list retrieval tool.

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

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

Schema coverage is 100% with detailed parameter descriptions. The tool description largely repeats the pagination token behavior already documented in the schema, adding no new semantic meaning for the parameters.

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

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

The description explicitly states the tool retrieves a user's posted notes by user_id, with a specific verb and resource. It distinguishes from the sibling tool xhs_get_user_posted_notes_by_profile_url by the input method (user_id vs 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 user_id parameter description advises to use profile_url if only a profile link is available, explicitly directing to the sibling tool. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnly and openWorld hints. The description adds value by stating it does not trigger reprocessing or long waits, providing additional behavioral context 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?

Single sentence, no wasted words, clearly front-loaded with the main action and constraints.

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 status query tool with an output schema and full annotation coverage, the description is complete: it defines the scope, behavior, and what it does not do.

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% (job_id already described as '口播转文字任务ID'), so the tool description adds no new parameter-level meaning. 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 verb '查询' (query) and resource '视频口播转文字任务状态' (video speech-to-text job status), distinguishing it from sibling tools that submit jobs. It also specifies it only queries, not triggers reprocessing.

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

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

The description indicates it is for querying the status of an existing job and explicitly says it does not trigger reprocessing or long waits, providing clear context. However, it does not mention when to avoid using it or list alternatives beyond implication.

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 valuable behavioral context beyond the annotations: it mandates that the note_url must be preserved intact with all query parameters, including xsec_token. This is a critical constraint not covered by readOnlyHint or openWorldHint.

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 a clear purpose statement followed by a critical behavioral rule. It is front-loaded and every sentence serves a purpose, though the structure could be slightly improved with separation of purpose and usage notes.

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 full parameter coverage in the input schema, the description adequately covers the essential behavioral constraint (URL preservation) and the search purpose. It is sufficiently complete for an 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 description coverage is 100%, so the parameters are fully documented in the schema. The description does not add extra meaning beyond what the schema provides, except for a general statement about keyword search. 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 that the tool searches for Xiaohongshu notes by keyword, which distinguishes it from sibling tools that retrieve details, comments, or user info. The verb 'search' and resource 'notes' are specific and unambiguous.

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

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

The description does not explicitly state when to use this tool versus alternatives, such as note detail or user info tools. However, it does provide critical usage guidance on how to handle the returned note_url, which is essential for correct invocation.

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

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

With no annotations provided, the description carries full burden. It discloses key behaviors: a maximum 15-second wait and an async fallback returning job_id and next action. This is adequate for a submission tool, though it omits details like idempotency, 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?

Two sentences, zero wasted words. The critical information (action, resource, wait time, async behavior) is front-loaded and 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 simple single-parameter input and presence of an output schema, the description covers all needed behavioral context: what the tool does, what to expect, and next steps if incomplete. No gaps remain.

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

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

Schema coverage is 100% with a very detailed description for note_id. The tool description adds no further parameter information, so it meets the baseline of 3 without exceeding it.

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 (submit speech-to-text task) and resource (video note by note_id). It distinguishes from sibling tools like xhs_submit_video_speech_text_by_note_url and xhs_get_video_speech_text_job, making the tool's specific use case 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 provides clear context on the tool's behavior: waiting up to 15 seconds and returning job_id if not completed. It implies when to use this tool (when you have a note_id) versus alternatives by URL or for querying results, but does not explicitly state when not to use it or provide exclusions.

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

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

No annotations are provided, so the description carries the full burden. It discloses the asynchronous nature (wait 15s, return job_id if not done) and implies mutation. However, it does not specify authentication requirements, rate limits, or success behavior (e.g., what happens if completed within 15 seconds). It adds some behavioral context but is incomplete.

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 main purpose, and each sentence adds necessary information. No filler or repetition.

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 (one parameter, output schema exists), the description covers the submission, waiting, and polling flow. It could be more complete by explaining the distinction between URL and ID variants, but overall it provides enough context for use.

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 (note_url) has a description in the schema (100% coverage), and the tool description does not add further details beyond what the schema says. The schema description already clarifies the input formats. 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 explicitly states the action (submits a task), the resource (video note speech-to-text conversion), and implies the input (by note URL). It clearly distinguishes from the sibling tool `xhs_submit_video_speech_text_by_note_id` via the name, and the description adds the context of waiting and job_id return.

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: submit, wait up to 15 seconds, and if not completed, use the returned job_id for polling. It does not explicitly compare with the sibling tool using note ID, but the name and context provide sufficient differentiation. No exclusions or alternatives are mentioned, 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.