SocialDataX Instagram MCP

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

Annotations already declare readOnlyHint=true, so the safe read-only profile is covered. The description adds useful behavioral context: page_token must be preserved for the same post/comment chain, and it describes fallback orchestration when required IDs are missing.

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 front-loads the core purpose and contains no filler. However, the fallback logic is compressed into one long semicolon-separated sentence, which could be more quickly parsed as structured bullets or short clauses.

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?

Covers every practical invocation path: valid IDs provided, missing IDs with post_url, missing IDs with only post_id, and no post locator at all. Since an output schema exists, the description is not required to explain return values.

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 description coverage is 100%, and the schema already documents ID provenance, page_token opacity, and valid reuse rules. The tool description therefore does not need to add parameter semantics; 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: paginating Instagram comment replies by post_id and top-level comment_id. It clearly distinguishes this tool from instagram_get_post_comments_by_post_url, which fetches top-level comments, and explains when this reply-specific tool applies.

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 explains when to invoke the tool directly, when to route through instagram_get_post_comments_by_post_url, when to use instagram_get_post_detail_by_post_id first, and when to ask the user for missing inputs. It also names the exact sibling tools, leaving little 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=true and openWorldHint=true, so the read-only nature is covered. The description adds meaningful behavioral context beyond the annotations: it explains that the operation is paginated, returns only top-level comments, and includes a fallback workflow involving another tool when only post_id is available. No contradiction with annotations exists. The description does not mention rate limits or auth, but with annotations covering safety, this is a minor gap.

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

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

The description is a single sentence, but it is logically structured with the main purpose front-loaded, followed by the direct use case, the fallback path, and pagination. It avoids unnecessary fluff and every clause carries meaning. It is slightly dense but remains concise and readable within a couple of lines.

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

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

For a two-parameter tool with an output schema (not shown here), the description covers the essential usage scenarios: direct use with post_url, the fallback via post_id, and pagination token handling. It specifies that only public posts are supported and clarifies the token reset rule. The only minor omission is explicit alternative tool routing (e.g., for replies), but the sibling tool names and the description's scope make this inferable. Overall, it provides sufficient context for an agent to call the tool correctly.

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

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

The input schema already documents both parameters (coverage 100%), so the baseline is 3. The description adds value beyond the schema by explaining the direct use of post_url (as provided or from share_url) and explicitly stating that page_token must be cleared when switching posts, and that it must be copied verbatim from the previous response. These are operational details not fully captured in the schema descriptions.

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 top-level comments of a public Instagram post via a post link, using the verb '获取' (get) and specifying the resource ('评论' comments) and scope ('一级评论' top-level). It distinguishes itself from the sibling replies tool by explicitly limiting to top-level comments, and from the post detail tools by focusing on comments. This is a precise, actionable purpose statement.

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 context: use directly when the user has already provided a post link, and if only a post_id is available, first call instagram_get_post_detail_by_post_id and reuse the share_url from that result. It also explains pagination usage with page_token. However, it does not explicitly mention when to avoid this tool (e.g., when replies are needed), though the sibling tool name provides that clue. The guidance is clear and actionable.

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 annotation readOnlyHint=true already covers the read-only nature, so the description does not need to repeat that. It adds the qualifier '公开' (public), which is useful context. However, it does not disclose potential error conditions (e.g., private posts, invalid IDs) or any rate limiting, though the output schema likely defines return types. The description carries 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, well-structured sentence that front-loads the primary function and includes a concise usage hint. There is no verbose or redundant content, and every word contributes to clarity.

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

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

With a simple one-parameter read-only tool and an output schema present, the description covers the essential guidance: what it does and when to use it. It might miss a note about behavior for non-existent or private posts, but given the schema and the explicit condition '已有完整 post_id 时直接使用', an agent can confidently invoke it correctly. Overall, it is nearly complete.

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

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

The schema description for `post_id` is complete (100% coverage), detailing that it is a numeric string, to be used as-is from user or prior results, and explicitly listing forbidden inputs (shortcode, username, URL, etc.). The tool description adds no additional parameter semantics beyond this, so the baseline of 3 applies.

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

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

The description states the verb (获取/get), the resource (公开帖子详情/public post details), and the input (post_id), making the core action clear. It also notes when to use it directly ('已有完整 post_id 时直接使用'), which implicitly distinguishes from sibling tools that use URLs or search. However, it does not explicitly name alternatives or contrast with `instagram_get_post_detail_by_post_url`, so it falls short of full sibling differentiation.

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

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

