SocialDataX 小红书 Xiaohongshu XHS RedNote MCP

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

Annotations already declare readOnlyHint=true, and the Chinese description reinforces that this is a query operation. The description adds context about the account-level API Key scope, but it does not disclose details such as response format, rate-limit implications, or whether the balance is cached or real-time.

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 with the key information front-loaded. The bilingual repetition and enumeration of 'balance / remaining points / points' is slightly redundant but not harmful.

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 this is a zero-parameter read-only balance lookup, the description is complete. An output schema is present, so return values do not need to be described, and the annotations cover the 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?

The tool has zero parameters and schema description coverage is 100%, so there is nothing for the description to explain about inputs. The description still usefully clarifies that 'points balance' refers to remaining credits.

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 a specific action, resource, and scope: querying the SocialDataX points balance for the current API Key account. It is fully distinguishable from the unrelated zhihu_ sibling tools even without inspecting schemas.

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 intended use is reasonably implied by the name and description, but there is no explicit guidance about when to check the balance, how it relates to other tools, or when this tool would not be appropriate. No alternatives are mentioned.

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

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

Annotations already mark it as readOnly (readOnlyHint=true) and openWorld (openWorldHint=true), so the description doesn't need to repeat those. It adds valuable behavioral context by stating it retrieves only first-level comments, supports sorting (sort_type) and pagination (page_token). This goes beyond the annotations and clarifies operational scope.

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, dense sentence that front-loads the core action and key capabilities. There is no wasted wording; it conveys the essential purpose in a compact form.

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 read-only tool with an output schema, the description covers the essential behavior (comments retrieval, sorting, pagination) and clarifies scope (first-level). It does not list potential error cases or rate limits, but given the annotations and schema, these are not critical. The description 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?

Schema description coverage is 100%, with each parameter (note_id, sort_type, page_token) having detailed descriptions. The tool description itself does not add semantic meaning beyond what the schema already provides; it merely mentions the parameters by name. Baseline 3 is appropriate given the high schema coverage.

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

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

