xdataapi: X (Twitter) data

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

While annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds behavioral context by explicitly stating that it returns credits and rate limit, and that it is 'Free' (likely meaning it does not consume quota). This goes beyond the annotations by clarifying the tool's side-effect-free nature in practical terms. 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 entire description is two short sentences, front-loaded with the most important information (credits and rate limit) followed by the 'Free' tag. Every word earns its place; there is no fluff, redundancy, or unnecessary detail. It is an exemplary model of conciseness for a simple status tool.

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's simplicity (no params, no output schema), the description adequately covers the return value at a high level (credits and rate limit) and the operational context ('this key', 'Free'). The only minor gap is the lack of detail on the exact response format or field names, but with no output schema and a clearly trivial resource, this is not a serious omission.

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

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

The tool has zero parameters, so the schema carries no burden. The description still adds meaning by referencing 'this key', which implicitly tells the agent that the tool operates on the current authentication context. This is useful context that the empty schema cannot provide, so the baseline for 0 params is met and slightly enhanced.

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 resource ('this key') and the data returned ('credits left' and 'rate limit'), which clearly distinguishes it from all sibling tools that fetch tweets or users. However, it lacks an explicit verb like 'gets' or 'returns', relying on the title 'Balance' to imply the action. It is still specific enough for an agent to understand the tool's purpose.

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 offers no explicit guidance on when to use this tool versus alternatives, nor does it mention any exclusions. The phrase 'Free' hints that it can be called without cost, which implies a pre-flight check, but this is not stated. The intended use (checking credits/rate limit before other calls) is only implicit, not articulated.

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, idempotentHint, and destructiveHint false. The description adds important behavioral details: cost per ID (0.02 credit), cache behavior relative to get_followers, and that a 403 is free. These go beyond the annotations and help the agent anticipate costs and error handling.

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 concise: four short sentences each carrying distinct information (purpose, cost, cache behavior, error cost). It is front-loaded with the core purpose and contains no filler. Every sentence 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 tool with 4 parameters and no output schema, the description covers purpose, cost, caching, and error handling. It does not explicitly describe the response format (though 'numeric ids' implies a list), but the schema documents cursor and count constraints. It is sufficiently complete for an agent to call 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 75% (user, fresh, cursor have descriptions; count does not). The tool description does not add any parameter-specific guidance. Since the schema already documents most parameters, the description adds no extra value, so it stays at the baseline of 3.

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

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

Description clearly states it returns numeric IDs of followers and explicitly distinguishes from get_followers by saying 'no profiles'. It names the resource (follower ids) and the verb (get), making its purpose 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?

It gives a specific usage context by noting it shares the same page as get_followers and that a page read there is a cache hit, implying it's cheaper after fetching profiles. It also implies 'no profiles' as a reason to choose this tool when profiles aren't needed. It lacks an explicit 'use instead of X when...' statement but provides 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 already declare readOnlyHint=true and idempotentHint=true, but the description adds non-obvious behavior: '0.1 credit per profile' reveals the cost model, and 'Not every account tier can read this; a 403 is free' clarifies an authorization failure mode and its cost implication. This is valuable 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 three short sentences, each carrying distinct information: what it returns, pricing, and authorization behavior. It is front-loaded with the core purpose and has zero 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?

With no output schema and a sibling tool named get_follower_ids, the description should clarify whether full user objects or IDs are returned gradations. It also omits response shape, pagination behavior, and how cursor/count work in practice. The account tier and cost notes are helpful but leave important operational gaps.

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 75% (user, fresh, cursor have descriptions), so the baseline is 3. The description's credit-per-profile mention indirectly relates to count but does not directly explain any parameter. It adds little 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 says only 'Followers of a user', which is a noun phrase rather than an explicit action like 'List' or 'Retrieve'. It conveys the resource and owner but does not distinguish this from the sibling get_follower_ids, leaving it unclear whether full profiles or just IDs are returned.

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 is no guidance on when to choose this tool over alternatives. The note about account tiers implies a prerequisite, but it never mentions get_follower_ids or when IDs-only would be more appropriate, so an agent gets no routing help.

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, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and idempotency. The description adds value by disclosing the per-profile credit cost (0.1 credit) and the access limitation that some account tiers may receive a free 403, which is not present in the annotations.

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

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

