twitr.sh

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

No annotations are provided, so the description carries the full burden. It discloses read-only nature, pricing model, and mandatory constraints. It does not cover auth requirements or rate limits, but the pricing context is valuable behavioral insight.

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 (two sentences plus a guidance line), front-loaded with the main action, and every sentence adds value. No 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 fully covers input parameters and their constraints. However, given no output schema, mentioning the variable output format by kind would improve completeness. Still, it is largely sufficient for a read tool.

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?

With 100% schema description coverage, the description adds significant meaning beyond the schema: it explains fixed vs per-item billing, the mandatory resultsLimit for some kinds, and the conditional requirement for 'q'. This enhances parameter understanding.

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 reads an X/Twitter Community with specific actions (profile info, rosters, tweets, search). It uses specific verb 'Read' and resource 'X/Twitter Community', distinguishing it from siblings like x_community by covering multiple operations.

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?

Provides explicit guidance on when to use each 'kind', pricing implications (fixed vs per-item), mandatory parameter (resultsLimit), and additional requirement (q for search). This fully informs selection within the 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?

Discloses payment settlement and idempotency-key requirement, and that the tool acts on a connected handle. However, no safety warnings about deletion irreversibility or error behaviors, and no discussion of rate limits or authorization beyond account requirement. With no annotations, more behavioral context would be beneficial.

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 paragraphs: purpose statement then guidance. Front-loaded with main functionality. Efficient but could be slightly more structured (e.g., bullet points). No 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?

Covers action mapping, prerequisites, and key constraints (payment, idempotency). Missing details on how to obtain community IDs, error handling, or post-action outcomes. Adequate but not fully complete given the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by mapping actions to parameters (e.g., create requires name, delete requires community_id and community_name) and noting optional fields. This explains conditional usage beyond 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?

Clearly states it manages X/Twitter communities with four specific actions (create, join, leave, delete). Distinguishes from sibling tools like x_communities (likely for listing) and other X 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?

Provides explicit prerequisite (connected X account), action-to-parameter mapping, and required fields. Lacks explicit when-not-to-use or alternatives, but the action-specific guidance 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?

With no annotations, the description must carry full weight. It discloses that the tool returns text variants with scores and suggestions, and mentions the flat price. It does not mention side effects like account interaction or draft persistence, which would be beneficial but not critical for a composition tool.

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 sentences plus a concise guidance block. It front-loads the action, groups related information, and avoids redundancy. Every sentence adds value, from the overview to the step-specific requirements.

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 11 parameters, no output schema, and no annotations, the description covers the tool's functionality well. It explains the three modes, required vs optional parameters, and return values. Minor gaps: it doesn't clarify whether drafts are saved or if the tool interacts with the account, but the core use is fully specified.

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 has only 9% description coverage (just 'step' has a short note). The description compensates fully by listing all parameters grouped by step (topic, goal, tone, etc.) and explaining their roles. It adds meaning beyond the schema, making the parameter intent clear despite minimal 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 identifies the tool as a Twitter compose assistant with three distinct steps (generate, refine, score), each with specific inputs. It differentiates from siblings like x_write and x_read by focusing on draft creation, refinement, and scoring rather than posting or reading tweets.

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 guidance on when to use each step and which parameters are required or optional. It mentions pricing but does not explicitly state when not to use the tool or contrast with alternatives. However, the step-based instructions are clear enough for an agent to pick the correct mode.

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 no annotations, the description carries full burden. It discloses provably fair randomness, crypto-random selection, fixed pricing, hard cap on estimatedEntries, payment settlement, no auto-refund, and idempotency key behavior. This is thorough but could mention error handling or validation.

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 moderately concise, front-loading the purpose and then systematically covering parameters, pricing, and idempotency. Each sentence adds value, though it could be slightly tighter.

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 no output schema and 13 parameters, the description covers most aspects but omits what the tool returns (e.g., confirmation, draw ID). It explains pricing and idempotency fully, but the lack of return value information leaves a 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?

Only 15% of parameters have schema descriptions, so description must compensate. It does so by listing all optional parameters (backupCount, mustRetweet, etc.) and explaining estimatedEntries (default 1000, max 10000) and pricing. This adds meaningful context beyond 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 tool's purpose: 'Run a provably fair giveaway on X/Twitter: pick crypto-random winners from a tweet's replies' with specific conditions. This distinguishes it from sibling tools like x_compose or x_read, which have different functions.

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 usage guidance: requires tweetUrl, lists optional parameters, explains pricing model (fixed upfront, hard cap), and warns about payment and refund policy. It implicitly suggests when to use (for giveaways) but does not explicitly compare to 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?

