SocialDataX X / Twitter 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 indicate read-only and open-world behavior; the description adds useful context by specifying that only public replies are returned and by warning against feeding reply-level comment IDs or comment links back into this tool. It does not discuss error or rate-limit behavior, but the annotations and output schema reduce the need for that.

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 semicolon-separated conditions, front-loading the core purpose and then giving concise routing rules. There is no filler or redundant restatement of the tool name.

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, annotations for read-only/open-world behavior, and 100% schema coverage, the description covers the crucial workflow decisions: when to use directly, when to call another tool, when to ask the user, and what not to pass. The schema additionally covers page_token handling, making the definition complete for agent 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%, and the parameter descriptions already explain the required ID formats, sources, and forbidden values. The tool description mostly restates workflow decisions rather than adding new per-parameter meaning, 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 identifies a specific operation: retrieving public comment replies for a given X post ID and first-level comment ID. It clearly distinguishes this from sibling first-level comment tools by stating it operates on replies and by warning not to use reply-result comment IDs.

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

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

The description explicitly states when to call this tool directly, when to call a first-level comment tool to fill in missing IDs, when to ask the user for post locator information, and what not to pass as an argument. These routing rules leave little ambiguity for an 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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses that only top-level comments are returned and that the post must be public. It does not cover rate limits or auth, but the annotation burden is already partly satisfied.

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 front-loads the operation, scope, and key exclusions. Every clause earns its place with no redundant material.

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 complete parameter documentation, an output schema, and safe-read annotations, the description covers what the tool does, when to use it, and its domain constraints. Pagination handling is already in the 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 description coverage is 100%, so post_id and page_token are already thoroughly documented. The tool description adds minimal parameter semantics beyond what the schema already states.

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 states a specific verb and resource: retrieving top-level comments for a public post by post ID, and explicitly notes replies are not embedded. This distinguishes it from siblings like x_get_post_comment_replies_by_comment_id and x_get_post_comments_by_post_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?

It says to prefer this tool when post_id is known and explicitly warns not to pass a post link or comment ID. This creates clear selection boundaries against the URL-based and reply-based sibling tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety. The description adds that it returns only top-level comments (not nested replies) and applies to public posts, which is valuable 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?

The description is two concise sentences, front-loaded with the core purpose and usage condition. No redundant wording or filler; every phrase 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 read-only tool with two well-documented parameters and an output schema, the description covers the primary usage condition, return scope, and the alternative tool. Minor gaps like error handling or rate limits are not critical given the schema and annotations are thorough.

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 explanations of post_url (including allowed sources and exclusions) and page_token (opaque pagination token with strict usage rules). The tool description itself does not add extra parameter semantics, 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?

Description clearly states the tool retrieves top-level comments for a public post given a post URL, explicitly excludes replies, and distinguishes from the post_id-based sibling. The verb '获取' and resource '一级评论列表' are specific and unambiguous.

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

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

The description explicitly says to use this tool only when there is no post_id and only a post_url (or a non-empty post_url from results), effectively pointing to the sibling tool x_get_post_comments_by_post_id for the alternative case. This is clear, actionable usage guidance.

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

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

The annotations already declare readOnlyHint=true, so the description carries a lower burden. It adds useful context by specifying that only public post details are fetched ('公开帖子详情'). It does not discuss auth, rate limits, or error behaviors, but for a read-only getter this is a modest but acceptable amount of added context.

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

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

The description is one compact, front-loaded sentence: it states the core operation first, then gives the priority usage rule and the key constraint. There is no filler or unnecessary repetition of schema details.

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 detail tool with rich schema coverage, an output schema, and safety annotations, the description is complete enough. It communicates the identifier source, the public scope, and the 'use by ID, not link' rule, while the input schema fills in the remaining parameter details.

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

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

Schema description coverage is 100%, and the schema's parameter description is already very detailed: it requires a numeric string, lists valid sources for copying post_id, and forbids links, usernames, and share text. The tool description adds essentially no new parameter semantics, 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 states a clear verb and resource: '获取公开帖子详情' (get public post detail) by post ID. It also distinguishes itself from x_get_post_detail_by_post_url by explicitly saying not to pass a post link, so the tool's role among siblings is 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 explicitly says to use this tool when post_id is already known ('已知 post_id 时优先使用') and forbids passing a post link. However, it does not name the URL-based alternative x_get_post_detail_by_post_url directly, so the routing guidance stops just short of 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?

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds the 'public post' qualifier, which is useful context. It does not contradict annotations and doesn't need to repeat read-only nature. Minor missing disclosure about rate limits or authentication is acceptable given annotations cover safety.

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

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

