SocialDataX 今日头条 Toutiao 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and external-source profile is covered. The description adds that results include upstream heat metrics, which is useful, but says nothing about freshness, caching, rate limits, or auth needs for a live trending feed.

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 that states the resource first and the payload second, with 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 zero-parameter read tool with an output schema and readOnly/openWorld annotations, the description covers purpose and the shape of the return adequately. Only live-feed traits such as update cadence are left unspecified, which is a minor 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?

The tool takes zero parameters, so the baseline is 4; there is nothing parameter-related for the description to explain or omit.

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 verb and resource ('读取今日头条热搜榜') and states what is returned ('热门关键词及上游热度信息'), which is enough to separate it from the post/user/comment siblings. It stops short of explicitly contrasting with near-sounding siblings like toutiao_search_suggestions or toutiao_search_posts.

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?

Usage is only implied: the description says it reads the hot search list, so an agent can infer this is for trending/keyword discovery rather than targeted retrieval. There is no explicit when-to-use, when-not, or routing to an alternative sibling.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: pagination follows Toutiao's default order and continuation pages reuse the same comment_id. It omits rate limits/auth, but the incremental disclosure is solid.

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 compact clauses, front-loaded with the read/scope statement followed by the ID and pagination constraint. Dense but every clause carries meaning; only minor repetition with the schema keeps it from a 5.

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

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

With an output schema present and annotations covering the safety profile, the description only needs to add the pagination/ID semantics, which it does. Complete enough for an agent to call correctly, though it could note the parent-child relationship to the comments-by-post tools.

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 both comment_id and page_token are fully documented in the schema, including the warning against passing the reply item's own ID. The description largely restates the schema's guidance, 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?

States a specific verb+resource ('读取指定一级评论下的回复') plus the ordering/pagination behavior, which is enough to tell it apart from sibling tools like toutiao_get_post_comments_by_post_id (comments on a post, not replies under a comment). An agent knows exactly what this returns.

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 correct-usage instructions for obtaining the comment_id and maintaining it across pages, but never states when to prefer this tool over the nearby get_post_comments_by_post_id or get_post_comments_by_url siblings. Usage is implied by the resource (nested replies) rather than contrasted with alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds meaningful behavior beyond annotations: only first-level comments (not replies), default Toutiao ordering, pagination support, and that results can continue from search. It does not discuss auth or rate limits, but for a read tool with annotation coverage this is solid.

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 core purpose is front-loaded in a single sentence, and each clause adds a necessary constraint: ordering, pagination, reply exclusion, and the URL alternative. There is no wasted text.

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?

Because an output schema exists, the description need not explain return values. For a two-parameter read tool, it covers scope, exclusions, ordering, pagination, and the URL sibling, while annotations and schema fill in safety and parameter details. 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%, so both post_id and page_token are fully documented in the input schema. The description restates that post_id is a numeric content ID and that pagination is supported, adding the context of continuing search results, but it does not add syntax or format details beyond the schema's own parameter descriptions. 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?

States a specific verb (读取), resource (一级评论), and scope (头条文章、视频或微头条), and explicitly excludes comment replies. It also distinguishes itself from the sibling by routing link cases to toutiao_get_post_comments_by_url. An agent can identify exactly what this returns 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?

Names the alternative explicitly: 有链接时使用 toutiao_get_post_comments_by_url. It also says the input is a numeric content ID from search results and that replies are not included, which implies the reply-specific sibling for that case. This gives clear when-to-use and when-to-use-other 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 cover read-only and open-world safety. The description adds meaningful behavior: it returns only first-level comments, uses Toutiao default order, supports pagination, and excludes comment replies. It does not discuss auth, rate limits, or output shape, but the output schema likely covers the latter.

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 compact sentence front-loads the core purpose, then adds exclusions and the alternative tool. No filler or repetition; 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?

Given a simple read/pagination tool with rich schema coverage, annotations, and an output schema, the description supplies the remaining decision-critical context: what is returned, what is excluded, and which sibling to use when only an ID is available.

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 both url and page_token are already well documented in the schema. The description reinforces URL usage and the ID-only alternative, but does not add syntax or format details beyond what the schema 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?

States a specific verb and resource: reads first-level comments through a Toutiao content URL or share text, in default order, with pagination, excluding replies. It also distinguishes itself from the sibling tool for ID-only cases.

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

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

Explicitly tells the agent when to use this tool (URL or share text is available) and when to use the alternative (only content ID available, use toutiao_get_post_comments_by_post_id). It also clarifies that replies are excluded, which routes the agent to the replies tool when 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful return-shape context (video play info, video description is not a transcription) but says nothing about pagination, errors, or rate limits. Reasonable value-add given annotations carry the safety 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?

Front-loaded with the primary capability and tightly scoped to three short clauses with no filler. The semicolon-chained clauses are slightly dense but every statement 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?

An output schema exists so return values need not be explained, and annotations cover the read-only/open-world profile. Purpose, ID source, and the by_url alternative are all present; the only gap is behavioral detail on large-result handling, which is minor for a single-ID lookup.

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?