No annotations are provided, so the description carries the full burden. It discloses async behavior (claim check, polling status_url), billing per result, and idempotency requirement. However, it does not detail error conditions, rate limits, or what happens on failure, leaving some gaps.

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 somewhat long but well-structured with a clear first sentence summarizing the tool, followed by bullet-point-like guidance. It front-loads the core purpose. A slightly more concise presentation of the extractor mappings could improve readability, but overall it earns its length.

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 complexity (14 parameters, 23 extractors, async execution, billing, idempotency), the description covers key aspects: extractor selection, target parameters, mandatory limit, async flow with polling, and idempotency. It lacks output schema details but describes the response shape. Error handling is not addressed, which is a minor gap for a complex tool.

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 only 14%, so the description must compensate. It adds significant value by mapping each extractor to the appropriate target parameter (e.g., targetUsername for follower/following extractors), clarifying resultsLimit as mandatory and billed, and explaining the async response structure. While not all 14 parameters are individually described, the mapping covers the critical ones.

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 it bulk-exports X/Twitter data as downloadable datasets, listing 23 specific extractors. This verb+resource specification differentiates it from sibling tools like x_read or x_write, which serve different purposes.

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 guidance on selecting extractors based on target parameters (e.g., targetTweetId for reply/repost/quote extractors), notes that resultsLimit is mandatory and billed, and explains the async workflow. It also mentions the Idempotency-Key header for retries, offering clear when-to-use 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?

With no annotations, the description carries the full burden of behavioral disclosure. It discloses critical traits: billing per item returned, the ownership restriction (only for handles this wallet connected), and the 'acts AS that account' behavior. These are non-obvious, significant behaviors that an agent must know before invoking the tool.

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 yet comprehensive, front-loading the purpose and organizing guidance into a clear block. Every sentence adds value, with no filler. The slight repetition of 'billed per item' is acceptable given the need to emphasize the cost implication. The structure supports quick scanning by 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?

The description covers prerequisites, scoping, action selection, billing, and parameter requirements very well. However, it does not describe the return format or pagination behavior beyond the maxId parameter in the schema. Since there is no output schema, a brief note on what each action returns would make it fully complete. Overall, it is highly complete for a complex multi-action tool.

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?

Even though schema coverage is 100%, the description adds cross-parameter semantics that the schema lacks. It maps actions to their relevant parameters (e.g., 'action=bookmarks (optional folderId)' and 'dm_history (target_user_id required)') and clarifies the purpose of resultsLimit as a billing control. This enhances understanding beyond the individual parameter 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 'Read' a specific resource: 'a connected X/Twitter account's private surfaces' and enumerates the exact surfaces (bookmarks, bookmark folders, notifications, DM history). This specific verb+resource combination distinguishes it from sibling tools like x_timeline or x_profile, which target public or different data.

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 prerequisites (connect an X account), explains that reads act as the connected account, and gives conditional parameter guidance (e.g., 'dm_history (target_user_id required)' and 'bookmarks/notifications/dm_history are billed per item — set resultsLimit'). This goes beyond a simple when-to-use by specifying exact usage scenarios and exclusions.

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?

No annotations are provided, so the description carries the full burden. It clearly states the tool is for reading, but does not disclose any rate limits, authentication requirements, error behavior, or pagination details. The billing mention adds some transparency, but more behavioral context would be helpful.

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 and well-structured, with two clear paragraphs: the first states the tool's purpose, the second provides usage guidance. Every sentence adds value without unnecessary 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?

Given the tool has 6 parameters (3 required), no output schema, and moderate complexity, the description covers the essential aspects: what it reads, how to specify kind and ID, mandatory resultsLimit, and optional time filters for tweets. It does not explain return format or error conditions, but for a read tool with no output schema, it is fairly 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 description adds significant meaning beyond the input schema. It explains the possible values for 'kind' (tweets, members, followers), clarifies that 'id' is a list ID, emphasizes that 'resultsLimit' is mandatory and billed per item, and notes that 'sinceTime', 'untilTime', and 'includeReplies' are supported only when kind=tweets. Schema coverage is 50%, and the description compensates well.

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 'Read' and specifies the resource (an X/Twitter List) along with the three things that can be read: combined tweet timeline, member roster, or followers. This specificity differentiates it from sibling tools like x_timeline or x_search.

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 guidance on how to use the tool: it explains the 'kind', 'id', and mandatory 'resultsLimit' parameters, and notes that for 'tweets', optional 'sinceTime', 'untilTime', and 'includeReplies' are available. It also mentions billing per item. However, it does not explicitly state when not to use this tool or suggest alternative 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?