The main description is a single, dense sentence that conveys purpose and usage condition in parallel. The parameter description is verbose but necessary for correctness. Nothing superfluous.

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 annotations covering read-only behavior, the description covers purpose, usage conditions, and parameter semantics completely. Nothing an agent needs to invoke 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?

The parameter description is exceptionally thorough, detailing what constitutes a valid post_url and explicitly listing what not to pass (user profile links, links in post body, keywords, API endpoints). This far exceeds the basic schema description and fully compensates for any ambiguity.

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 public post details from a post link, with the specific condition that it is only used when no post_id is available. It distinguishes from the sibling x_get_post_detail_by_post_id by making the post_id condition explicit.

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: only when there is no post_id, only a post_link, or when using a non-empty post_url from results. This routes the agent clearly away from the by_post_id sibling and toward using URL-based data.

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 returned data is "公开" (public) info, which is mildly useful, but nothing about rate limits, auth, or response shape. With annotations carrying the behavioral load, a 3 is appropriate.

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 purpose first, then input sources, then the exclusion. Efficient, though it overlaps noticeably with the parameter's own schema description.

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 safety, the description need not explain return values. It adequately covers the one input's provenance and a key misuse case, leaving only sibling routing unspecified.

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 documents accepted URL forms and the exclusion list. The description largely restates that same guidance, so it adds no meaning beyond the schema – 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 ("根据 X 用户主页链接获取公开用户信息" – fetch public user info by profile URL), which naturally distinguishes it from the by_user_id and by_username siblings. It does not explicitly call out those alternatives, so differentiation is implicit via the input type rather than stated.

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 concrete guidance on where to source the input (non-empty items[*].profile_url from user search, or author.profile_url from posts/comments) and an explicit exclusion ("不要传帖子链接"). Clear context for use, though it never names the by_user_id/by_username alternatives that would be the fallback when a URL 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and external-data profile is covered. The description contributes the additional fact that only 公开 (public) user information is returned, which is useful scoping, but says nothing about rate limits, auth, or data that may be withheld for protected accounts.

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 short clauses separated by a semicolon, with the core action first and the usage condition second. Every word carries weight and there is 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?

An output schema exists, so return values need no explanation, and the single required parameter is fully documented in the schema. The description covers purpose and the ID-ready precondition; only the explicit contrast with the by-username and by-profile_url siblings 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 parameter description is exhaustive, covering how to copy user_id from search results, user detail, and post author fields, plus what not to pass. The description's "已有完整 user_id 时直接使用" only restates the schema and adds no new syntactic or format guidance.

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 scopes it to lookup by X user ID, which meaningfully separates it from the username/profile_url variants in the sibling list. It does not explicitly name those siblings, so an agent must infer the distinction from the identifier naming convention.

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 时直接使用" gives a clear positive trigger: use this tool when a complete numeric ID is already in hand, implying the username/URL lookups are for other cases. There is no explicit when-not statement or named alternative, so it stops short of full routing 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, so the safety profile is covered. The description adds only that the data is '公开' (public), which is mild scope context, and says nothing about permissions, rate limits, or lookup failure behavior; with annotations present, 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 front-loaded sentence that leads with the verb and resource, then appends the sourcing hint. It is tight with no obvious filler, though the sourcing detail partially duplicates the schema.

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 lookup tool with an output schema and full annotation coverage, the description supplies the essential purpose and input sourcing guidance. The only missing piece is explicit routing among the many sibling lookup-by-X 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 the schema already documents format ('不带 @', accepts '@username'), sourcing, and negative cases (no links or share text). The description largely restates the same sourcing paths, adding little beyond the schema; baseline 3 is correct.

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 ('根据 X 用户名获取公开用户信息' – get public user info by X username), which is unambiguous about what the tool returns. It does not, however, explicitly contrast itself with the sibling lookup modes (by_profile_url, by_user_id), leaving the agent to infer the routing from the name 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?

The description tells the agent where a valid username can be sourced from (search result items[*].username, or author.username from posts/comments), which is implied usage guidance. It never states when to prefer this lookup over x_get_user_info_by_user_id or x_get_user_info_by_profile_url, so the alternative-selection guidance is absent.

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 safety is covered. The description adds real behavioral context: pagination via page_token, first-page/onward semantics, and the requirement to pin the token to a single user. It does not describe volume or rate limits, but for a read-only list tool this is adequate.

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 purpose, then the sourcing constraint, then pagination support. Dense but every clause carries information; minor redundancy with the schema's profile_url description.

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 shape need not be explained. With annotations covering the safety profile and 100% schema coverage, the description supplies the remaining context an agent needs to select and 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%, so both page_token and profile_url are already fully documented in the schema, including the opaque-token rules. The description restates the accepted source fields for profile_url and the post-link exclusion, which reinforces but does not exceed 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?