It provides a usage condition: use directly when you already have a complete post_id. This implies that for cases without an ID you'd use other tools, but it never names those alternatives explicitly or says 'instead of X'. With sibling tools like `instagram_get_post_detail_by_post_url` and `instagram_search_posts` present, the guidance is only implicit and would benefit from explicit routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation. The description adds the 'public post' scope restriction, which is useful, but it does not disclose additional behaviors like failure modes, rate limits, or auth requirements.

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 concise, front-loaded sentence in Chinese that directly states the tool's purpose. There is no filler or redundant 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?

For a simple read-only tool with one parameter, an output schema, and clear annotations, the description is mostly sufficient. It lacks explicit usage context vs. sibling tools, but the schema and annotations cover most operational needs.

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 post_url parameter is thoroughly documented, including what to pass and what to avoid. The tool description itself does not add 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?

The description clearly states the action and resource: get public post details via an Instagram post URL. The name and description together distinguish it from siblings like instagram_get_post_detail_by_post_id by specifying the URL-based input.

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

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

The description implies the tool is for retrieving post details when given a post URL, but it does not explicitly state when to prefer this over alternatives such as by_post_id or when not to use it. The param schema gives URL formatting guidance but no tool-selection 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 description explicitly states it retrieves public information, which aligns with the readOnlyHint annotation. It adds clarity about the data scope, though it doesn't mention potential errors or limitations for private accounts, which is acceptable given the annotations already indicate read-only behavior.

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

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

The description is a single, concise sentence that immediately conveys the tool's purpose without unnecessary detail. It is well-structured and front-loaded.

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

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

The description is sufficient for the tool's simplicity. Given that an output schema exists, the description does not need to explain return values. It adequately covers the tool's scope and constraints, though it could mention edge cases, but that is not essential here.

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 description itself does not elaborate on the parameter, but the input schema provides a detailed description of profile_url, including sources and exclusions. Since schema coverage is high, the description adds no additional meaning, warranting the baseline score.

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

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

The description clearly states the tool's function: getting public user information based on an Instagram profile URL. It distinguishes from sibling tools that operate on usernames or post IDs, making the purpose 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 and the parameter guidance provide clear instructions on what to pass (e.g., author.profile_url) and what not to pass (links to posts, comments, API endpoints). While it doesn't explicitly compare with sibling tools, the name and purpose make it obvious when to use this tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety and result-completeness aspects. The description adds only the word 'public' (公开), which implies no authentication is needed, but this is a minor addition. It does not mention any other behavioral traits like rate limits or error conditions, which are less critical for a simple read-only getter. The description 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 in Chinese that states the purpose and a usage condition without any fluff. It is front-loaded, immediately conveying the action and the primary usage cue. Every word 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, single-parameter, read-only tool with a rich output schema and comprehensive parameter guidance, the description provides all necessary context. The purpose is clear, the usage condition is stated, and the schema handles parameter semantics. No missing information prevents an agent from invoking 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 schema's parameter description is extremely detailed, covering formatting (no @), usage (copy from author.username), and what to avoid (URLs, share text). The tool description adds no extra parameter meaning beyond what the schema already provides; in fact, it repeats the 'when user provided username' condition without adding new details. At high 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 tool's function: '根据 Instagram 用户名获取公开用户信息' (get public user info by Instagram username). It specifies the resource (user info) and the key (username), and differentiates itself from siblings like instagram_get_user_info_by_profile_url by explicitly mentioning the username-based input. The additional note '用户已提供 username 时直接使用' reinforces the intended use case.

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

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

The description provides a clear context: 'when user has already provided username, use directly.' This tells the agent when to use this tool. It does not explicitly name alternatives or state when not to use it, but the sibling names and the parameter schema's instruction to avoid URLs indirectly convey that. The lack of an explicit exclusion for profile URLs leaves a small gap, so it fits the 'clear context, no exclusions' category.

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

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

注解已表明 readOnlyHint=true 和 openWorldHint=true，描述进一步说明返回的是分页列表，且仅包含公开帖子，为代理提供了注解之外的行为上下文。但描述未说明分页大小、限流或其他边界情况，部分留白。

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

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

主体描述高度简洁，一句完成；参数注释虽长但包含大量关键约束（如不得修改令牌），属于高密度、高价值信息，没有冗余。

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

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

对于带分页的只读列表工具，描述加参数说明已覆盖绝大多数使用场景，且具有输出 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 描述覆盖率 100%，已对 profile_url 和 page_token 分别进行了详细说明，包括来源、格式要求以及使用注意点（如不得修改令牌、换页需传回等）。描述额外补充了 page_token 的不透明性和有效期上下文，信息量足。

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

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