The description states a specific verb (获取) and resource (单篇小红书笔记的一级评论), and explicitly mentions sorting and pagination capabilities. It naturally distinguishes from sibling tools like xhs_get_note_comments_by_note_url (which uses URL) and xhs_get_note_sub_comments_by_comment_id (sub-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 does not explicitly state when to use this tool versus alternatives. While the parameter description for note_id implies it's for when a note_id is available, it does not contrast with the URL-based sibling or mention that this tool only handles first-level comments compared to the sub-comment tool. The guidance is implied rather than explicit.

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

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

Annotations declare readOnlyHint=true, so the read-only nature is already known. The description adds contextual detail beyond that: it specifically states that this returns only first-level (top-level) comments, not nested replies, and that it supports comment sorting and pagination via page_token. These are behavioral traits that help an agent understand scope and capabilities without contradicting 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, compact sentence that front-loads the primary action and key capabilities (URL types, sorting, pagination). Every phrase earns its place; there is no fluff or repetition. It is efficiently structured and easy to scan.

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 fairly simple with three well-documented parameters and a provided output schema, so the description does not need to explain return values. It covers the essential input forms and the fact that only top-level comments are returned. The only minor gap is the lack of explicit instructions about when to prefer this over the by_note_id variant, but the clear input requirement largely mitigates that. Overall, it is adequate for an agent to call 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 coverage is 100%, so each parameter already has a detailed description. The tool description does not add new meaning beyond what the schema provides; it merely summarizes that sorting and pagination are supported. This is redundant with the schema, so the baseline score of 3 is appropriate—the description does not compensate for any schema 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: fetch first-level comments of a single Xiaohongshu note given a note URL, short link, or share text. It also mentions sorting and pagination support, which are key features. The name itself distinguishes it from the 'by_note_id' sibling, and the description reinforces that by specifying the input forms (URL, short link, share text) rather than a note ID, making its resource and verb unambiguous.

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

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

The description implies the use case: when you have a note URL, short link, or share text, use this tool. It does not explicitly contrast with xhs_get_note_comments_by_note_id, but the clear input requirement (URL vs ID) provides sufficient context for an agent to select the appropriate tool. No exclusions are stated, but the context is clear enough to meet the 'clear context, no exclusions' bar.

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 a crucial behavioral rule beyond the readOnly/openWorld annotations: when note_url is non-null it must be preserved verbatim including query parameters, and when null no public URL should be synthesized from note_id. This is actionable, specific, and not inferable from the schema.

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 with no filler: the first states the operation, the second states the critical URL-handling constraint. Important information is front-loaded and every clause 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 one-parameter read tool with an output schema, the description plus schema covers most needs. However, it is incomplete as a selection aid because it does not differentiate the tool from the sibling xhs_pgy_get_note_detail_by_note_id, and it lacks any mention of when a URL-based alternative would be preferred.

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 note_id parameter is already described in detail in the schema. The tool description only repeats that it uses note_id and adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: '根据 note_id 获取单篇小红书笔记详情' (get single Xiaohongshu note detail by note_id), which clearly identifies what the tool does and the identifier it keys on. This naturally distinguishes it from the sibling note_url-based 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?

No guidance is given about when to choose this tool over alternatives. It does not mention xhs_get_note_detail_by_note_url for URL inputs, nor does it explain the difference from xhs_pgy_get_note_detail_by_note_id, so an agent receives no routing help beyond the tool name.

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/openWorldHint annotations, the description adds an important behavioral constraint: the returned note_url must be preserved exactly, including xsec_token, and must not be reconstructed from note_id. It also warns against synthesizing a public link when note_url is null, which is valuable execution-relevant information.

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: the first states the purpose and accepted inputs, the second front-loads the critical URL-preservation constraint. 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?

With a single required parameter, full schema coverage, readOnly/openWorld annotations, and an output schema present, the description supplies the remaining necessary operational rule (preserve note_url as-is). No critical selection or invocation information is 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 schema already provides 100% coverage of note_url's accepted forms. The description mostly restates those forms and adds a downstream URL-preservation rule rather than new input semantics, so it does not exceed the schema-documented 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 ('获取') and resource ('单篇小红书笔记详情') with the input carrier (note_url) defined as link/short link/share text. This clearly distinguishes the URL-based detail retrieval from the sibling xhs_get_note_detail_by_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?

It clearly states the intended input forms (long link, short links, share text), so an agent knows what to pass. It does not explicitly name the note_id-based alternative or state when not to use it, but the context is clear enough that only URL/ID routing remains implicit.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. It adds behavioral detail about pagination: '支持 page_token 翻页' and instructs to use the same note_id/comment_id for pagination. 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 a single, dense sentence using semicolons to separate distinct instructions. All statements are relevant: purpose, usage conditions, and pagination. No fluff, but slightly dense; could be broken into bullet points for clarity. 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?

With output schema present and full parameter documentation, description provides sufficient context: purpose, usage flow, and pagination. It does not discuss error handling or rate limits, but given read-only annotation and existing schema, this is adequate.

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

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

Schema coverage is 100% with detailed descriptions for note_id and comment_id (e.g., '不得截断、缩写、脱敏' etc.). The description adds contextual usage guidance (when to use directly vs. when to call other tools) but does not significantly augment parameter meaning beyond schema. Baseline 3 given high coverage.

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

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

The description explicitly states the tool's function: '根据 note_id 和一级评论 comment_id 获取二级评论' (get sub-comments based on note_id and first-level comment_id). It clearly distinguishes from siblings by mentioning '一级评论' and '二级评论', separating it from tools like xhs_get_note_comments_by_note_id which fetch 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?

Provides explicit when-to-use instructions: '用户已提供完整合法的 ID 组合时直接使用' (use directly when complete IDs provided), and when to call alternative tools: '已有 note_id 或笔记链接但缺少必需 ID 时，调用对应一级评论工具补全' (call corresponding first-level comment tool when missing required ID), and when to ask user: '缺少笔记定位信息时向用户索取'. This clearly routes the agent.

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 annotation already signals the read-only nature, and the description adds no contradictory side effects. It does not mention potential error cases, but the annotation sufficiently covers the primary behavioral expectation.

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, using two sentences to convey purpose and usage boundaries without redundant or extraneous 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 output schema exists (as indicated by context) and the description clarifies the tool's role among many similar xhs_* tools, the definition is complete enough for an agent to select and invoke it 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 single parameter sku_id is fully described: it must be used as provided, should be sourced from xhs_search_products items[*].sku_id, and explicitly excludes spu_id, links, and keywords. Schema coverage is 100%.

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 product details by sku_id, and explicitly differentiates from the URL-based tool by stating it does not support links, spu_id, or search terms.

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?

It explains when to use the tool (when sku_id is available) and when not to (when only links or search terms exist), directing users to the appropriate alternative tool (xhs_get_product_detail_by_url).

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 explicitly lists unsupported input types (note links, blogger pages, pure share codes, search terms), setting accurate expectations beyond the readOnly annotation. It also mentions the returned sku_id can be reused, clarifying downstream behavior.

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, direct, and free of fluff. It efficiently communicates purpose, alternatives, and downstream usage without redundancy.

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

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

The description provides sufficient context for a read-only retrieval tool: it indicates the input format, the fallback condition, and a concrete follow-up action (using sku_id for reviews), making it self-contained for agent 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 parameter description in the schema already fully covers the accepted and rejected input formats. The tool description adds little beyond that, so the baseline of 3 applies due to high schema coverage.

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

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

The description clearly states the tool retrieves product details from a product link, short link, or share text, and distinguishes it from the sku_id-based sibling tool.

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

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

Explicitly advises using xhs_get_product_detail_by_sku_id when a complete sku_id is already available, and notes that no search is needed, providing clear selection criteria among siblings.

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 annotation already signals a non-mutating read, and the description adds valuable behavioral constraints: the next_page_token must be passed back verbatim, must not be truncated or modified, and root_review_id must not be supplied. These details go beyond what the annotations alone would provide.

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

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

The description is compact, front-loaded with the core operation, and every sentence adds needed guidance. The token integrity warning is specific and directly actionable rather than filler.

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 two-parameter read-only tool with a supplied output schema, the description covers ID sourcing, parent-tool routing, first-page vs. continuation behavior, and an explicit exclusion of root_review_id. Nothing necessary for correct invocation is 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?

Schema description coverage is 100%, and the schema already documents review_id sourcing and exact page_token reuse rules. The main description mostly reinforces those rules rather than introducing new parameter-level meaning, so the baseline score 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 states a precise verb-and-resource pair: fetch replies under a top-level product review by review_id. It clearly distinguishes this tool from xhs_get_product_reviews and note-comment siblings by scoping to product review replies and rejecting root_review_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 explicitly says to use an existing review_id directly and otherwise obtain one from xhs_get_product_reviews. It also explains pagination semantics and the continuation requirement, so an agent knows exactly when and how to invoke the 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?

The description adds important behavioral detail beyond the readOnlyHint annotation, especially around pagination: the returned next_page_token must be passed verbatim as the next page_token, and pages cannot be truncated, abbreviated, masked, or replaced with ellipses. This is a concrete, actionable constraint that affects correct invocation.

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 appropriately brief and well-ordered: it states the core operation first, then explains how to obtain the ID, then the support parameters and pagination behavior, and finally which inputs are not supported. Every sentence adds useful operational 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 that an output schema exists and the annotations already signal read-only and open-world behavior, the description covers all essential invocation details: how to get the required id, how to paginate correctly, and what not to pass. No critical usage gap remains.

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 input schema already documents all parameters. The description largely reinforces the same information, such as sku_id provenance and page_token integrity, without adding significant new meaning beyond what the schema provides.

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

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

The description explicitly states the tool's function — 根据小红书商品 sku_id 获取商品评价 — giving a specific verb, resource, and identifier type. It also differentiates from other tools by stating what it does not support: 商品链接、spu_id 和搜索词, and it points to xhs_search_products as the source for missing sku_id values.

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

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

The description provides a clear usage rule: 已有该 ID 时直接使用，否则可从 xhs_search_products 获取. This tells the agent when to use this tool directly and when to first call another tool. It also gives a strong when-not cursor by rejecting product links, spu_id, and search terms as inputs.

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 does not contradict these, but it adds no additional behavioral context—e.g., whether the list updates frequently, whether it requires authentication, or what happens if the list is unavailable. With annotations covering the key traits (read-only, open world), the lack of further detail is acceptable but not enhanced.

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

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

The description is a single sentence in Chinese. It conveys the purpose efficiently without any filler. However, it could be slightly less terse if it included the English equivalent for non-Chinese agents.

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

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

Given the tool has no parameters and has an output schema, the description is sufficient for understanding the tool's purpose. The output schema presumably defines the structure of the hot list, so the description does not need to explain return values. One might wish for additional context about what 'hot list' means (e.g., trending topics, searches), but the purpose is clear enough.

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 zero parameters, so the description cannot add parameter details. With no parameters, the baseline is 4—the description is sufficient as there are no parameter semantics to elaborate.

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 the 小红书 search hot list (search hot list for Xiaohongshu). The verb '获取' (get) and resource '搜索热榜' (search hot list) are specific. Among sibling tools that focus on notes, comments, user info, products, and search results, this one uniquely addresses the hot list, providing good differentiation.

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 this should be used when an agent or user wants the current trending/search hot list from Xiaohongshu. However, it does not explicitly state when to use this versus alternatives (e.g., when to prefer this over search functions like xhs_search_notes). No exclusions or context about frequency or user need are given.

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 safety profile is covered. The description adds that the call supports sorting and pagination, which is mild behavioral context, but it does not go beyond that with e.g. what happens on invalid page_id, data volume, or the meaning of open-world results.

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 front-loaded sentence: core action and identifier first, then the two capability notes. Every word earns its place, and there is zero redundant restatement of the tool name or schema fields.

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 read-only list tool with 3 parameters (1 required), a full output schema covering return values, and annotations covering safety, the description is adequate. The one meaningful gap is not referencing xhs_get_topic_notes_by_topic_url so the agent can route by identifier type (page_id vs topic_url), though the sibling names largely communicate this.

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 page_token schema description is exceptionally detailed (opaque token, no reuse across page_id/sort, no modification). The tool description merely mentions sort_type and page_token by role, adding no meaning beyond what the schema already provides, so the high-coverage baseline of 3 applies.

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

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

The description states a specific verb + resource: '获取标签页笔记列表' (get tag page notes list) keyed by page_id, plus the two capabilities sort and pagination. It is clear but does not explicitly differentiate from the very close sibling xhs_get_topic_notes_by_topic_url; the distinction is left to the tool name rather than stated in the description.

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 phrase '根据 page_id' implies the tool is for cases where the agent holds a page_id, and the pagination rules are well documented in the page_token schema description. However, the description never explicitly says when not to use it nor names the URL-based alternative, so routing guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds only that sorting and pagination are supported, which is already visible in the schema; it contributes little extra 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?

A single sentence states the purpose and key capabilities with no filler. Every element in the description 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?

With a full input schema, output schema, and read-only annotations, the description is sufficient for an agent to select and invoke the tool correctly. It could add an explicit pointer to xhs_get_topic_notes_by_page_id for page-ID scenarios, but that is a routing nicety, not an invocation gap.

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

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

Schema description coverage is 100%, so the schema already documents topic_url formats, sort_type enum, and page_token behavior. The description only restates that sorting and pagination are supported, adding no new meaning beyond the schema.

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

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

The description states a specific verb and resource: it fetches the topic notes list from a topic URL, short link, or share text. This also differentiates it from the sibling xhs_get_topic_notes_by_page_id, which uses a page ID instead of a 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 makes the intended trigger explicit: use this tool when the caller has a topic page link, short link, or share text. It does not mention the page_id alternative or state exclusions, so it misses the full '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 readOnlyHint=true (safe read) and openWorldHint=true (results may vary). The description adds valuable behavioral context beyond annotations: it clarifies that the tool accepts multiple URL formats and share text, and explicitly prohibits note links. No contradictions with annotations.

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

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

The description is a single sentence that directly states the tool's purpose and input options. It is concise and front-loaded, with no wasted words. Could slightly improve by adding a brief usage hint, but overall 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 tool's low complexity (one parameter, output schema present, annotations provided), the description is fully adequate. It specifies the allowed input formats and what to avoid, while the output schema covers return values. No gaps remain for an agent to use this 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 input schema covers 100% of parameters, with a detailed description of the 'profile_url' parameter. The tool description repeats the supported formats but adds no new semantic meaning beyond what the schema already provides. 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 identifies the action ('get') and resource ('single Xiaohongshu user info'), and specifies the input type (profile link, short link, or share text). This distinguishes it from sibling tools like 'xhs_get_user_info_by_user_id' (which takes a user ID) and 'xhs_get_user_posted_notes_by_profile_url' (which retrieves notes, not user info).

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 implicitly suggests usage when a profile URL is available, and the schema explicitly warns not to pass note links. However, it does not explicitly compare to alternatives or state when to use this tool versus 'xhs_get_user_info_by_user_id' or other siblings. The guidance is present but not explicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation in an open world. The description itself adds no further behavioral context (e.g., error handling, rate limits), but this is acceptable given the annotations cover the safety profile. No contradiction exists.

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 tool's purpose. There is no extraneous information, and all additional guidance is appropriately placed in the schema, keeping the description lean and 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?

The tool has a single parameter fully documented in the schema, annotations declare safety traits, and an output schema exists so return values are separately specified. The description is complete for a simple, read-only lookup tool—nothing an agent needs to call it correctly is 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?

Schema description coverage is 100%, and the user_id parameter is thoroughly documented with a description explaining origin, alternatives, and exclusions. The tool description adds no additional parameter semantics, but the schema already carries the full burden, 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 '根据 user_id 获取单个小红书用户信息' clearly states the action (get) and resource (single Xiaohongshu user info) and specifies the input method (by user_id). It distinguishes itself from the sibling tool xhs_get_user_info_by_profile_url via the parameter schema's note about using profile_url for home page links, so an agent can tell them apart.

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

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

The parameter description explicitly provides usage guidance: it instructs to use user_id as-is when provided, where to copy it from other results, and specifically says '如果只有主页链接，请使用 profile_url 入口' (if only home page link, use profile_url), while also warning against using Xiaohongshu number, nickname, or homepage name. This clearly routes the agent to the correct tool and 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 mark the tool as readOnlyHint and openWorldHint, so the safety profile is established. The description adds that the operation supports page_token pagination, which is a behavioral trait beyond the annotations. However, it does not disclose ordering, visibility of returned notes, rate limits, or response behavior beyond pagination, and the deeper token constraints live in the schema rather than the description.

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 verb, resource, and accepted input forms, then states pagination support. It is concise, scannable, and contains no redundant filler.

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 a detailed input schema, an output schema, and readOnly/openWorld annotations, the tool definition is largely sufficient for correct invocation. The only notable gap is the absence of explicit guidance for choosing between this tool and closely related siblings, though the tool name and parameter type make the decision mostly unambiguous.

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%: profile_url documents long links, short links, and share text, and page_token fully documents the opaque, same-user-only, must-be-returned-unmodified rules. The description only restates the accepted link forms and pagination support, adding no new parameter meaning beyond the schema.

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

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

The description clearly states the action (获取, 'get'), the resource (用户已发布笔记列表, 'list of user's published notes'), and the accepted input forms (主页链接/短链接/分享文案). It also mentions page_token pagination. The input-type distinction differentiates it from sibling xhs_get_user_posted_notes_by_user_id even without naming it.

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 use when the agent has a profile URL, short link, or share text and needs a user's published notes. The profile_url parameter additionally instructs '不要传笔记链接' (do not pass note links), which is a useful exclusion. However, there is no explicit mention of when to prefer this tool over siblings like xhs_get_user_posted_notes_by_user_id or xhs_get_user_info_by_profile_url, leaving alternative selection to inference.

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?

注解已声明 readOnlyHint=true 和 openWorldHint=true，说明这是只读操作且结果可能超出已知集合。描述额外补充了翻页行为：首次留空、后续必须传回完整 next_page_token，且令牌不能跨用户复用、不得修改。这些对 agent 正确调用很重要。但描述未提及返回结构或可能的错误情况，考虑到注解已覆盖安全性，评分为 3 合理。

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?

描述一句话点明核心功能，简短高效。关键的使用规则（翻页）放在描述中，而详细参数语义放在 schema 中，整体结构合理。唯一不足是描述没有提及与 profile_url 版本的区别，但参数说明中已补充，不影响简洁性评分。

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?

工具复杂度中等，有输出 schema 且注解完整，描述已覆盖核心调用方式（user_id + 翻页）。缺少的可能是对返回字段的简要说明，但输出 schema 已承担该职责。考虑到 openWorldHint=true，描述不需要列举所有可能结果，整体对 agent 正确调用已足够。

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 为 100%，两个参数在 schema 中已有详细说明，尤其是 user_id 的来源优先级和 page_token 的完整使用规则。描述本身没有在 schema 之外增加新的参数语义，因此按高覆盖基线评 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?

描述明确说明通过 user_id 获取用户已发布笔记列表并支持 page_token 翻页，动词和资源清晰。与兄弟工具 xhs_get_user_posted_notes_by_profile_url 形成明确区分，一个按 user_id、一个按 profile_url，agent 无需打开 schema 即可区分。

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?

描述虽未直接写'当有其他入口时用哪个'，但结合 user_id 参数说明中的详细指引（用户已提供则原样使用；否则可从其他结果复制；只有主页链接时用 profile_url 入口），隐式给出了与 xhs_get_user_posted_notes_by_profile_url 的选择依据。缺少明确的'何时不用'声明，但上下文已足够指导选择。

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 and openWorldHint annotations, the description discloses the blocking wait behavior ('每次最多等待 240 秒' - wait up to 240 seconds each time) and the idempotency traits (no re-processing, no re-submission). These are valuable behavioral details not captured by annotations. It does not describe what happens on timeout, but the output schema covers return structure.

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

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

The description is a single, well-structured sentence that front-loads the primary action and then adds usage, timeout, and exclusion guidance. It is dense but not verbose, with every clause earning its place. A 4 reflects that it is efficient while slightly dense; could be split for readability but is far from under-specified.

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 there is an output schema, the description adequately covers the essential operational context: when to use, the blocking wait, and explicit prohibitions against resubmission and re-processing. It implies repeated calls are allowed ('每次最多等待' - each time). No critical information for correct invocation is missing, making it complete enough.

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 and already thoroughly explains the job_id parameter, including instructions on sourcing it from the user or submission tool and not passing note_id. The description essentially repeats this without adding new semantics. Baseline 3 is correct since the schema does the heavy lifting.

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

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

The description clearly states the action: '查询任务状态' (query task status) for a specific resource, the job_id. It explicitly mentions it is used to continue unfinished tasks, which distinguishes it from the sibling submission tools (e.g., xhs_submit_video_speech_text_by_note_id). The purpose is unambiguous and specific.

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

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

The description provides clear when-to-use context: '用于继续未完成任务' (used to continue unfinished tasks). It also gives exclusions: '不要重复提交任务' (do not resubmit tasks) and '不触发重处理' (do not trigger re-processing), implicitly steering the agent away from the submission siblings. However, it does not explicitly name the alternative submission tools, so a 4 is appropriate rather than 5.

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?

Discloses the 20-point cost on success and no charge on failure, the specific pgy_commercial_data_unavailable error for missing commercial data, and clarifies that timeout/auth/balance errors do not mean the blogger is not joined. These details go beyond the readOnlyHint and openWorldHint 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 dense but every sentence adds essential information: purpose, scope, clarification rules, cost, and error handling. No redundant phrases or vague filler; the structure flows logically from what to when to how.

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 complexity—cost model, error code semantics, sibling tool differentiation—the description covers all critical operational aspects. Output schema is present, so return-value details are not required. The description fully equips an agent to call and interpret the result 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 input schema already provides 100% coverage with a detailed description of note_id, including rules against truncation or reformatting. The tool description itself adds no parameter-specific semantics beyond what the schema already states, so the baseline of 3 applies.

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

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

Description clearly states the tool fetches Pugongying commercial enhanced note details by note_id, lists included fields (text, image/video summary, author, exposure, reads, interactions, quotes), and distinguishes from the ordinary detail tool by explicitly naming the alternative usage.

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

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

Explicitly specifies when to use: only for notes from Pugongying-joined bloggers and when user explicitly requests commercial data; ordinary notes should use the normal detail tool. Also provides clarification rules for ambiguous requests and states not to retry when commercial data is unavailable.

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 transparently discloses cost, failure charging, special return values, and retry guidance, but it directly contradicts the annotation readOnlyHint=true by stating that a successful call deducts 20 points. Deducting points is a state-modifying side effect, so the description conflicts with the read-only annotation.

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 and dense with useful operational information, covering functionality, applicability, cost, error semantics, and retry policy. It is slightly repetitive in emphasizing the distinction from ordinary public note details, but overall every sentence contributes 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?

The description provides complete operational context: what data is returned, when to use the tool, cost and failure conditions, the meaning of pgy_commercial_data_unavailable, and how to handle timeout, auth, and balance errors. An agent has enough information to invoke it correctly and handle edge cases.

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 single parameter note_url is fully described, including supported long links, short link domains (xhslink.com, xhsurl.com, etc.), and full share text containing such links. This adds practical parsing details beyond the schema and leaves no ambiguity about acceptable input formats.

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 fetches Pugongying commercial enhanced note details from note links, short links, or share text. It explicitly distinguishes this tool from ordinary note detail retrieval and from the by-note-id variant, so an agent can select it correctly.

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 gives explicit when-to-use guidance: use only for Pugongying commercial data when the user explicitly requests it, and use the ordinary detail tool for normal notes. It also instructs the agent to clarify the commercial caliber and the 20-point cost when context is ambiguous, and not to reconfirm when context is already clear.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses critical behavioral constraints: the full next_page_token must be passed back unmodified, and returned note_url values must be preserved completely including xsec_token. It also warns against reconstructing URLs from note_id, which is valuable behavioral context an agent would not otherwise know.

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 efficient and front-loaded with the core purpose, followed by routing and critical pagination/URL constraints. It is slightly repetitive around the paging and URL-preservation warnings, but every sentence contributes operational 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?

For a search tool with a full input schema, an output schema, and annotations already covering read-only/open-world behavior, the description covers the main usage scenario, alternative-tool routing, pagination behavior, and URL integrity requirements. No critical operational gap is visible.

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 adds meaningful extra guidance for keyword, such as not passing note links, user IDs, or page_token, and reinforces the page_token chaining rule. This goes beyond the schema without needing to repeat enum documentation.

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 starts with a specific verb and resource: “搜索小红书 / Xiaohongshu / XHS / RedNote 相关笔记”, which states exactly what the tool does. It also distinguishes this tool from detail, comment, and transcription tools by explicitly saying that those cases should use corresponding URL/ID 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 clearly says to use this tool when the user needs to search by keyword, and explicitly redirects note-detail and comment/transcription needs to sibling tools. It does not explicitly contrast with xhs_search_products or xhs_search_suggestions, but the overall wording makes the note-search scope clear enough.

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

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

The description adds behavioral context beyond the readOnlyHint annotation by explaining the pagination mechanism and the strict rule to not modify the next_page_token. This is useful for correct usage and aligns with the read-only nature, with no contradictions.

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

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

The description is concise, consisting of two focused sentences: the first states purpose and alternatives, the second explains pagination. It is well-structured and front-loaded with the primary purpose, with no unnecessary 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 tool with only two parameters and an existing output schema, the description covers all necessary context: purpose, when to use, alternatives, and pagination handling. It is complete for the agent to 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?

The schema already provides comprehensive descriptions for both parameters (keyword and page_token), covering their meaning and usage constraints. The tool description adds little beyond this high-coverage schema, so the 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 searches Xiaohongshu products by keyword, and distinguishes it from sibling tools by explicitly specifying when to use this tool (when searching by keyword) versus when to use product detail/review tools (when having sku_id) or xhs_get_product_detail_by_url (when having a product link).

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 conditions for using this tool over alternatives, and gives clear instructions on pagination using page_token, including the requirement to pass the complete token unchanged. This fully guides the agent on when and how to invoke the tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the tool's safety and open-world nature are covered. The description adds that it returns 'candidate search suggestions', but does not elaborate on specific behaviors such as response format or limitations. This adds some but not rich context, aligning with baseline given annotations.

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

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

The description is a single, compact sentence that both defines the tool and differentiates it from alternatives. No wasted words, and the core 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?

With a simple single-parameter tool, an output schema exists, and annotations cover read-only/open-world, the description is complete enough. It clearly states the purpose, usage, and exclusions. It does not address potential response times or error conditions, but these are not necessary for a tool of this simple nature and the presence of output schema reduces that need.

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 explicitly instructs what to pass (keyword or phrase being typed) and what not to pass (links, IDs, tokens). The description reinforces the schema, but also clarifies the intended input type (being typed) beyond the generic 'search term'. This adds practical guidance, slightly above baseline.

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

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

The description clearly states the tool retrieves candidate search suggestions based on the search term, with the explicit purpose 'to complete search terms'. It distinguishes itself from xhs_search_notes and xhs_search_products by naming them as alternatives for actual searches, making it clear what this tool does not do.

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 covers when to use the tool (for completing search terms) and when not to use it: when the user needs to actually search notes or products, directing to xhs_search_notes or xhs_search_products. This provides clear context and alternative tools, leaving no ambiguity.

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 this is a mutating, non-idempotent operation. The description adds valuable behavioral details: it waits up to 240 seconds, returns a job_id when incomplete, and tells the agent to perform a follow-up query. It does not contradict any annotations; the added info is complementary.

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

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

A single sentence that front-loads the action and then states the waiting behavior and the fallback return. No filler words; every clause carries information.

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

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

With one parameter, an output schema present, and sibling tools for follow-up, the description covers the essential workflow: submit, wait, and query next. It does not explicitly name the exact follow-up tool, but the mention of a 'next query action' is sufficient for an agent to infer the step, especially with sibling visibility.

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 for note_id is highly detailed (100% coverage), specifying how to obtain it and what not to do with it. The tool description adds no additional parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('submit'), a clear resource ('video note speech-to-text task'), and the identifier type (note_id). It also distinguishes from the sibling tool that uses note_url, making the purpose unambiguous and separable from the other submission tool.

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 use when you have a note_id, but does not explicitly mention the alternative (xhs_submit_video_speech_text_by_note_url) or when to choose one over the other. It provides no explicit usage exclusions, but the sibling tools are visible to the agent, so the context is partially inferred.

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 flag this as a write operation (readOnlyHint=false, idempotentHint=false). The description adds valuable behavioral detail beyond annotations: it explicitly mentions a 240-second wait and that an incomplete job returns a job_id and points to a next query action. This goes beyond the structured hints and clarifies the asynchronous nature of the task.

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, dense sentence that front-loads the core action (submit task by note URL) and immediately covers the key constraints (wait time, job_id return). Every phrase earns its place; there is no filler 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 available output schema (not shown but indicated), the description provides sufficient context: it states the input format, the asynchronous wait, and the follow-up query action. It does not explicitly name the polling tool (e.g., xhs_get_video_speech_text_job), but the existence of such a sibling and the mention of 'next query action' make the workflow clear. Minor gaps like error handling or idempotency advice are not critical given the annotations.

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 parameter note_url is fully documented. The tool description repeats the same input formats (link, short link, share text) without adding new syntax details. With schema doing the heavy lifting, a 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 (submit a video speech-to-text task), the resource (Xiaohongshu video note via URL, short link, or share text), and distinguishes it from the sibling by_note_id variant. It also outlines the wait/response behavior, leaving no ambiguity about the tool's purpose.

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 (it is a submission task triggered by a note URL), but it does not explicitly state when to prefer this over the by_note_id sibling or exclude other tools. However, the naming and input type make the usage context obvious enough for an agent to infer the appropriate choice.

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