SocialDataX 知乎 Zhihu MCP

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

Annotations already declare readOnlyHint=true, and the description reinforces that this is a read-only balance query. It adds useful context by tying the balance to the current API Key and pointing to the billing dashboard for recharges. No contradictions or hidden side effects are indicated.

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

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

The description is two short sentences: the first states the core purpose, and the second provides an actionable billing link. Every word earns its place without unnecessary detail.

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 zero-parameter, read-only balance query with an output schema, annotations, and a billing link, the description is fully sufficient. No additional information is needed 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 tool has zero parameters Belarusand schema coverage is 100%, so parameter semantics are not a burden on the description. The description still adds value by explaining what the returned balance represents.

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 (query) and resource (current API Key account's SocialDataX points balance), including Chinese and English terms. It is unambiguous and obviously distinct from the YouTube-focused sibling 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 identifies the exact context: querying the balance for the current API Key accounttons. It also provides a relevant follow-up URL for recharging. There are no competing sibling tools for balance checking, so no explicit alternatives are needed.

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 已表明这是只读操作，描述与此一致，并额外补充了条件分支行为、参数复用链路和分页能力。虽然没有涉及速率限制或错误行为，但对于一个只读查询工具，描述已经提供了足够的行为上下文。

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?

开头一句直接点明核心用途，后续用分号列出条件分支，信息密度高且没有冗余。每个分句都承载决策或操作信息，结构清晰。

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?

对于 3 个参数、有输出 schema、有只读注解的工具，描述覆盖了直接调用、缺失参数时的回退流程、需要向用户追问的场景以及分页继续的方法。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?

input schema 覆盖率为 100%，参数描述本身已经很详细；描述额外说明了 content_url 与 comment_id 之间的配合关系、如何从 zhihu_get_content_comments_by_url 的返回值中获取 comment_id，以及 page_token 必须原样用于同一链路。

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?

描述明确说明该工具根据知乎内容页链接和一级评论 ID 读取评论回复，动词和资源都很具体。它还与兄弟工具 zhihu_get_content_comments_by_url 形成区分：本工具处理的是评论回复，而非一级评论列表。

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

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

描述明确给出了完整决策流程：用户已提供 content_url 和 comment_id 时直接使用；缺少 comment_id 时调用 zhihu_get_content_comments_by_url 并复用同一 content_url 和 items[*].comment_id；缺少内容定位信息时向用户索取；还说明了 page_token 的翻页使用方式。

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 signal readOnlyHint=true, and the description adds meaningful behavioral context: it returns only first-level comments, supports sort_type ordering, and uses page_token for pagination. These traits go beyond the annotation safety profile. However, it does not mention auth prerequisites, rate limits, or invalid-URL behavior, so it stops short of full disclosure.

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 core action and resource, then briefly mentions sorting and pagination. Every clause earns its place; there is no filler, redundancy, or unnecessary verbosity.

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

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

Between the detailed parameter schema, the output schema, and the read-only annotations, an agent has almost everything needed to call this tool correctly. The only missing piece is explicit routing to sibling tools, which is already accounted for under usage guidelines. For a read-only paginated comment fetcher, this is sufficiently complete.

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

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

Schema description coverage is 100%, with highly detailed parameter descriptions covering page_token opacity rules and content_url format restrictions. The tool description merely restates that sort_type and page_token are supported, adding no new semantic detail beyond the schema. 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 opens with '根据知乎回答页...链接读取一级评论', naming a concrete action (read first-level comments) and specific resource types (answer pages, column articles, independent videos). The qualifier '一级评论' clearly distinguishes this tool from the sibling zhihu_get_comment_replies_by_url, which handles nested replies. This satisfies the specific-verb+resource and sibling-differentiation criteria.

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

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

The description implies when to use the tool (when you have a Zhihu content URL and want first-level comments), but it never explicitly states conditions or alternatives such as 'for replies, use zhihu_get_comment_replies_by_url.' The content_url parameter description adds URL-type restrictions, but that is about parameter shaping, not tool selection. Usage guidance remains 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 already declare readOnlyHint=true and openWorldHint=true, covering the read-only nature of the operation. The description adds useful scope by enumerating supported page types, but does not discuss other behavioral aspects such as rate limits, errors, or response shape; the output schema and annotations cover much of the remaining burden.

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?

One concise, front-loaded sentence conveys the action and all supported content types without filler. It is easy to scan and immediately actionable for an agent.

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, combined with the read-only annotations, detailed input schema, and presence of an output schema, provides enough information for an agent to correctly select and invoke the tool. There is no critical missing operational guidance.

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

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

Schema description coverage is 100% and the content_url parameter has a very detailed explanation of accepted URL formats, prohibited input types, and how to pass URLs from search results. The description itself only says 'by URL', adding no parameter semantics beyond what the schema already provides.

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

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

The description uses a specific verb ('读取详情') and names the three supported resource types (answer pages including video answers, column articles, and standalone videos). This clearly distinguishes it from sibling tools focused on comments, user profiles, hot lists, and transcription jobs.

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 clear: pass a supported Zhihu content URL to get its details. The schema adds strong input constraints, but the description itself does not explicitly compare against sibling tools or state when not to use it, so it relies on context rather than explicit exclusion 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 and openWorldHint=true, covering the safety profile. The description adds that the data is current and enumerates returned fields, but it does not disclose details like ordering, pagination, list size, or potential dynamic behavior beyond 'current'. Given the annotation coverage, this is adequate but not rich.

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

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

A single succinct sentence that front-loads the action and resource, then specifies the exact return payload. There is 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?

With no parameters, an output schema present, and annotations covering safety and open-world behavior, the description provides all necessary context for an agent to invoke the tool correctly. Return values are also summarized, so nothing essential 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 tool has zero parameters, so the schema imposes no burden. Baseline for zero parameters is 4, and the description correctly focuses on the output rather than inputs. No additional parameter semantics are 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?

The description states a specific verb ('读取', read) and resource ('知乎热榜', Zhihu hot list), and explicitly lists the returned fields: question title, heat, answer count, and link. This clearly distinguishes it from sibling tools like zhihu_search_content or content-detail tools, as it targets the aggregate hot list rather than individual content or user data.

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

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

The description makes the context obvious: call this tool to get the current Zhihu hot list. It does not explicitly name alternatives or exclusions, but none of the sibling tools serve the same hot-list purpose, so the intended use is clear without needing to contrast against them.

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，描述中'读取'与注解一致，无矛盾。描述未增加额外的行为细节（如权限、速率限制），但鉴于注解已覆盖安全性，此分数合理。

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?

描述仅一句话，无冗余信息，直接点明核心操作，符合简洁高效的标准。

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?

工具只有一个参数，模式已详尽说明，且有输出模式和注解，描述足以让代理正确调用。对于此类简单工具，信息完整。

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?

模式中profile_url的描述覆盖率达100%，详细说明了可接受的输入类型和复用方式。描述本身未添加参数语义，但依据规则，高覆盖率时基线为3，故维持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?

描述以明确的动词'读取'和资源'公开博主资料'清晰陈述了工具功能，与名称高度一致。虽然没有明确提及兄弟工具，但通过名称和上下文可推断其与获取评论、文章等工具的区分，故扣1分。

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?

描述本身未说明何时使用，但输入模式中的参数描述提供了具体的使用场景（如从搜索结果复用profile_url），隐含了适用的上下文。缺少明确排除其他工具或替代方案的指引，故评为3。

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 covers the safety profile. The description adds meaningful behavioral details beyond the annotation: it returns only articles (not answers, thoughts, or videos) and supports pagination via page_token. This is useful context for an agent deciding whether this tool fits 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 two short sentences, front-loaded with the core action and its filter, and ends with the pagination note. No redundant or fluff content; every part 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 detailed schema (100% parameter coverage), annotations, and presence of an output schema, the description covers the essential purpose and return filter. It does not discuss error conditions or edge cases, but those are not critical for correctly invoking the tool.

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

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

Schema description coverage is 100%, with thorough parameter descriptions for profile_url and page_token. The tool description itself adds no additional parameter semantics beyond what the schema already provides, 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 clearly states the tool reads a user's published article list from their profile URL, and explicitly excludes answers, thoughts, and videos, distinguishing it from sibling content tools. This is a specific verb-resource pairing with a precise scope.

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 tool implies when to use it (retrieving articles for a user) but does not explicitly name sibling alternatives or specify when-not-to-use. The schema parameter description provides guidance on chaining from search results, but the tool description itself lacks explicit routing relative to other zhihu_get_* tools.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds useful behavioral context: each call waits up to 240 seconds, does not trigger reprocessing, and should not be used to resubmit. This is meaningful beyond the annotations, though it does not detail timeout error handling or pagination-style progression.

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

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

The description is a single compact sentence that front-loads the purpose and then adds the operational constraints. 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?

For a single-parameter read-only job-status tool with an output schema, the description covers the input source, the waiting behavior, and the important no-resubmission/no-reprocessing rules. Nothing critical is missing for an agent to 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 input schema already provides 100% coverage for the single job_id parameter, including its source and the reuse rule. The tool description reinforces these semantics but does not add significant parameter-specific 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 action and resource: querying a Zhihu video speech-to-text task by job_id. It clearly distinguishes itself from the sibling submit tools by referencing job_ids returned by them and framing the operation as a query rather than a submission.

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

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

It explicitly states when to use the tool: when a valid user-provided job_id exists or when a job_id was returned by a submit tool. It also gives a clear exclusion: do not resubmit or trigger reprocessing, which helps the agent choose this polling/query tool over re-submitting.

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 safety is covered. The description adds scoping context (公开内容/public content only) and notes page_token pagination support, which are useful behavioral traits. However, it does not go deeper (e.g., token expiry, rate limits, or that a videoanswer result is returned under video filter — though that detail is in the schema). Modest value beyond annotations.

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

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

Front-loaded with the core purpose, then usage routing, then capability summary; every clause earns its place and there is zero filler. Slightly dense as one continuous sentence block, but efficient overall.

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 5-parameter tool with 3 enums, an output schema, and 11 siblings, the description covers purpose, when to use, when-not-to-use with named alternatives, and available filters/pagination. The output schema covers return values, so no need to restate them. Complete enough for selection and correct invocation, though the dense single-sentence structure is the only minor weakness.

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

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

Schema description coverage is 100% with detailed descriptions for all 5 parameters, including the opaque-token contract for page_token and enum meanings for sort_type/content_type/publish_time_range. The description only summarizes these at a high level, so baseline 3 applies; it adds no semantics beyond the schemas

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?

States a specific verb and resource ('按搜索词搜索知乎公开内容') and names the alternatives it is not: URL-based detail/comment tools for existing page links, and user profile/article-list tools for profile links. An agent can clearly distinguish it from the 10+ sibling tools without opening 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?

Explicitly states when to use ('用户需要按搜索词查找内容时') and when-not: when the user already has answer/article/video page links, or a profile link, it routes to the corresponding sibling tools. This is explicit when/when-not with alternatives named.

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, and the description's '获取' is consistent with a read-only operation with no annotation contradiction. The description adds a scope constraint (suggestions only, not full search), which is useful. However, it adds no context about result limits, pagination, or failure modes; the presence of an output schema lowers that burden but does not eliminate it.

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 action and purpose front-loaded, followed by a short exclusion clause. Every element earns its place — purpose, trigger, and scope boundary — with zero filler or redundant wording.

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 single-parameter, read-only tool with 100% schema coverage, a present output schema, and safety annotations, the description covers purpose, trigger, and exclusions adequately. The only modest gap is not naming the exact alternative tools for the excluded cases, which is minor given the low complexity and the descriptive sibling names.

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

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

Schema description coverage is 100%, and the schema itself already provides strong parameter guidance — keyword is described as '搜索关键词或短语' plus explicit prohibitions on links, user IDs, and page_token. The description's '根据关键词' merely restates the parameter name without adding meaning beyond the schema. With the schema doing the heavy lifting, 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 uses a specific verb and resource combination (获取/获取知乎搜索输入框联想词 — get Zhihu input-box suggestion words), which unambiguously states what the tool does. The exclusion clause '不用于搜索用户或内容' explicitly differentiates it from the sibling tools zhihu_search_content and zhihu_search_users. An agent can identify the tool's function and its boundaries without opening the 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?

The description states the trigger condition — wanting keyword-based suggestion words — and explicitly rules out user/content search via '不用于搜索用户或内容'. This gives clear when-not guidance and implicitly points toward the search_content and search_users siblings, but it stops short of naming those alternatives by tool name, so the routing is not fully 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?

注解已声明readOnlyHint=true和openWorldHint=true，描述没有与之矛盾。描述额外说明了page_token翻页这一行为特性，但对返回格式、分页细节等未提及。由于有输出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?

描述仅两句话，第一句点明核心功能，第二句给出使用条件，第三句说明翻页。信息密度高，没有冗余，且关键信息前置。

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描述返回结构，注解覆盖只读属性，描述提供了足够的场景区分和翻页指导。代理可以准确判断何时使用此工具以及如何正确调用，没有遗漏关键信息。

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对两个参数的描述已非常详细（keyword禁止传链接/ID，page_token说明首页留空和跨能力不可用），覆盖率达100%。描述本身没有增加超出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?

描述明确说明工具用途是'按关键词搜索知乎用户'，动词+资源清晰，且与兄弟工具区分（zhihu_search_content用于内容搜索，zhihu_get_user_info_by_profile_url用于获取用户资料）。还特别指出已有主页链接时用其他接口，进一步明确了边界。

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

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

描述直接给出使用条件：已有用户主页链接时应调用用户资料接口，隐含了本工具适用于无链接时按关键词搜索。同时提到支持page_token翻页，让代理知道如何处理分页。虽然没有列出所有兄弟工具，但关键替代方案已明确。

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 convey non-read-only, non-idempotent, non-destructive behavior. The description adds the useful async behavior: it waits up to 240 seconds and, if incomplete, returns job_id and the next query step. This goes beyond annotation data and gives an agent a realistic model of the call's outcome.

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: it front-loads the main action and then gives the key async behavior. No filler or redundant phrasing.

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

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

For a one-parameter submission tool with a detailed schema and an output schema, the description covers initiation, wait behavior, and incomplete-job handling. It also tells the agent what to do next if the job is not finished, so nothing critical 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 property description already fully documents accepted URL formats and exclusions. The tool-level 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 names a specific action (submit speech-to-text transcription) and a specific resource (Zhihu standalone video page or video answer page link). It clearly differentiates from the sibling zhihu_submit_video_speech_text_by_zvideo_id by targeting URL-based input rather than zvideo 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 states when to use this tool: with a standalone video URL or a video-bearing answer URL. It explicitly lists unsupported inputs (plain answers, articles, question pages, profiles, interfaces, short links, and numeric-only IDs), giving clear exclusions. It does not explicitly name the sibling alternative for zvideo_id-only inputs, but the accepted formats imply the distinction.

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 only indicate non-readonly, non-idempotent, non-destructive, open-world. The description adds meaningful behavior: submission may wait up to 240 seconds and, if incomplete, returns a job_id plus a follow-up query action. This async/timeout behavior is not visible in 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 compact sentence front-loads the core action and then adds the two key behavioral facts (240s wait, job_id/next step). 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?

For a one-parameter async submission tool with an output schema and sibling get-job tool, the description covers the important operational details: input type, wait limit, and fallback job_id. It is slightly non-specific about the exact next query action/tool name, but the sibling list makes this recoverable.

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 zvideo_id parameter is already well documented with source, numeric-string constraint, and exclusions. The tool description adds no parameter details beyond the schema, so baseline 3 applies.

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

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

The description states a specific action (submit speech-to-text task) and resource (Zhihu standalone video identified by zvideo_id), plus the async wait behavior. It is clear, but it does not explicitly differentiate from the sibling zhihu_submit_video_speech_text_by_video_url by naming the alternative or stating 'use this when you have a zvideo_id, not 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 context is implied rather than stated: it is for submitting via zvideo_id, and '未完成时返回 job_id 和下一步查询动作' hints at polling with the get-job sibling. The schema's parameter description warns not to pass video links/answer/article/question IDs, but the main description does not explicitly say when to prefer this tool over the by_video_url sibling or how to proceed beyond a vague 'next query action'.

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