Names a specific verb and resource (obtain public user post list by profile URL) and implicitly distinguishes it from the user_id/username siblings that fetch the same resource. An agent can tell what it retrieves 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?

Explicitly tells the agent where to source profile_url (user search items[*].profile_url, user detail profile_url, or author.profile_url) and warns against passing post links. It does not, however, state when to prefer this over x_get_user_posts_by_user_id or _by_username, which are the more likely point of confusion.

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 only that page_token pagination is supported, which is already fully spelled out in the schema; no extra context on rate limits, ordering, or result bounds is provided. A 3 fits given the lower bar set by 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 with the resource, the identifier precondition, and pagination front-loaded; nothing is padded. The trailing page_token clause is mildly redundant with the schema but cheap.

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 described, and annotations cover the read-only/open-world profile. Purpose, required identifier, and pagination semantics are all present; the only gap is explicit routing to the username/profile_url 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%, and the two parameter descriptions are unusually thorough (exact-copy rules for user_id, opaque-token handling and reset-on-user-switch rules for page_token). The description adds nothing beyond the pagination mention, so the baseline 3 is correct.

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+scope: fetch a user's public post list by X user ID, with pagination support. The identifier form (user_id) implicitly separates it from the sibling *_by_username and *_by_profile_url variants, but the description never names those alternatives, so differentiation relies on the tool name.

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 时直接使用" gives a usable trigger condition (you already have a complete numeric user_id). However, no explicit when-not or alternative routing is given, even though the sibling list contains three identically-purposed tools keyed by username and profile_url — the agent must infer the choice.

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 only public posts are returned and that pagination is supported via page_token, which is modest additional context beyond the structured fields.

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 compact two-clause sentence that front-loads the core purpose before the parameter-sourcing detail. No wasted wording, though it is terse.

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, return values need not be explained, and the description covers username sourcing plus pagination adequately. It is complete enough for an agent to invoke correctly, missing only explicit 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%, so both username and page_token are already fully documented in the schema (including pagination-token handling rules). The description adds no meaning beyond what the schema provides, making the baseline 3 correct.

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 ('根据 X 用户名获取公开用户帖子列表'), making it clear this retrieves a user's posts by username. It does not, however, explicitly differentiate from siblings like x_get_user_posts_by_user_id or x_get_user_posts_by_profile_url, which the name alone must disambiguate.

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 tells the agent where to source the username (user-search items[*].username or author.username from post/comment results), which is useful context. But it gives no guidance on when to prefer this tool over the by_user_id or by_profile_url variants, so selection among siblings is left 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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuine behavioral context beyond that: results include the author's self-replies, and the operation is paginated. It does not discuss ordering, result volume, or rate limits, which keeps it short of a 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?

Front-loaded with the core verb and resource, then scope, then the alternative. Slight redundancy between the purpose clause and the "when to view replies" clause, but no filler and no wasted sentences.

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 no explanation, and annotations carry the read-only/open-world profile. The description covers purpose, scope, and routing adequately; only minor operational details (ordering, result caps) are absent, which is acceptable for this complexity.

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 field already documents first-call and continuation semantics in detail, so the baseline of 3 applies. The description names the profile link as the input but adds no format or sourcing detail beyond what the schema property 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?

States a specific verb and resource: retrieve the reply posts published by a given X profile URL, with the notable scope qualifier that self-replies are included and pagination is supported. It also explicitly contrasts itself with the comment-oriented siblings, so an agent can distinguish it without opening any 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 positive trigger ("查看博主回复过什么时使用") and an explicit non-trigger with a redirect ("查看某条帖子下的评论或评论下的回复时，使用对应评论工具"). The alternative is named by category rather than by exact tool name, but the routing decision 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. The description adds genuinely useful behavioral traits beyond that: it includes self-replies and supports pagination. With an output schema present, no further return-format disclosure is required.

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 tightly packed clauses separated by semicolons, front-loaded with the core action and followed by routing guidance. No filler sentences, though the punctuation-dense Chinese phrasing is slightly compressed.

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, two-parameter tool with full schema coverage, annotations, and an output schema, the description covers purpose, pagination, self-reply inclusion, and sibling routing adequately. The only residual gap is disambiguation from the profile_url/username reply variants.

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

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