描述明确说明工具功能：“根据 Instagram 用户主页链接分页获取该用户发布的公开帖子列表”，动词（获取）+ 资源（用户公开帖子列表）+ 分页方式（按主页链接），且与兄弟工具（如按用户名获取、搜索等）区分明显。

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

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

描述清楚说明何时使用：当有用户主页链接时需要分页获取公开帖子列表；同时隐含不使用本工具的条件（如不具备链接时应使用其他工具），page_token 的详细使用说明也帮助代理正确使用。

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds that the tool is paginated ('分页获取'), which is a behavioral trait not explicitly in annotations. However, the schema provides extensive pagination details (e.g., how to handle next_page_token), so the description adds minimal extra transparency 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 a single sentence with no filler. It front-loads the primary purpose and immediately includes the usage hint. Every word earns its place; the structure is compact and efficient.

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

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

The tool is simple (2 params, 1 required, no nested objects) and has an output schema, so return value details are covered structurally. The description covers the core purpose and the key usage condition. With thorough schema parameter docs and appropriate annotations, nothing critical is missing for an agent to call this tool correctly. The only minor gap (explicit sibling differentiation) is a usage-guideline concern, not completeness.

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%; both 'username' and 'page_token' have detailed descriptions in the schema itself (including how to copy usernames and that page_token is opaque). The tool description adds no additional parameter semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states the verb '获取' (get) and the resource clearly: '根据 Instagram 用户名分页获取该用户发布的公开帖子列表' — fetching public posts for a given username with pagination. It also adds a usage hint ('用户已提供 username 时直接使用') that clarifies the input source. This distinguishes it from siblings like instagram_get_user_posts_by_profile_url by explicitly restricting to usernames.

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

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

The description provides a clear condition for when to use the tool: '用户已提供 username 时直接使用' (use directly when the user has provided a username). However, it does not mention alternatives (e.g., the profile URL variant) or explicitly state when NOT to use it. This is clear context without exclusions, matching a 4.

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 description adds value by disclosing the 240-second wait behavior and the instruction not to re-trigger processing. It does not contradict annotations and provides useful additional context beyond 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 sentence that packs three key pieces of information—job_id sourcing, timing, and non-reprocessing—without redundancy. It is front-loaded with the core query action and efficiently communicates all critical guidance.

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 the simple single-parameter input, the description covers everything an agent needs: how to obtain job_id, how to behave during polling, and what not to do. No critical context 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?

The schema description covers the job_id parameter at 100%, so baseline is 3. The description adds nuanced semantics: it explains the source of job_id (user-provided vs. from submit tools) and emphasizes reusing the same job_id without re-submitting. This enriches the parameter usage beyond the schema description.

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 queries an Instagram speech-to-text task by a valid job_id, and explicitly contrasts it with submit tools. It is unambiguous about the resource and action, and the reference to submit tools differentiates it from siblings.

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 guidance: use the user-provided job_id if available, otherwise use the job_id returned by submit tools. It also specifies the 240-second wait limit and states not to re-trigger processing or re-submit, giving clear boundaries and alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description need not repeat that. The description adds value by explaining that the search returns public posts and that pagination with page_token must be used for further pages. It also clarifies that the token must be passed back unchanged and that it's only valid for the same keyword chain. This goes beyond annotations but could be slightly more explicit about what result data contains (though output schema exists). Given annotations cover safety, a 4 is appropriate; no contradiction found.

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 paragraph with front-loaded purpose and usage conditions. It is efficient but a bit packed; splitting into shorter sentences could improve scannability. However, every sentence contributes value; no filler. Slightly less than perfect due to density, but well-structured overall.

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

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

Given the tool has output schema (so return values are covered there), 2 parameters with full schema coverage, and annotations for safety, the description covers the essential usage context: when to use, how to paginate, and what not to pass as keyword. It falls short of 5 because it does not explicitly mention that search results may be time-limited or that pagination has a limit, but with the existing structured data, the description is largely complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds meaning for keyword by specifying what NOT to pass (post links, user links, post_id, username, page_token) and for page_token by detailing the opaque nature, chain validity, and handling on keyword change. This goes beyond the schema's basic descriptions, so it exceeds 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?

