twitterapi-mcp-server

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 temporal ('current') and location-scoped behavior but does not disclose further traits such as rate limits or data freshness delays; given the annotation coverage, this is adequate but not exceptional.

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 front-loaded sentences: purpose, required parameter, and default guidance. Every sentence earns its place with no filler or repetition.

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

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

For a read-only tool with one required parameter and a simple optional count, the description plus schema covers the essential calling context. There is no output schema, but the returned resource is clear from 'trending topics/hashtags'; still, a note on output format or ordering would make it fully 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 carries the baseline parameter documentation. The description adds value by providing a broader set of common WOEID examples (India, South Korea) and reinforcing the safe default woeid=1, which helps an agent choose the right value.

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

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

The description states a specific verb ('Fetch') and a specific resource ('current trending topics/hashtags for a location'). This clearly distinguishes the tool from the sibling tweet and user-related tools.

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

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

The description gives clear context on required input, common WOEID values, and a default fallback ('Use woeid=1 for global trends if you don't know a specific location'). It does not name alternative tools or explicitly say when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds behavioral context by noting pagination via cursor at ~20 per page and optional time bounds, which are useful operational details not 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?

Three sentences, each carrying distinct value: what it does, when it is useful, and how pagination and time bounds work. The core purpose is front-loaded, and there is no redundant or filler 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?

Despite lacking an output schema, the description covers the essential call behaviors: quote-tweet retrieval, pagination (~20 per page), time bounds, and the includeReplies option is documented in the schema. It omits minor details like ordering or empty-result behavior, but these are not critical for a read-only fetch 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 100%, so the schema already documents all five parameters clearly. The description mostly reiterates time bounds and pagination behavior without adding new meaning beyond the schema, meeting the baseline for full schema 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 opens with a clear verb and resource: 'Fetch quote-tweets (tweets that quote the given tweetId)'. It defines the exact behavior and distinguishes it from reply or retweet tools through the parenthetical, which is essential given the sibling context.

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

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

The description gives a concrete use case: 'finding commentary on a tweet, measuring reach beyond direct replies'. This implies when to use it and signals it is not for direct replies, though it does not explicitly name an alternative sibling like get_tweet_replies.

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 meaningful behavioral context beyond that: it returns only top-level replies, paginates at roughly 20 per page, and provides full tweet objects. This informs the agent about result depth and pagination behavior that annotations do not convey.

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 with no filler. The core action and return payload are front-loaded in the first sentence, and the second sentence provides contextual use cases. Every phrase earns its place.

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

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

For a read-only fetching tool with no output schema, the description explains the return payload ('full tweet objects'), pagination size, and result scope, and suggests when to use it. It stops short of describing the exact shape of a tweet object or handling of edge cases, but is largely complete for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, with each parameter already described (tweetId as numeric ID, cursor for pagination, queryType as sort order with default). The description reinforces the 'root tweet' aspect and top-level nature, but does not substantially extend the schema's parameter explanations, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource ('Fetch replies to a specific tweet') and adds critical detail that it returns top-level replies, which distinguishes it from sibling tools like get_tweet_quotes or get_tweet_retweeters. It also names concrete use cases (thread analysis, sentiment, reply trees), making the tool's purpose unmistakable.

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

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

The description explicitly recommends when to use the tool ('thread analysis, sentiment on a viral post, or building reply trees'), giving clear context for selection. It does not explicitly name alternatives or state when not to use it, but the 'top-level replies' qualifier implicitly steers an agent away from quotes/retweeters tools, so it earns a 4 rather than a 5.

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

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

Annotations already mark the tool as read-only and open-world; the description adds useful behavioral context by stating that it returns user profiles with metadata and paginates via cursor at roughly 100 per page. It does not cover every edge case, but it meaningfully supplements the structured 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?

Three short sentences, all informative: core purpose, key exclusion/alternative, output shape, and pagination. No redundant phrasing; the most important behavioral distinction 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?

For a simple two-parameter read-only tool with full schema coverage, the description is nearly complete: it names the resource, output, pagination, and main alternative. The lack of an output schema is partially offset by 'Returns user profiles with metadata', though exact response fields are not 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?

Schema description coverage is 100%, so the schema already fully documents tweetId and cursor. The description echoes the cursor pagination behavior but does not add significant new semantic detail beyond what is already present 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?

Description uses a specific verb and resource ('Fetch users who retweeted a specific tweet') and explicitly distinguishes itself from the quote-tweet tool by name. An agent can immediately see what this tool does and how it differs from get_tweet_quotes.

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 clearly states the scope (simple retweet action), explicitly excludes quote-tweets, and names the alternative tool to use for that case. This gives the agent direct routing guidance with no ambiguity.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful return-content context (author, text, engagement counts, media), but does not disclose edge cases like invalid IDs, missing tweets, or rate limits. Given the annotation coverage, this is acceptable but not rich.

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

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

Three sentences with no wasted words. The primary action and input format are front-loaded, followed by a clear use-case rationale. Every sentence adds value, and the structure lets an agent quickly decide whether this is the right 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?

For a single-parameter, read-only batch fetch tool with strong annotations and a detailed parameter description, nothing critical is missing. The description explains what the tool returns, when to use it, and the input constraints, making it fully actionable without an output schema.

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

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

Schema description coverage is 100%, and the parameter's schema already documents that tweet_ids is a comma-separated string of up to 100 numeric strings. The description essentially repeats this information without adding new parameter-level insight, 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 uses a specific verb ('batch-fetch') and a clear resource ('full tweet objects by numeric tweet IDs'), immediately distinguishing it from sibling tools that handle searches, replies, or user timelines. It states the exact input format and the payload contents, leaving no ambiguity about what the tool does.

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 clearly states when to use this tool: 'when you already have specific tweet IDs' and need full tweet data, with concrete examples of where those IDs come from. It does not explicitly name alternatives or state when not to use it, but the guidance is contextually strong enough to prevent confusion with search_tweets or user-centric tools.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral nuance: the extra metadata is only available 'when available,' and the tool returns data beyond what get_user_info provides. It doesn't detail rate limits or failure modes, but the read-only annotations lower that burden.

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 tight sentences: verb and resource, value relative to get_user_info with an availability caveat, and explicit usage order. There is no filler and the core scope 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?

For a one-parameter, read-only tool, the description sufficiently covers what it does, when to use it, and how it relates to get_user_info. No output schema exists, so return specifics are only described vaguely as 'extra profile metadata,' but that is adequate for 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 description coverage is 100%: the userName parameter is already described as a Twitter/X screen name without @ that fetches the profile about/bio page. The description only restates 'by screen name' and adds no additional parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Fetch the extended about/profile page data for a Twitter/X user by screen name.' It explicitly differentiates from get_user_info by saying it returns 'extra profile metadata beyond what get_user_info gives,' so the agent can distinguish the closest sibling.

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

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

Gives explicit routing guidance: 'Use get_user_info first; only call this if you need additional about-page fields.' It names the alternative tool and the exact condition for choosing this one.

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 the description adds meaningful behavioral details: results are newest-first, paginated via cursor, and incomplete on first call for large accounts. This goes beyond the annotations and gives the agent realistic expectations about data volume and pagination. There is 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 tight and front-loaded: it states exactly what the tool returns, the ordering, metadata scope, pagination mechanism, and a critical warning about large accounts. Every sentence adds value, and there is no redundant or filler 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?

With only three parameters, no output schema, and read-only annotations, the description gives the agent everything needed to call the tool correctly: the resource, the ordering, the metadata shape, and pagination behavior. It is complete for a read-only follower-fetching 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?

The input schema covers all three parameters with clear descriptions, so the baseline is 3. The description adds some context about pagination behavior and the fact that pageSize won't return all followers, but it doesn't add much beyond what the schema already states for cursor and pageSize.

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

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

The description clearly states a specific verb ('Fetch followers'), a specific resource ('Twitter/X user'), and a precise scope (reverse chronological order with full profile metadata). It is easily distinguishable from the sibling get_user_followings because it explicitly says 'followers' and describes follower-specific metadata.

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

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

The description gives concrete use cases: analyzing who follows an account, building follower audiences, and sampling for competitive analysis. It also provides practical guidance about pagination for large accounts. However, it does not explicitly mention alternatives or when not to use this tool, though the use-case framing implies appropriate contexts.

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

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

Annotations already indicate readOnlyHint: true, and the description aligns with that. Adds behavioral context about pagination ('Paginates via cursor') and mentions that full profile metadata is returned, going slightly beyond the annotation.

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 concise sentences: first states the action, second gives the use case. No unnecessary words, front-loaded with the core purpose.

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?

Mentions pagination and profile metadata, giving a sense of the response. Lacks details on error cases or exact response structure, but for a simple read tool with readOnlyHint, 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?

Schema covers all parameters (userName, cursor, pageSize) with descriptions, so coverage is 100%. The description does not add extra clarification for parameters beyond the schema, so 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?

Clearly states the action ('Fetch') and resource ('the accounts a Twitter/X user follows'), and distinguishes from siblings like get_user_followers by focusing on followings. Includes pagination detail and a 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?

Provides a clear use case ('map a user's interest graph') and implies when to use it (when you need followings, not followers). Does not explicitly contrast with alternative tools, but the purpose is unambiguous.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value by enumerating the exact fields returned (which is important since there is no output schema), but it does not disclose additional behaviors such as rate limits, error cases, or handle normalization.

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 sentences, no waste. The first sentence front-loads the core purpose, the second lists return fields and gives usage direction. Every clause 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 single-parameter, read-only tool, the description is complete: it explains the input format via schema, lists return fields in the description, and gives usage context. The readOnly annotation covers safety, so nothing material is missing.

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

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

Schema description coverage is 100%: the userName parameter is fully documented with the no-@ convention and an example. The description merely restates 'by their screen name,' adding no new parameter-level meaning. 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?

The description clearly states the action ('Fetch basic profile info'), the resource (a Twitter/X user by screen name), and lists the returned fields. It implicitly differentiates from siblings by emphasizing 'basic' profile info as the starting point, but it does not explicitly name a sibling like get_user_about to distinguish against.

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 instruction 'Use this as the starting point for any user analysis' provides explicit when-to-use context. It does not name alternatives or state when not to use it, but the starting-point guidance is a strong usage signal given 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 and openWorldHint, and the description adds meaningful behavioral context: newest-first ordering by created_at, cursor-based pagination at roughly 20 tweets per page, and the effect of includeReplies. It does not cover every edge case, such as behavior when both userName and userId are supplied, but with annotations covering the safety profile, this is a strong 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 front-loaded with the most critical usage constraint, then moves to the alternative tool, then the core behavior, parameters, and pagination. Every sentence earns its place; there is no filler or repetition of annotations.

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

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

For a read-only tool with four well-documented parameters, the description covers invocation, parameter selection, ordering, reply inclusion, and pagination, and names the sibling alternative. Because there is no output schema, it leaves the exact result envelope and field-level response format unspecified, but this is a minor gap for selecting and calling 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?

Schema description coverage is 100%, so the input schema already documents all four parameters thoroughly. The description reinforces the either/or relationship between userName and userId and the preference for userId, but it adds little substantive meaning beyond the schema, matching the baseline for high schema 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 verb and resource: fetch the most recent tweets posted by a Twitter/X user, sorted newest first. It further distinguishes itself from search_tweets by explicitly limiting scope to 'latest / recent / what's new' queries, so an agent can differentiate it from siblings without inspecting schemas.

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

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

It gives explicit when-to-use and when-not-to-use guidance with concrete examples: DO NOT use for date-range queries, and for those use search_tweets with a 'from:user since:... until:...' query. This is the strongest possible usage routing for an agent.

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

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

Annotations already declare readOnlyHint and openWorldHint. The description adds useful behavioral details beyond this: time-bound queries via sinceTime/untilTime and pagination via cursor. No contradictions 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?

Three concise sentences: the core operation, the use cases, and the key capabilities. The most important information is front-loaded, and 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 simple read-only mention-fetching tool, the description covers the operation, use cases, time filtering, and pagination. All four parameters are documented in the schema, and no output schema exists, so nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so the description does not add significant meaning beyond the schema. It mentions sinceTime/untilTime and cursor, but those are already well documented in the input 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 a specific verb and resource: 'Fetch tweets that mention a specific Twitter/X user' with an exact definition ('tweets containing @userName'). This unambiguously distinguishes it from siblings like get_tweet_replies, get_tweet_quotes, and get_tweet_retweeters.

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 clear context for when to use the tool: brand monitoring, sentiment tracking, and finding conversations involving an account. It does not explicitly name alternatives or exclusions, but the use cases give sufficient 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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses pagination behavior ('Returns ~20 tweets per page'), ordering ('reverse chronological order' vs 'Top'), and date semantics ('until:' is exclusive). It even warns that older/archival queries should use date ranges rather than pagination, which is useful behavioral guidance.

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 front-loaded with a bold primary-purpose statement, followed by compact examples and a short general section. Every sentence contributes either selection guidance, query syntax, or behavioral details, with no filler.

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

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

The description covers when to use, query syntax, date format, ordering, and pagination. It would be slightly stronger if it described the shape of a returned tweet object, since there is no output schema, but the current information is sufficient for correct tool 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 for parameters is 100%, so the baseline is 3. The description adds real value through example query constructions like 'from:USER since:X until:Y', the default for queryType ('Default to Latest for time-sensitive queries'), and the YYYY-MM-DD format rule, going beyond the schema text.

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 by naming it the 'PRIMARY CHOICE for date-range / historical / keyword-based tweet queries' and then states 'Search Twitter/X for tweets matching a query.' It clearly distinguishes itself from get_user_last_tweets and other siblings, so an agent can identify it without reading schemas.

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

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

It gives explicit when-to-use instructions with examples ('tweets from January 2026', 'tweets last week'), and an explicit exclusion ('Use this (NOT get_user_last_tweets) whenever user asks about a SPECIFIC TIME RANGE or historical tweets'). It also lists general use cases like keyword research and brand monitoring.

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