With no annotations provided, the description fully discloses behavioral traits: prepaid billing with hard stop at expiry, no refunds, extension refusal within 5 minutes, event type restrictions per monitor type, and payment options. It also explains how to poll or set up webhooks, making agent behavior predictable.

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 well-structured with sections for purpose, guidance, and payment, but it is quite lengthy and contains some repetition (e.g., mentioning prepaid nature multiple times). It is front-loaded with the most important information, but could be slightly more concise without losing 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?

Given the tool's complexity (7 parameters, two actions, payment, polling/webhooks, event types), the description covers all necessary aspects for agent usage: creation, extension, event filtering, billing, error conditions, and output delivery mechanisms. No output schema is provided, but the description explains how events are retrieved (polling or webhook), making it 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?

Although schema coverage is 100%, the description adds significant context beyond the schema: it explains the purpose of each parameter (e.g., 'username' for account monitor, 'query' for keyword with max length), lists all 21 event types with their applicability, and clarifies default behavior (default event types, default hours). This helps agents choose correct values.

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 monitors X/Twitter accounts or keyword queries in real time, listing specific event types. It distinguishes itself from sibling tools like x_radar (monitoring) by emphasizing real-time delivery via webhooks and polling, and from x_read/x_search by focusing on continuous monitoring rather than one-time reads.

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 guidance for when to use create vs extend, including prerequisites (Idempotency-Key header, payment methods). It warns against re-polling paid reads and advises using webhooks for agent integration. The section on prepaid hours and expiry clarifies usage boundaries.

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?

No annotations present, so description carries full burden. Discloses payment settlement before change, idempotency-key requirement, and how actions (update_profile, set_avatar, set_banner) work. No mention of side effects or destructive behavior beyond editing.

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?

Three clear sentences with a guidance block. Front-loaded purpose and essential details. No redundancy, but could be slightly more compact without losing completeness.

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 7 parameters, no output schema, and no annotations, the description covers prerequisites, actions, payment, and idempotency. Missing details on return values or error conditions, but acceptable for a mutation tool.

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% (baseline 3). Description adds value by grouping parameters per action, e.g., 'action=update_profile (any of name, description, location, url)' which clarifies conditional parameter usage beyond 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?

Clear verb 'Edit' and specific resource 'connected X/Twitter account's profile' with explicit fields (display name, bio, location, etc.). Distinguishes from sibling tools like x_compose or x_write.

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

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

Explicit prerequisite stated ('PREREQUISITE: connect an X account') and constraint ('Acts only on handles this wallet connected'). Guidance on action parameter usage provided, but no explicit when-not-to-use or alternatives 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?

No annotations are provided. The description adds cost info ('flat sub-cent price') and pagination behavior ('use report.next_cursor'). It does not mention auth needs, rate limits, or whether the tool is read-only. For a read tool, this is adequate but could include more about data freshness or limits.

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 paragraphs: the first states purpose and cost, the second gives parameter and pagination guidance. It is mostly concise, but the price mention could be integrated more smoothly. No redundant sentences.

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

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

Given the tool has 6 optional params, no output schema, and no annotations, the description covers the main behavioral aspects (cost, filtering, pagination). It could be improved by mentioning the structure of returned items or typical response format, but it is fairly complete for its purpose.

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 6 params with 50% description coverage. The description adds value by indicating all filters are optional and grouping them, and explaining the 'after' parameter for pagination. This compensates for the missing schema descriptions on hours, limit, and region.

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 it provides 'trending topics and breaking stories' across multiple categories, with specific sources and filters. This distinguishes it from sibling tools like x_read (reading content) or x_search (searching). The verb 'aggregates' and resource 'topics/stories' 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 frames it as 'the cheap first stop for what is happening right now', implying it's for quick trend overviews. It lists optional filters and pagination. However, it does not explicitly say when not to use it or compare to alternatives like x_search or x_monitor.

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?

Without annotations, the description fully discloses behavior: all operations are read-only (no side effects), pricing is per-call (per-result for followers-you-know), failed calls are not charged, and download-media links expire in 7 days. No hidden surprises.

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 paragraphs: the first gives a high-level overview; the second is a dense, structured guidance list. Every sentence adds necessary detail with no fluff.

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 8 parameters and no output schema, the description covers all resources, their parameters, pricing, and side effects (no authentication, link expiry). It is complete enough for correct selection and 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%, but the description adds critical context: batch limits, download-media limit ≤50, default WOEID, and the fact that resultsLimit is mandatory and billed per result. This is far beyond the schema's basic type constraints.

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 opens with a clear verb ('Read') and lists specific resources (tweet, user, batch, trends, etc.), immediately distinguishing it from sibling tools like x_write or x_compose.

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 'Guidance:' section explicitly maps each resource to its parameters, constraints (e.g., batch ≤100, followers-you-know requires resultsLimit), and pricing model. This tells the agent exactly when to use each variant.

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?