The description states a specific verb+resource: '按搜索词搜索 Instagram 公开帖子' (search Instagram public posts by search term). It clearly distinguishes from siblings by listing alternatives: use post detail for existing post links, user info tools for profile URLs or usernames, etc. This differentiates from all sibling tools effectively.

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 guidance: '用户需要按搜索词查找帖子时使用' (use when user needs to find posts by search term). It also gives clear exclusions: use other tools for post links, post_id, user profile links, or usernames. It further specifies pagination usage with page_token and warns against reusing tokens across different keywords, which is crucial practical 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 description discloses key behavioral traits beyond annotations: the async nature, the 240-second wait, and that it returns a job_id with a follow-up query action when incomplete. It also states unsupported post types. No contradictions with annotations (readOnlyHint false, not idempotent, not destructive) — the description adds useful context about side effects and timing.

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, then adds constraints and async behavior. While long, every clause carries crucial information and there is 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 an async submission tool with a single parameter and output schema present, the description covers the essential points: target resource, unsupported types, timeout behavior, and the returned job_id with next-step implication. The agent has enough to decide when to call it and 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?

Schema coverage is 100% (only post_id), but the description adds significant value: instructs to use the provided post_id verbatim, or copy from search/detail results, and warns against passing shortcodes, usernames, profile links, or share text with URLs. This goes well beyond the schema's brief description.

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 submits a speech-to-text task for Instagram video posts or Reels using a post_id, and explicitly excludes image and carousel posts. It distinguishes itself from the URL-based sibling by specifying 'by post_id', and names the resource and action unambiguously.

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

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

The description provides clear negative guidance (image/carousel posts not supported) and explains the async wait behavior with a max 240s timeout, implying when to use this tool versus querying the job status. However, it does not explicitly contrast with the sibling instagram_submit_video_speech_text_by_post_url, though the naming and context make the distinction obvious.

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

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

The description adds behavioral context beyond the provided annotations: it discloses the async nature (waits up to 240 seconds), the unsupported post types, and the fallback response (job_id and next query action). Annotations only provide generic hints, so this description fills in the workflow significantly.

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

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

The description is a single sentence that packs in the core purpose, exclusions, timeout, and return behavior without any filler. Information is front-loaded: the main action and resource come first, followed by constraints and workflow. No unnecessary words or vague phrases.

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

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

Given that an output schema exists (as per context), the description appropriately omits detailed return values. It covers the essential points: what submissions are supported, what are excluded, the async wait, and the behavior on timeout (job_id and next step). The success case is implied but not explicit, yet the presence of an output schema mitigates this gap.

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

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

The schema has 100% coverage, and the post_url parameter description is highly detailed: it specifies copying the share_url from search/detail results and warns against passing author homepage, comment, or API endpoint links. This provides concrete, actionable guidance that goes beyond the type, justifying a score above the baseline.

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

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

The description clearly states the verb 'submit' and the resource 'speech-to-text transcription task for Instagram video posts or Reels', and explicitly excludes image and carousel posts. It distinguishes itself from the sibling instagram_submit_video_speech_text_by_post_id by input method (URL vs ID), ensuring no ambiguity.

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

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

The description provides clear context: use for video/Reels only, not for image/carousel posts. It also mentions the async wait of up to 240 seconds and the fallback returning job_id for follow-up, indicating when to use this tool. While it doesn't explicitly name the by_post_id alternative, the exclusions and timeout guidance effectively guide usage.

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 confirm readOnlyHint and openWorldHint, and the description aligns by stating it 'queries' the balance. It adds useful context that the resource is tied to the API key account and mentions points/balance synonyms. This goes beyond the annotations without contradicting them, so a 4 is justified.

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, concise sentence that fully conveys the operation. No fluff, no redundancy, and the key information (balance) is front-loaded. Perfectly efficient.

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

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

For a parameterless, read-only tool with an output schema and annotations, the description is complete. It provides all necessary context: what is queried and the scope (current API key account). Nothing essential is missing.

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

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

The tool has zero parameters, so per the rubric, the baseline is 4. The description further clarifies that the account is derived from the API key, which a parameterless endpoint implies. No additional parameter documentation is needed.

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

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

The description states a specific verb ('查询', i.e., query) and a clear resource (SocialDataX points balance for the current API key account). It is unambiguous and distinct from all Instagram-oriented sibling tools, making its purpose 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?

There are no competing tools for balance checks, so explicit alternatives are unnecessary. However, the description doesn't state when to use this (e.g., 'Use when you need the remaining points for your account'), which is a minor gap. Since the purpose is obvious and no alternatives exist, a score of 4 is appropriate.

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