Schema description coverage is 100% and both parameters are fully documented in the schema (user_id sourcing rules, page_token continuation rules). The description adds no parameter-level meaning beyond the schema, 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?

States a specific verb+resource (get the replies posted by this user, identified by X user ID) and adds scope detail that it includes self-replies. It explicitly differentiates from the comment tools, but does not distinguish itself from the near-identical siblings x_get_user_replies_by_profile_url and x_get_user_replies_by_username beyond the identifier in the name.

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 ('use when viewing what the blogger has replied to') and an explicit alternative plus exclusion ('to view comments under a post or replies under a comment, use the corresponding comment tool'). It omits guidance on choosing between the user_id / username / profile_url variants, so it stops short of full alternative coverage.

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 by structured data. The description adds genuine behavioral context beyond that: the result set includes self-replies (自回复) and supports pagination. It stops short of describing ordering or volume/rate behavior, so it is not a 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?

Two compact sentences, with the core action and scope front-loaded and the disambiguation clause clearly separated. Every clause carries information; 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 values need not be explained. For a two-parameter read tool with full annotation coverage, the description supplies scope, self-reply inclusion, pagination support, and sibling routing – everything needed 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?

Schema description coverage is 100% and the username/page_token descriptions are already very detailed (accepts @, sourcing rules, token reuse constraints). The description adds no additional parameter guidance, 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 ('获取该博主发布的回复帖子，包括自回复'), scoping it to replies authored by a given X user. It explicitly separates itself from the comment/reply-listing siblings, so an agent can distinguish it without opening any 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 when-to-use condition ('查看博主回复过什么时使用') and a when-not-to-use rule that routes to a named alternative ('查看某条帖子下的评论或评论下的回复时，使用对应评论工具'). Nothing is left 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?

Annotations declare readOnlyHint=true and openWorldHint=true, and the description adds behavioral context beyond that: it waits up to 240 seconds per call, does not trigger reprocessing, and warns against duplicate submission. 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?

A single front-loaded sentence that states the purpose first, then the key behavioral constraints (240s wait, no reprocessing, no resubmission). Zero waste and easy to parse.

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 simple parameter, an output schema, and readOnlyHint annotations, the description covers the critical operational details: timeout behavior, reentrancy (same job_id), and resubmission warning. 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 coverage is 100%, so the baseline is 3. The description reinforces that the same job_id should be passed unchanged when the task isn't complete, but this is already largely captured in the schema's parameter description. The description adds marginal value here.

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

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

The description states a specific verb (查询/query) with a distinct resource (video speech-to-text task) keyed by job_id. It clearly differentiates itself from the submit siblings (x_submit_video_speech_text_by_post_url / by_post_id) by focusing on querying an existing task rather than creating one.

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 tells the agent when to use it — querying a job using a user-provided or submit-returned job_id — and explicitly says not to resubmit the task. It doesn't name alternatives explicitly, but the submit siblings are implied as the source of the job_id, giving clear context.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true, and the description does not contradict them. Beyond that, the description adds the behavioral trait 'only returns post results' and mentions pagination and sorting, which are not in the annotations. This provides useful context that helps the agent predict behavior without additional inference.

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 efficiently states purpose, usage, exclusions, and feature. It is front-loaded with the core purpose and then routes to alternatives, but the long sentence packs multiple clauses, which slightly reduces readability. Overall, it earns its place 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?

Given the presence of an output schema and detailed input schema parameters, the description covers all necessary aspects: purpose, usage conditions, exclusions, pagination, and sorting. Nothing essential for an agent to correctly invoke the tool 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?

Input schema covers 100% of the parameters with detailed descriptions, including exclusions for keyword and precise instructions for page_token. The tool description itself does not add any parameter-specific semantics beyond what the schema already provides. With full schema coverage, a 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 clearly states the verb 'search' and the resource 'X / Twitter public posts', and explicitly notes it 'only returns post results', distinguishing it from sibling tools that return post details or user info. It differentiates itself by naming the exact conditions for using alternatives, so an agent can immediately identify the correct 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 provides explicit when-to-use and when-not-to-use guidance: it says to use when searching by keyword, and to use other tools when having post_id, post_url, user_id, username, or profile_url. It also mentions pagination and sorting support. This is thorough and leaves 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 cover read-only/open-world status, and the description adds real scope information the annotations do not: no posts, no recommended users, and explicitly no pagination. This prevents an agent from attempting paging or expecting content payloads. It stops short of noting rate limits or result caps.

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 dense sentences with zero filler; scope and the negative constraints are front-loaded, and the usage hint comes last. 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?