The description is three short sentences with no filler: the core purpose comes first, followed by cost and access caveats. It is efficient and easy to scan, though starting with an imperative verb like 'Get' would improve structure slightly.

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 annotations covering safety, the description covers cost and access, but it does not specify whether 'Accounts' means full profile objects or just IDs, which matters given sibling tools like get_follower_ids. Pagination is inferred from the cursor parameter in the schema, but with no output schema, an explicit statement of return format would make the tool more 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 coverage is 75% with clear descriptions for user, fresh, and cursor, but count lacks a description. The description does not add direct parameter-level meaning; the '0.1 credit per profile' line hints at count's effect on cost but does not explain its semantics. With moderate schema coverage, the description could do more but does not contradict or significantly enhance 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 'Accounts a user follows' clearly identifies the tool's resource, and the pairing with sibling tools like get_followers and get_follower_ids makes the distinction easy to infer. It lacks an explicit verb such as 'get' or 'list', so it is not as direct as it could be, but the meaning 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 implies the tool is used to retrieve the accounts a user follows, which sets it apart from siblings, but it does not explicitly state when to choose this over alternatives like get_followers or get_follower_ids. No exclusion criteria or alternative recommendations are provided; the account-tier caveat is a behavioral warning, not 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the sort order ('newest first') and the credit cost ('1 credit per tweet'), which are behavioral details not present in the annotations or schema.

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

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

A single sentence conveys the core purpose and key behavior. It is front-loaded with the primary function and includes ordering and cost without wasted words.

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 adequate for a simple read tool: it states the resource and ordering. However, it does not explicitly mention that the required id parameter is the tweet ID, nor does it describe pagination behavior (though cursor is in the schema). For a tool with only one required parameter and no output schema, this is acceptable but not comprehensive.

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 50% (fresh and cursor have descriptions; id and count do not). The description does not mention any parameters, so it fails to clarify the meaning of id (likely the tweet ID) or count. It adds no value beyond the schema, and for the undocumented parameters it leaves the agent without explicit 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?

The description clearly states the resource ('Tweets that quote a tweet') and the ordering ('newest first'), distinguishing it from siblings like get_retweeters (retweets) and get_replies (replies). The action is implied by the tool name and context, making the purpose 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?

There is no guidance on when to use this tool versus alternatives such as get_retweeters or get_replies. The description does not mention any conditions, exclusions, or alternate tools, leaving the agent to infer usage solely from the name and purpose.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds cost ('1 credit per reply') and pagination scope ('one page'), which are useful beyond the annotations. However, it does not disclose behaviors such as caching behavior, rate limits, or exceptional behavior, so the added value is moderate.

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 clauses: 'Direct replies to a tweet, one page. 1 credit per reply.' It is front-loaded with the core behavior and contains no filler. 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?

The description plus schema and annotations cover the primary calling needs: what the tool does, required id, pagination scope, and cost. However, there is no mention of the return payload structure or edge cases, and no guidance on how to chain pages beyond the cursor schema description. It is adequate but with clear gaps.

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 description does not elaborate on any of the parameters. Schema coverage is 67% (id has only a pattern, no description), so the description should compensate for the undocumented id but does not. 'fresh' and 'cursor' are only described in the schema, and the description adds no semantic meaning beyond it.

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: 'Direct replies to a tweet' and adds the pagination scope 'one page.' It implies a distinction from quote tweets or retweets, but it does not explicitly name an alternative sibling. This makes the purpose clear but not fully differentiated.

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 offers no 'when to use' context, no mention of alternatives, and no conditions that would route an agent toward get_quotes, get_retweeters, or search_tweets. Any usage guidance must be inferred indirectly from the tool name and the sibling list.

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, openWorldHint, and idempotentHint, but the description adds meaningful behavioral context: the credit cost per profile and the possibility of a 403 for restricted account tiers. This covers authorization and cost behavior not present in annotations. It does not mention pagination details, but those are partially covered by the cursor parameter description in the schema.

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

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

The description is brief, starting with the core purpose ('Accounts that retweeted a tweet') then adding cost and error context. Each sentence adds distinct information and no words are wasted. Though the first sentence is a fragment, it is immediately informative.

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 cost and tier access, but lacks details on response format, pagination, and parameter semantics for id and count. With no output schema, an agent needs more context about what data is returned for each retweeter. The cursor description in schema helps with pagination, but overall the description is only partially complete for a non-trivial list endpoint.

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 describes fresh and cursor, but id and count lack descriptions. The tool description does not explain that id refers to the tweet ID or that count limits the number of retweeters returned; it only implies the tweet context. With schema coverage at 50%, the description fails to compensate for the undocumented parameters.

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 resource as 'Accounts that retweeted a tweet,' clearly indicating the tool retrieves retweeters for a given tweet. It distinguishes this from siblings like get_quotes and get_replies by the specific resource, though it does not explicitly name alternatives. The verb is implied by the tool name, so it meets the clarity bar.

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 no guidance on when to use this tool over its siblings such as get_quotes or get_replies. It only provides cost and tier restrictions ('0.5 credit per profile. Not every account tier can read this; a 403 is free.'), which are operational notes, not usage selection criteria. No alternative tools 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 declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful traits beyond annotations: per-tweet credit cost and the deterministic ordering of the focal tweet first. It does not mention cursor pagination behavior, but that is partially covered by the schema.

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

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