Only one parameter and schema description coverage is 100%; the schema already documents post_id, its numeric pattern, and the warning not to pass a link. The description's '输入内容数字 ID，可接续搜索结果' restates the same information rather than adding syntax or format detail, 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?

States a specific verb+resource (读取头条文章、视频或微头条详情) and enumerates the returned content (正文、图片、作者、互动数据、视频播放信息), so the agent knows exactly what this retrieves. It also explicitly names the sibling it is not (toutiao_get_post_detail_by_url), letting an agent route between the two without opening either 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?

Gives a clear selection rule: use this tool when you have a numeric content ID, which can be carried over from search results, and use toutiao_get_post_detail_by_url when you have a link instead. No explicit exclusions beyond that, but the alternative routing is unambiguous.

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 by structured data. The description adds non-obvious context: it accepts share text as well as bare links, spans three content types, and clarifies that video copy is not a transcript. It stops short of describing returning fields or pagination, but with an output schema present that gap is minor.

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 that leads with the action and resource, then appends the routing alternative and the transcription caveat. Nothing is wasted, though the three densely packed clauses push slightly past ideal front-loading.

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

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

With an output schema present, the description needn't explain return values, and annotations cover the safety profile. Purpose, the sibling fork, and the output caveat are all present, leaving nothing an agent needs to call this 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% and the single url parameter is already documented with supported path patterns and an explicit 'don't pass a bare ID' warning. The description's phrase '链接或分享文案' merely echoes that schema text, so baseline 3 is appropriate for a one-param tool where 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?

Names a specific verb (读取/read detail) plus the resource types it covers (文章、视频、微头条) via link or share text. It explicitly distinguishes itself from the sibling toutiao_get_post_detail_by_post_id, so an agent can route without opening either 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?

States the exact condition under which the sibling applies ('只有内容 ID 时使用 toutiao_get_post_detail_by_post_id'), which is the primary routing decision for this tool. It also warns that video descriptions are not speech transcriptions, heading off a likely misuse.

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 structurally. The description adds a genuinely useful behavioral caveat not present in annotations or schema: the thumbnail/homepage statistics are approximate values ('缩略统计为近似值'). It stops short of covering freshness or rate limits, so 4 rather than 5.

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 sentence, front-loaded with the purpose, then the alternative-tool rule, then the approximate-stats caveat. No filler and nothing important buried.

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?