An output schema exists, so return-format explanation is not required, and the description covers scope, exclusions, and usage. For a single-parameter read tool this is essentially complete; only minor caveats like rate limiting are absent.

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 its schema description is fully documented (keyword/phrase, with exclusions for links, IDs, and pagination tokens). The description adds no format or syntax details beyond the schema, 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: retrieve keyword autocomplete suggestions from the X/Twitter search box. It explicitly disambiguates from siblings by naming what it does NOT return (posts, recommended users), which is exactly what an agent needs to separate it from x_search_posts and x_search_users.

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 usage route: the returned text feeds post search, and if an explicit search term already exists the agent should search posts directly. The alternative is described behaviorally rather than by tool name, so the routing is clear but 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?

Annotations already declare readOnlyHint and openWorldHint, covering safety and open-world behavior. The description adds that it returns user profiles and a pagination token, but the output schema already covers return format and the page_token parameter schema covers pagination mechanics; no additional auth or rate-limit context is provided. Added value beyond annotations is modest.

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 tightly written sentences: the first states purpose and pagination support, the second routes to alternatives. No filler or repetition; information is front-loaded.

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

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

Given a read-only search tool with annotations, full schema coverage, and an output schema, the description supplies purpose, pagination behavior, and explicit alternative selection guidance. Nothing material is missing for an agent to call 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?

Schema description coverage is 100% and both parameters are documented with examples and pagination instructions. The description mentions keyword search and page_token pagination but adds no semantic detail 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?

States a specific verb and resource: search X/Twitter users by keyword. It also distinguishes itself from sibling detail tools by explicitly routing to them when user_id, username, or profile URL is already known.

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

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

Explicitly states when to use this tool (discover accounts by name/keyword) and when not to use it (when user_id, username, or profile URL is known, use the corresponding user detail tool). The alternative selection condition 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 mark this as not read-only and not idempotent, so the description correctly implies a mutation. Beyond that, it adds specific behavioral details: it only processes the first available MP4 of the post, waits up to 240 seconds, and returns a job_id with a next-step query action. This is valuable context not present in annotations and matches the open-world hint.

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 dense sentence that front-loads the primary action and embeds all key constraints (first MP4, 240s wait, job_id handoff). No filler or repetition; the sentence earns its length by packing critical behavior flags into a compact structure.

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

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

The description covers the full call flow: submit, wait, and on timeout return a job_id plus a pointer to the next query. Given the output schema exists (to define return structures) and the sibling x_get_video_speech_text_job handles the follow-up, the description provides an agent with everything needed to invoke the tool correctly and know what to expect.

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 post_id is thorough (100% coverage), explaining exactly where to source the ID and the required numeric-string format. The tool description does not add meaning beyond what the schema already provides—it only reiterates 'based on post_id.' Since the schema carries the full burden, 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 states a clear action (submit a speech-to-text task) on a specific resource (video post identified by post_id) and adds explicit constraints (only the first MP4 of the post, a 240-second wait). This distinguishes it from the sibling x_submit_video_speech_text_by_post_url, which uses a URL instead of an ID, so an agent can immediately tell them apart 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?

The description makes it clear this tool is for post_id input, and the naming contrasts with the URL-based sibling. It also signals a follow-up step ('下一步查询动作') implying use of x_get_video_speech_text_job for status. However, it does not explicitly state when to choose this over the URL variant, though the ID/URL distinction is implicit. No when-not guidance is given, but the context is sufficient for most agents.

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?

Description discloses key behaviors beyond annotations: it waits up to 240 seconds, processes only the current post's first MP4, and returns job_id plus next query action if incomplete. This adds meaningful context that annotations alone do not provide, without contradicting them.

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 purpose and then adds critical constraints and fallback behavior. There is no filler or repetition of schema details.

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 only one parameter, a full schema, output schema availability, and annotations, the description covers the essential operation, the time limit, the video-selection rule, and the asynchronous fallback. Nothing material is missing for an agent to invoke 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?

Schema description coverage is 100%, so the baseline is 3. The main tool description does not add further parameter-level semantics beyond what the schema already explains about post_url; it correctly does not need to compensate.

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

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

Description clearly states the action (submit speech-to-text task), the resource (X/Twitter video post URL), and the precise scope (only the first available MP4 in the current post). It is distinguishable from the sibling x_submit_video_speech_text_by_post_id because the tool is explicitly URL-based.

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 schema specifies '仅在没有 post_id 时' (only when there is no post_id), which gives a clear condition for choosing this URL-based tool over the post_id variant. However, it does not explicitly name sibling tools or provide a fuller when-not-to-use statement, so it falls just short of fully explicit alternative routing.

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