Two short sentences carry the core behavior and a cost signal with zero filler. The ordering rule is front-loaded and the credit cost is compactly stated.

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 basics needed to invoke it are present: it returns a thread, the focal tweet is first, and credits are per tweet. However, with no output schema, the description leaves the shape of replies and pagination behavior unspecified, so an agent must rely on schema hints and assumptions.

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 descriptions cover fresh and cursor, and the required id is inferable as the focal tweet even though the description does not name it explicitly. With 67% schema coverage and no parameter-level detail in the description, the description provides only marginal semantic aid.

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 the returned resource as 'a tweet with its thread and replies' and specifies the focal tweet comes first, making the tool's job clear. It does not explicitly contrast with siblings like get_tweet or get_replies, so it loses the top point.

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 given about when to choose this over get_tweet, get_replies, or search_tweets. The description implies it is for whole conversation threads, but it never states selection conditions or 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds a cost indicator ('1 credit') and implicitly mentions the fresh parameter's extra cost via schema. This goes beyond annotations by disclosing pricing. It does not contradict any annotation and adds useful behavioral context about cost, which is not present in 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?

The description is two short sentences with zero waste. It front-loads the core function ('One tweet by numeric id') and appends the cost note. Every word earns its place, and the structure is easily scannable for an agent.

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

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

For a simple single-tweet fetch, the description covers the essential: what it returns (tweet with author) and cost. It does not mention return format, but that's not required given no output schema and the tool's simplicity. The annotations handle safety. The description is complete enough for an agent to invoke correctly without missing critical information.

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 50% (only 'fresh' has a description). The description adds 'numeric id' to clarify the 'id' parameter, which is partially compensating. However, it doesn't explain the 'fresh' parameter, though the schema already does. The description provides some meaning for id beyond the schema pattern, but not for all parameters. Overall, it adds marginal value but does not fully cover the gap.

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 operation: fetch a single tweet by numeric id, and notes it includes the author. This distinguishes it from sibling get_tweets (plural) and get_user_tweets (user-scoped). The verb is implied from the tool name but the resource and scope are specific. It could be more explicit about alternatives, but the singular 'tweet' vs plural siblings provides 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?

The description gives no explicit guidance on when to use this tool versus the many siblings. It implies usage for a single tweet by id, but does not mention alternatives or exclusion criteria. For example, it doesn't state 'use get_tweets for multiple tweets' or 'use search_tweets for queries.' The context is partially clear from the name, but the description itself lacks explicit usage direction.

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 read-only, idempotent, and non-destructive, which are covered. The description adds value by disclosing the credit cost per tweet, which is behavioral information not in annotations. It doesn't mention caching behavior beyond the 'fresh' parameter, but the credit cost is a significant addition.

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 sentences, front-loaded with the core action and constraints. No wasted words, and the credit cost is a useful extra.

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 batch read tool with annotations covering safety and idempotency, the description covers the essential purpose, constraints, and cost. There is no output schema, but that is not required. Missing details like caching behavior are minor given the 'fresh' parameter.

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 50% (only 'fresh' has a description). The main parameter 'ids' lacks description, but the description's 'numeric id' and the pattern in schema clarify it. The description adds batch limit and credit cost, which enriches the meaning beyond the schema.

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

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

The description clearly states 'Up to 100 tweets by numeric id in one call' with a specific verb (get), resource (tweets), and key constraint (batch by id). It distinguishes itself from single-tweet retrieval and search by emphasizing batch by ID, though it doesn't name the sibling explicitly.

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 usage for batch retrieval by IDs, and the sibling list clarifies alternatives (e.g., get_tweet for single). However, it does not explicitly state when not to use (e.g., for search by query or user timeline) or name alternatives, but the batch constraint is implicit.

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

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

