SocialDataX X / Twitter MCP

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

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

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

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

The description is a single compact sentence with the key information front-loaded. The bilingual repetition and enumeration of 'balance / remaining points / points' is slightly redundant but not harmful.

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

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

Given that this is a zero-parameter read-only balance lookup, the description is complete. An output schema is present, so return values do not need to be described, and the annotations cover the safety profile.

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

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

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

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

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

The description clearly states a specific action, resource, and scope: querying the SocialDataX points balance for the current API Key account. It is fully distinguishable from the unrelated zhihu_ sibling tools even without inspecting schemas.

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

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

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

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

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

Annotations already 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. The description's mention of 公开用户信息 (public info) is consistent with these and adds a slight context that the data is public, but it does not materially extend beyond what the annotations already convey. 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?

The description is compact and front-loaded: purpose first, then a usage caution. Both clauses earn their place with no filler. It could be slightly more expansive on usage context, but for a single-parameter tool this length is well balanced.

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 the return shape is covered outside the description. The parameter is exhaustively documented in the schema, and the description covers purpose plus a key sourcing caution. For a read-only, single-parameter tool, nearly everything an agent needs to call it correctly is 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 profile_url parameter description is exhaustive, specifying accepted formats and exclusions. The tool description adds only 'don't pass post links,' a point already captured in the schema. At full schema coverage, 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 specific verb (获取/get) and resource (公开用户信息/public user info) keyed by a specific identifier (profile_url). It is clearly distinguishable from the sibling get_by_user_id and get_by_username tools, which operate on different identifiers, and from get_user_posts_by_profile_url, which returns a different resource.

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 a clear sourcing instruction (use non-empty author.profile_url from search/detail/comment results) and an explicit exclusion (do not pass post links). The schema description is equally rich, listing exactly where to obtain the URL and what formats are valid. It does not explicitly name alternatives like get_by_user_id when an ID is available, but the identifier-based differentiation is effectively conveyed.

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

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

注解声明了readOnlyHint和openWorldHint，描述未添加额外行为信息。虽无矛盾，但描述未补充诸如数据来源或限制等上下文，仅依赖注解。

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

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

描述仅一句话，无冗余，直接传达核心用途和条件。

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

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

工具简单，单参数，有输出schema，注解覆盖安全属性。描述提供了使用条件，但未提及错误场景或特殊要求，整体足够但仍可更完整。

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

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

schema描述覆盖了参数user_id的完整说明（数字字符串、来源等），描述未增加额外信息，符合基线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?

描述明确说明根据X用户ID获取公开用户信息，动词'获取'和资源'用户信息'清晰。与兄弟工具（通过用户名或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?

描述了使用条件（已有完整user_id时直接使用），但未明确提及何时不使用或替代工具。尽管兄弟工具名称暗示了替代方案，但描述未显式说明，缺乏明确的when-not。

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

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

Annotations already provide readOnlyHint=true and openWorldHint=true, so this is known to be a non-destructive lookup. The description adds that the data is public, but does not disclose additional behavioral details such as rate limits or error behavior. It does not contradict the annotations.

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

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

The description is a single compact sentence with the verb and resource front-loaded. It communicates the core purpose and a practical usage hint without any extraneous content.

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

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

This is a simple single-parameter read-only lookup with an output schema. The description, combined with the detailed parameter schema and annotations, provides enough information for an agent to call it correctly. No material gaps remain.

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

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

Schema description coverage is 100%, and the schema already explains valid username formats, the '@' handling, and what not to pass. The description merely echoes a subset of that guidance, so it does not add meaningful semantic value beyond the schema.

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

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

The description clearly states the action and resource: getting public user information by X username. It also indicates the source of valid usernames, and the 'by_username' scoping distinguishes it from sibling tools that take a profile URL or user ID.

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

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

The description gives clear context for when to use the tool: when you have a non-empty author.username from search, detail, comment, or reply results. It does not explicitly say to use the profile_url or user_id siblings when those identifiers are available, but the intended input source is clear.

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

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

Annotations already declare readOnlyHint=true, so the safe-read behavior is covered. The description adds that posts are public and that page_token pagination is supported, but does not disclose rate limits or response shape; the output schema covers the latter. 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?

The description is a single, dense sentence containing three useful pieces: the core purpose, input sourcing guidance, and pagination support. It has no filler, though the multiple clauses make it slightly less scannable than a two-sentence 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?

Combined with the highly detailed schema and an output schema, the description covers the essential operational aspects: what the tool fetches, where to source the profile_url, what not to pass, and pagination. It does not explicitly mention alternative tools, but that is not critical for calling 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 coverage is 100%, and the schema descriptions for both profile_url and page_token are extremely detailed, including exact sources, exclusions, and opaque-token rules. The main description only adds a usage hint about reusing author.profile_url, which is helpful but not necessary given the schema's depth.

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

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

The description clearly states the verb '获取' (get) and the resource '公开用户帖子列表' (public user posts list) keyed by profile_url. It distinguishes itself from sibling tools by name and by emphasizing the profile_url input, but does not explicitly name the user_id/username alternatives.

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 concrete guidance: use a non-empty author.profile_url from other results or a user-provided x.com/twitter link, and explicitly warns not to pass post links. It mentions pagination support but does not explicitly tell when to choose sibling tools based on available identifiers.

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

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

With readOnlyHint=true and openWorldHint=true annotations, the safety profile is already covered. The description adds meaningful context by clarifying that only public posts are returned and that page_token pagination is supported, going slightly beyond what the annotations state.

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 entire description is one compact, front-loaded sentence that covers the core purpose, usage condition, and pagination support. Every clause adds value with no 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 simple two-parameter tool with 100% schema coverage, a true output schema, and safety annotations, the description sufficiently covers purpose, usage condition, and pagination. Nothing essential is missing for an agent to call 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%, with detailed explanations for both user_id and page_token. The description itself adds little beyond reinforcing that user_id should be complete and passed directly, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource ('根据 X 用户 ID 获取公开用户帖子列表' - get public user posts by X user ID), and explicitly notes it should be used when a complete user_id is already available. This clearly distinguishes it from the by_username and by_profile_url 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 gives clear context for when to use the tool: when a complete user_id is already available, use it directly. However, it does not explicitly mention when not to use it or name the alternative by_username/by_profile_url tools, though sibling names make the distinction evident.

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 known. The description adds pagination support and the tip to use author.username from results, which is useful behavioral context. It does not disclose any additional behaviors (e.g., rate limits, auth) but the bar is lower due to annotations.

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

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

The description is a single, concise sentence that front-loads the core purpose and includes the most important usage hint (author.username) and pagination support. No wasted words; every element contributes to understanding.

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

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

Given the output schema exists, the annotations cover read-only and open-world, and both parameters are fully documented, the description is sufficient for an agent to call the tool correctly. It covers the essential information: resource, pagination, and reuse of author.username. No critical gaps are evident.

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 both parameters are already documented in the input schema. The description adds a tip about using author.username, but that is largely redundant with the schema's username description which already says to copy from author.username. The page_token behavior is also fully described in the schema, so the description adds minimal extra value.

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

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

The description clearly states the action (get public user posts) and the resource (by X username). It is distinguishable from siblings like x_get_user_posts_by_profile_url or x_get_user_posts_by_user_id, though it doesn't explicitly mention alternatives. The purpose is immediately clear.

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

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

No guidance is provided on when to choose this tool over its siblings (profile_url or user_id variants). It also lacks conditions like 'use this when you have a username' or exclusions. The description implies usage by stating the resource, but it does not officially guide selection.

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 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.