No annotations provided, so description carries full burden. Discloses billing per tweet, mandatory resultsLimit, and pagination for users. Does not mention any destructive behavior, but search is inherently non-destructive.

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?

Description is well-structured with a guidance section and front-loaded purpose. While it could be slightly more concise, every part adds value and aids 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 16 parameters, no output schema, and no annotations, the description provides a comprehensive overview of search functionality, including pagination for users. Lacks details on return format, but overall sufficient.

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 44%, but the description adds meaning for many parameters beyond the schema, such as explaining operator syntax, billing, and pagination. Compensates well for the low 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 clearly states the tool searches X/Twitter tweets or user profiles with a full operator set. It distinguishes from siblings like x_timeline and x_monitor by focusing on search with advanced filtering.

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?

Provides explicit guidance on when to use search-tweets vs search-users, mandatory resultsLimit for tweets, and billing per tweet. However, it does not mention when not to use this tool or list specific alternatives among siblings.

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?

Without annotations, the description must disclose behavioral traits. It states that results are billed per item and that resultsLimit is mandatory, implying a cost-aware read operation. It does not mention idempotency, rate limits, or authentication requirements. Since it is a read tool, no destructive behavior is expected, but more context would improve transparency.

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 well-structured with two paragraphs: the first states the main purpose and scope, the second provides usage guidance. Sentences are concise and avoid redundancy. It is slightly long but every sentence adds value, and the critical information is front-loaded.

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

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

Given 9 parameters and no output schema, the description covers the core usage: timeline types, mandatory resultsLimit, and optional filters. It explains what is returned (tweets, lists, engagement data) but does not detail the response format or pagination. For a complex tool, this is mostly 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 33%, so the description adds significant value. It lists all 'kind' enum values, explains their mapping to user/tweet IDs, and describes optional filters as 'search-operator filters.' The 'resultsLimit' parameter is reemphasized as mandatory and billed. This goes beyond the schema, though some parameters (e.g., 'language') are not detailed individually.

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 it fetches a user's X/Twitter timeline and enumerates specific sub-timelines (tweets, replies, likes, media, mentions), follower/following lists, and engagement lists. The verb 'fetch' and resource 'timeline' are specific, and the scope is well-defined, distinguishing it from sibling tools that likely handle other X operations.

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 guidance on how to use the 'kind' parameter with all enum values and emphasizes that 'resultsLimit' is mandatory and billed per item. It also mentions search-operator filters. However, it does not explicitly state when to use this tool vs. alternatives (e.g., x_search) or when not to use it, which slightly reduces clarity.

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 no annotations, the description carries the full burden and does a stellar job: it discloses server-side ownership checks, non-refundable payment before execution, the possibility of pending_confirmation with actionId, and the mandatory Idempotency-Key for safe retries. This is far beyond basic mutation disclosure.

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 long but exceptionally well-structured: a one-sentence overview, a clear 'Guidance:' section, and a compact action-to-parameter map. Every sentence carries operational weight, and the formatting makes dense information scannable, though it is not 'short'.

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 complexity (12 actions, 10 params) and no output schema, the description covers prerequisites, auth flow, payment behavior, pending-confirmation handling, idempotency, and parameter relationships. It stops short of describing a full success response for every action, but the essential runtime context 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?

The schema already has 100% parameter coverage, but the description adds valuable semantics: it maps each action to its required parameters, clarifies that target_user_id is the numeric ID (not the @handle) and how to obtain it, and notes the 'no @' convention for account. This elevates it beyond a simple schema repetition.

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 immediately states the tool's purpose with a specific verb and resource: 'Act on X/Twitter through an account you connect' and lists all concrete actions (post, reply, like, retweet, follow, etc.). This clearly distinguishes it from read-only siblings like x_read and x_search.

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 prerequisites (connect an X account first), references x_read for obtaining numeric user IDs, and warns against asking for sensitive credentials. It explains when to poll for pending_confirmation and the requirement for an Idempotency-Key, giving clear practical guidance, though it does not explicitly contrast with x_compose or other write siblings.

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