Annotations already establish readOnly, idempotent, non-destructive behavior. The description adds a concrete operational fact ('1 credit') and the handle-based lookup, but does not disclose caching behavior, freshness semantics, or return characteristics, leaving room for more 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?

Two short sentences with no filler; the core purpose is front-loaded and the credit cost is a useful standalone fact. 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 read-only lookup with fully documented parameters and safety annotations, the description is almost sufficient. The main missing piece is guidance on output shape or when to prefer siblings, but that is already counted under usage guidelines.

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 documents both handle and fresh adequately. The description's 'by handle' and cost are consistent, but it adds no parameter-level guidance beyond the schema, matching the baseline for high coverage.

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 the resource as a single X user's profile addressed by handle, which distinguishes it from sibling tools like get_users, get_user_tweets, or get_followers. It lacks an explicit verb, relying on the tool name's 'get', but the intent 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?

No guidance is given about when to use this tool instead of the many sibling tools, such as get_users for multiple profiles or get_tweets for user content. The description does not state exclusions or alternative conditions.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable beyond-annotation context: a hard batch limit of 100 and pricing behavior of 1 credit per profile 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?

Two short sentences, no filler, and the most important scoping constraint (up to 100 users by handle in one call) is front-loaded. The credit cost is added as a natural second sentence.

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 plus schema give an agent the required handle input, the optional fresh flag, the batch limit, and cost behavior. It is complete for invoking the tool correctly, though an explicit note about the return shape for missing handles would strengthen it further.

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 only 50%; the handles parameter lacks a description in the schema. The description compensates by clarifying that the array values are X handles and that the call accepts multiple users up to 100. The fresh parameter is already described well in the schema.

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

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

The description states exactly what the tool does: fetches profiles for up to 100 X users by handle in one call. The title 'Profiles, batch' and the sibling name get_user make the batch-vs-single distinction 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?

The description implies batch usage with 'up to 100 X users by handle in one call' and the sibling get_user exists for single-user lookups. However, it never explicitly says when to choose this tool over get_user or when not to use it, so the guidance is implied rather than stated.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the tool is safe. The description adds credit cost per tweet and mentions cache bypass via the 'fresh' parameter, which is important behavioral context. However, it does not explain pagination behavior in detail, but the cursor parameter schema covers this somewhat.

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 sentence with no filler, and the key information (newest first, credit cost) is front-loaded. It is clear and to the point.

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's simplicity and the rich schema (100% coverage), the description adequately covers usage. It lacks explicit pagination details, but the cursor parameter and output schema absence do not require extensive explanation. The credit cost is a complete addition, so a small gap remains.

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 each parameter has a description. The description does not add much beyond the schema, but it mentions credit cost and cache bypass, which relates to the 'fresh' parameter, adding value. Baseline is 3, and this slight addition justifies a 4.

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 the latest tweets of a user, sorted newest first, which aligns with the tool name and distinguishes it from siblings like get_user (user profile info) and get_tweets (likely other tweet fetching). The verb 'get' and resource 'user tweets' are specific.

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 mentions the newest-first ordering and credit cost, which provides context for when to use. It does not explicitly state when not to use or name alternative tools, but the sibling list shows many similar tools. However, the tool's purpose is clear enough that an agent can infer when to use it over, say, search_tweets.

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 destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: '1 credit per tweet or profile' discloses the cost model, and 'Top may answer 403 (free)' warns about a possible error condition. This goes beyond the annotations and helps the agent anticipate outcomes.

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 three short sentences with no fluff. It front-loads the core purpose ('X advanced search') and then adds essential facts (operators, cost, availability) in a tight sequence. Every sentence 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 search tool with no output schema, the description covers the key aspects: query format, cost, and product-specific behavior. It does not detail return structure or pagination, but the cursor parameter is documented in the schema. The tool is simple enough that this description is largely complete, though it could mention that People returns profiles, which 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 80%, so most parameters are documented in the schema. The description adds a note about the product parameter's availability (Latest vs Top 403), which is useful, but it doesn't significantly enhance understanding of q, count, fresh, or cursor beyond what the schema already provides. With 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 'X advanced search' with a specific verb and resource. It distinguishes itself from sibling getter tools (like get_tweet, get_tweets) by emphasizing the query-based search with x.com operators, which is unique among the siblings. The tool's purpose 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 provides some usage context by noting product availability ('Latest is always available; Top may answer 403'), but it does not explicitly state when to prefer this search tool over direct fetch siblings like get_tweets or get_user_tweets. The usage is implied rather than explicit, so a clear gap remains in guiding the agent to choose this over alternatives.

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