A one-parameter read tool with full schema coverage, an output schema (so return shape needn't be described), and annotations covering safety. Purpose, input constraints, sibling routing, and the approximation caveat are all present.

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

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

Schema description coverage is 100% and the single parameter's schema text already specifies accepted formats and the anti-patterns (content links, pure IDs). The description largely restates that, so the 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?

Names a specific verb and resource ('读取头条用户资料和主页统计') and states the accepted input form (主页链接或分享文案). It also explicitly distinguishes itself from the sibling toutiao_get_user_info_by_user_id, so an agent can choose between them without opening either 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?

Gives an explicit routing rule: when a numeric user ID is also available, prefer toutiao_get_user_info_by_user_id. The schema reinforces the exclusion set (no content links, no pure IDs), so both when-to-use and when-not-to-use are covered.

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 establish readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds a meaningful data-fidelity caveat (缩略统计为近似值) that annotations cannot express, though it says nothing about rate limits, auth, or response shape.

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 semicolon-joined sentence packs purpose, a caveat, and the routing rule, with the core action front-loaded and zero 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?

With only one parameter at full schema coverage, an output schema present, and annotations covering the safety profile, the description supplies everything else an agent needs: what it returns in general terms, the accuracy caveat, and the sibling routing.

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%: the schema already states the numeric-ID pattern and warns against content IDs, links, or profile handles. The description adds no parameter detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource (读取头条用户资料和主页统计) and immediately disambiguates against the sibling toutiao_get_user_info_by_profile_url. An agent can pick the right one without opening either 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?

Explicit routing rule: use this tool when a numeric user ID is already available, and use the profile_url variant only when working from a homepage link. This is exactly the when/when-not/alternative guidance the dimension calls for.

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 results span articles, videos and micro-posts and that pagination is supported, which is genuine behavioral context, but it gives no detail on pagination limits, ordering, or rate constraints.

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 clause states the action, the input form, and the coverage in one pass with zero filler. Nothing is buried and nothing is redundant.

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?

An output schema exists, so return-value explanation is unnecessary, and annotations cover the safety profile. With params fully documented and the description covering content types and pagination, the definition is close to complete; only explicit sibling routing and pagination behavior are left implicit.

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 all three parameters (page_token, profile_url, content_type) are fully documented in the schema, including the enum values and the non-reusability of page tokens. The description only echoes content-type coverage and pagination, adding no syntax or format detail beyond the schema. 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 names a specific verb (读取/read), resource (发布的作品/published works) and access path (通过头条用户主页链接/via the user's profile URL), plus the content scope (文章、视频、微头条). It is clear what the tool does, but it does not itself differentiate from the sibling toutiao_get_user_posts_by_user_id — that routing hint lives only in 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?

Usage is only implied by the required profile_url parameter and the name suffix; the description neither states when to prefer this tool over toutiao_get_user_posts_by_user_id nor describes any prerequisite. The explicit alternative-naming exists in the schema's profile_url description, not in the description text, so the agent must open the schema to be routed correctly.

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 safe-read profile and external-dependency nature are covered. The description adds no behavioral context beyond routing — no pagination behavior, result limits, or auth/rate-limit notes (pagination is only hinted at via the schema's page_token). Adequate but adds little beyond structured data.

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 tight sentence with the purpose front-loaded and the routing condition appended. No filler, no repetition of schema or annotations.

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 listing tool with an output schema, complete parameter docs, and safety annotations, the description supplies the one thing structured data cannot: the sibling-routing decision. Return format is legitimately omitted since an output schema exists; only minor gaps (result volume/pagination expectations) remain.

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

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

Schema description coverage is 100% with rich per-parameter text (ID pattern and source, page_token reuse warning, content_type enum), so the schema carries parameter meaning. The description only restates the ID-vs-URL routing condition already present in the user_id schema field, adding no new parameter detail. Baseline 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?

States a specific verb and resource — reading a Toutiao user's published works ('读取头条用户发布的作品') — and immediately distinguishes this tool from the profile-URL variant. An agent can tell which of the two sibling post-listing tools to pick from the description alone.

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?

Gives explicit routing conditions: use this when a numeric user ID is already available, use the profile-link tool when a homepage URL is available. The when/when-not split with an alternative is fully specified, not 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value beyond them by disclosing what the result set excludes (navigation, encyclopedia, user and video aggregation panels), which shapes how an agent interprets the returned items. It does not cover rate limits, auth, or empty-result 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?

One front-loaded sentence carries the purpose and pagination support, and a second sentence carries the exclusion list. There is no filler, and the highest-value routing information comes first.

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?

An output schema exists, so return-value explanation is unnecessary, and the 100%-covered schema handles parameter detail. Purpose, scope exclusions, and pagination are all covered, so an agent has everything needed to call this correctly against its siblings.

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 explains both keyword (with examples and link/ID exclusions) and the page_token continuation protocol. The description only reiterates that pagination is supported, adding no format or syntax detail beyond the schema, which is the correct baseline of 3.

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

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

The description pairs a specific verb with a specific resource and scope ("按关键词或短语查找今日头条公开内容"), and immediately distinguishes itself from siblings by ruling out detail-by-link and user-search use cases. An agent can tell it apart from toutiao_get_post_detail_by_url and toutiao_search_users without opening either 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?

It gives explicit when-not guidance: not for reading a specified link's detail and not for finding users, which maps cleanly onto the toutiao_get_post_detail_by_url and toutiao_search_users siblings. What is missing is naming those alternatives directly, so the routing is strongly 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=true and openWorldHint=true, so safety and open-world behavior are covered. The description adds genuinely useful extra context: no pagination support and no user/content details in the response, which prevents the agent from attempting page_token pagination or expecting rich entities.

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 that front-loads what is returned and appends two scope limitations. Every clause earns its place; there is no 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?

An output schema exists, so return-value shape need not be described, and the description still usefully states the response scope and the absence of pagination. For a single-parameter, annotated, output-schema-backed tool this is essentially complete, though it could note response size or rate limits.

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 documents the keyword parameter thoroughly (examples, and prohibitions on links/user IDs/page_token). The description adds no further parameter meaning, so the baseline of 3 is appropriate when the schema does all the work.

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: retrieving the Toutiao search-box suggestion words for a keyword. It further distinguishes itself from siblings by asserting it does NOT return user or content details, which separates it from toutiao_search_users and toutiao_search_posts without opening either 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 exclusions ('不返回用户或内容详情') implicitly route the agent: for user or post data, use the other search tools. However, no alternative tool is named explicitly and there is no positive statement of when to prefer this over, say, the hot-search list. Clear context, but not full when/when-not/alternative 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, and an output schema exists, so the safety profile and return shape are covered elsewhere. The description's added detail (pagination support, returned fields) largely duplicates the schema's page_token description and the output schema, leaving modest incremental value.

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

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

A single dense sentence with the core purpose front-loaded and the disambiguation clause trailing. It is efficient, though listing return fields that the output schema already covers is slightly redundant padding.

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

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

With annotations carrying the safety profile, a full output schema, and 100% parameter coverage, the description supplies the one thing structured fields cannot: the sibling-routing rule for keyword vs. ID/URL lookup. Nothing essential is missing for correct invocation.

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%: keyword and page_token are both fully documented in the schema, including the warning not to pass content/profile links and the rule to preserve keyword across pages. The description adds nothing parameter-specific beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource (按关键词查找今日头条用户) and enumerates the returned fields (ID, name, bio, follower count, verification). The second clause distinguishes it from the by-ID/by-URL lookup siblings, so an agent can route correctly without opening another 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?

Gives a clear when-to-use condition (search by keyword) and a when-not condition (if you already have a user ID or profile URL, query the profile directly). The alternatives are described by capability rather than named, so the agent must map them to toutiao_get_user_info_by_user_id / toutiao_get_user_info_by_profile_url itself.

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