twitterapis
Server Quality Checklist
Latest release: v0.9.1
- Disambiguation3/5
Many tools are clearly distinct, but there are multiple overlapping read variants (twitter_user_tweets vs twitter_user_tweets_and_replies, twitter_user_followers vs twitter_user_followers_v2) and a parallel monitor compat surface (twitter_x_user_stream_* vs twitter_monitor_*). Rich descriptions mitigate the confusion but do not fully remove boundary ambiguity.
Naming Consistency4/5The overwhelmingly common pattern is snake_case with a twitter_ prefix and an entity/action structure, which is readable and predictable. Minor deviations exist (twitter_check_follow_relationship, twitter_followers_you_know, twitter_x_user_stream_add_user) but they are isolated rather than systemic.
Tool Count1/594 tools is an extreme count for a single server, driven by many near-duplicate variants, v2 alternatives, compat shims, and account-management utilities. This far exceeds the range where an agent can efficiently reason about the tool surface.
Completeness4/5The tool surface covers an unusually broad Twitter/X domain: search, users, tweets, timelines, lists, communities, spaces, trends, DMs, media, articles, bookmarks, monitoring, and webhooks. Notable gaps like block/mute write actions and list update/delete exist, but most core workflows are covered without dead ends.
Average 4.4/5 across 93 of 94 tools scored. Lowest: 3.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 45 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the action is irreversible, which is a key side effect. However, it does not mention other potential consequences (e.g., immediate stop of tweets, data retention) or the exact behavior beyond stopping the watch.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using two sentences to convey the function, compatibility, irreversibility, and cost. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the core action is described, the description lacks details on how this tool fits into the larger workflow (e.g., when to use it after adding a user) and does not clarify the relationship with twitter_monitor_delete beyond a vague 'drop-in'. More context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter id_for_user is explained as 'The monitor id, from twitter_x_user_stream_list_users. Same value as a twitter_monitor_* tool's monitor id.' This clarifies its source and equivalency, making it clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the primary function: 'stop watching an account'. It also positions it as a compat drop-in for twitter_monitor_delete, which adds context, though the 'x_user_stream-shaped envelope' phrase is somewhat obscure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It mentions being a drop-in for twitter_monitor_delete but does not explicitly state when to use this tool versus that alternative. There is no guidance on prerequisites or scenarios where this specific tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, establishing a safe read operation. The description adds no additional behavioral context (e.g., no mention of rate limits, result ordering, or limitations) beyond these annotations, missing an opportunity to add value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is two sentences long, front-loaded with the action, and contains no filler. Every sentence is informative and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description compensates by listing returned fields and mentioning pagination. Parameter descriptions include examples. However, it omits comparison to sibling tools like twitter_advanced_search, leaving some contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (query, count, cursor) having a clear description. The tool description adds little beyond summarizing pagination; baseline 3 is appropriate as the schema already carries the informational burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool searches for Twitter user accounts by name, keyword, or topic, and specifies the returned fields (username, display name, bio, follower count, verification status) with pagination. It provides use cases like discovering accounts in a niche or finding brand handles, distinguishing it from sibling tools like twitter_user_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Use this to discover accounts in a niche, find brand handles, or locate a person when you only know their name.' This clearly indicates when to use the tool, though it does not explicitly mention when not to use it or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it returns profile data and supports pagination with cursor, which are useful behavioral details 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the main action, and no redundant information. Efficiently communicates purpose, return type, pagination, and use cases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (read with two optional params), the description covers the main purpose, return type, pagination method, and typical use cases. No output schema exists, but the return is explained as 'profile data,' which is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description does not need to add parameter info. The description mentions pagination and list_id location, but these are already in the schema. It adds no new semantic value beyond what is structured.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists members of a Twitter/X List by numeric list ID and returns profile data. It is specific but does not explicitly differentiate from sibling tools that also list users (e.g., twitter_user_followers), though those are for user lists rather than curated lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases: 'enumerate curated account sets, including competitor lists, industry watchlists, or media outlet lists.' This gives clear context but does not mention when not to use it or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and destructiveHint=false. Description adds value by detailing return format: 'Returns each bookmarked tweet with author and metrics plus a cursor.' No contradictions; openWorldHint=true is not contradicted. Missing details on side effects beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences, front-loaded with purpose and requirements. Every sentence serves a purpose; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with 6 parameters fully documented, the description covers purpose, authentication necessity, and return format. Lacks pagination details beyond cursor mention, but schema covers that. No output schema needed. Adequate for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed parameter descriptions. Description does not add extra meaning beyond what the schema provides, only mentions return format. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'List YOUR authenticated account's bookmarked tweets, most recent first.' Provides specific verb (list), specific resource (bookmarked tweets), and scope (authenticated account). Clearly distinguishes from sibling tools like twitter_bookmark_search and twitter_bookmark_tweet.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description mentions requirement for authenticated session but does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusions or alternative suggestions provided, though sibling tool names imply context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them. It adds the fact that no arguments are accepted and enumerates returned fields, but it does not go beyond annotations with behavioral context like pagination, rate limits, or the semantics of 'degraded flag' or 'events_possibly_missed.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with the primary purpose front-loaded. The field enumeration is dense but directly useful for an agent selecting or invoking the tool, and there is no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with no parameters, the description covers the action, output fields, and argument expectation well. However, terms like 'degraded flag,' 'events_possibly_missed,' and 'webhook_ids restriction' are left unexplained, and with no output schema, the description carries the full burden of clarifying return value semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema shows empty properties. The description explicitly states 'Takes no arguments,' which removes ambiguity and meets the 0-parameter baseline; no further parameter explanation is possible.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List every monitor on your account,' giving a specific verb and resource, then details the exact fields returned. This clearly distinguishes it from sibling monitor tools like twitter_monitor_health and twitter_monitor_deliveries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose is implied by the resource name and the direct 'List every monitor on your account' phrasing, but there is no explicit guidance about when to use this tool versus alternatives such as twitter_monitor_health, twitter_monitor_deliveries, or twitter_monitor_account_health. No exclusions or alternative tool names are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so destructive nature is known. The description adds 'Requires write capability behind your key', which hints at authentication, but does not detail consequences (e.g., irreversible, rate limits) or mention that it acts on the authenticated account specifically beyond the title. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the action. It includes a necessary caveat about write capability and proxy for writes, but could be trimmed. However, every sentence adds value, so conciseness is good.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters and no output schema, the description covers the essence but lacks details on return values or edge cases. Annotations handle safety. For a simple undo action, this is adequate but not exceptional. The description could mention what happens if the tweet is already unretweeted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds the crucial requirement of providing exactly one of id or url, which is not fully explicit in schema descriptions but helps disambiguate parameter usage. It also emphasizes the write capability and proxy recommendation, adding context beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Undo a retweet') and the resource (AS your authenticated account). It distinguishes from sibling tools like twitter_retweet by explicitly stating the undo action and scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use it (to undo a retweet) and specifies input requirements (tweet id or url). However, it does not explicitly contrast with alternative tools or state when not to use it, but the unique action makes alternatives obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is disclosed. The description adds that it resolves the numeric user_id, but no further behavioral details are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main function, and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (one parameter, no output schema) and presence of annotations, the description covers purpose, usage, output fields, and parameter format. Missing authentication mention but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with the same detail as the tool description (handle without leading @, examples). The tool description does not add new parameter information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a user's complete public profile' and lists specific fields. It differentiates from siblings like twitter_user_info_by_id by specifying 'by their @handle'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this before fetching tweets or followers to confirm the account exists and resolve the numeric user_id,' providing clear when-to-use guidance. It lacks explicit exclusions but is still helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description's addition of 'Requires an authenticated session with write capability' and 'Returns the updated article object' adds valuable behavioral context beyond annotations. It also mentions the DRAFT/PUBLISHED state, which is useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences and under 50 words, front-loading the core action. There is minor redundancy (mentioning 'authenticated account' and later 'authenticated session'), but each sentence serves a purpose: action, required inputs, auth requirement, and return value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with 6 params, 2 required, and no output schema, the description adequately covers the operation, auth prerequisite, input source, and return behavior. It does not discuss error conditions or rate limits, but these are not expected for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description restates the need for id and title but adds no new meaning beyond the schema's field descriptions; it does not compensate for optional parameters like proxy_url or auth_token, which are already well-documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Set or replace the title of a DRAFT or PUBLISHED article AS your authenticated account,' which uses a specific verb (set/replace) and resource (title of article). It clearly distinguishes from sibling tools like twitter_article_update_content and twitter_article_update_cover_media by focusing solely on the title.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: the article id comes from twitter_article_create or twitter_article_list, and the tool targets title-only updates. It does not explicitly state 'use update_content for body changes,' but the title-specific wording and sibling differentiation make the intended usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds that it requires write capability, which is consistent with the readOnlyHint=false annotation. It does not disclose further side effects (e.g., visibility, rate limits) but annotations already cover the read-only nature, 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that conveys all essential information (action, subject, requirement, and alternative) without ambiguity or unnecessary words. It is well-structured and easily parsed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple write operation, the description covers the core functionality (retweet), identifies the target via id or url, states the authentication requirement, and points to the reverse operation. Since there is no output schema, return values need not be described. It is complete for its scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions fully cover all 6 parameters (id, url, etc.), and the description redundantly notes 'Provide the tweet id or url,' which is already stated in the schema. Since coverage is 100% and no additional semantic detail is given, the description adds minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Retweet a tweet AS your authenticated account.' It specifies the resource (a tweet) and the context (authenticated account), making the purpose unambiguous and distinct from other tweet actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a precondition: 'Requires write capability behind your key,' and mentions the reverse operation ('Reverse with twitter_unretweet'). However, it does not explicitly compare to other tweet creation tools (e.g., twitter_create_tweet) or indicate when retweeting is preferred, but the purpose alone makes usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that it filters to verified accounts and paginates, which is transparent. No contradictions or additional behavioral details (e.g., rate limits) are needed given 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Front-loaded with the core action and purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains what the tool does and pagination, but lacks details on the return format (e.g., list of user objects). Given no output schema, some return structure info would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; the description adds minimal value ('paginate with cursor' is already in schema). Baseline 3 is appropriate as the schema fully handles parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists a user's verified followers, filtering the follower list to verified accounts only. It explicitly distinguishes from sibling tools like twitter_user_followers by specifying the verification filter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions usefulness for identifying notable or institutional followers and pagination with cursor, implying appropriate contexts. However, it does not explicitly exclude cases or mention alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Transparently notes that the tool does not construct or validate content_state, passes it through verbatim, and clarifies authentication and write requirements. Consistent with destructiveHint=false and adds useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using two clear sentences without redundancy, and is well-structured with necessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key aspects: target article states (DRAFT or PUBLISHED), authentication/write requirements, pass-through behavior, and return type. Sufficient for the tool's complexity; lacks only explicit mention of alternatives, but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description enriches schema by specifying content_state as Draft.js JSON with expected structure and explicitly states that the user builds it and it is passed through verbatim, adding meaning beyond the basic schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action: 'Replace the body content of a DRAFT or PUBLISHED article'. It identifies the resource (article) and the specific operation (content update), distinguishing it from other article operations like title or cover media updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for changing article body content and mentions requirements (authenticated account, write capability), but does not explicitly contrast with alternative tools like update_title or update_cover_media, nor state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive, and the description adds useful context: requires an authenticated session, and pagination is cursor-based with no count/page-size. This is beyond the annotation metadata and helps the agent understand expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both dense with actionable info: purpose/scoping, source of folder_id, auth requirement, and pagination. No fluff, each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only paginated tool with good annotations and full schema coverage, the description adequately covers purpose, auth, and pagination. It doesn't describe the return shape, but without an output schema, that's acceptable. It might mention rate limits, but overall it's complete for this tool type.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all six parameters are described there. The description adds minimal extra meaning, only reminding that folder_id comes from twitter_bookmark_folders. Since the schema handles parameter details, the description's contribution is marginal but not absent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads tweets from one bookmark folder, specified by folder_id sourced from twitter_bookmark_folders. This specific verb+resource+scope distinguishes it from siblings like twitter_bookmark_folders (listing folders) and twitter_bookmarks (all bookmarks).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a prerequisite (folder_id from twitter_bookmark_folders) and notes the requirement for an authenticated session. It also explains pagination behavior (cursor-based, no count parameter). While it doesn't explicitly name alternative tools, the 'ONE' qualifier and source hint adequately guide usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds that it requires an authenticated session, returns tweets plus cursor, which goes beyond annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no wasted words. Efficiently communicates key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Describes input (query) and output (tweets and cursor), but lacks detail on response structure. However, given no output schema and straightforward use case, it's mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The tool description adds minimal parameter info (only mentions cursor output), so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states it performs 'full-text search within YOUR authenticated account's bookmarks', clearly identifying the tool's action and resource. It distinguishes from siblings like twitter_bookmarks by specifying search vs. list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use for retrieving a bookmarked tweet by keyword and mentions authentication requirement. No when-not or alternatives provided, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag readOnlyHint=false, so the description adds value by specifying the side-effect scope: the bookmark lands only in the authenticated account's *private* bookmarks, and the operation is reversible via twitter_unbookmark_tweet. It also discloses the auth requirement ('write capability behind your key'). It stops short of 5 because, with no output schema, it doesn't disclose return/error behavior or duplicate-bookmark semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the core action, then input form, precondition, and reversal — every sentence earns its place with zero filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers action, account scope, privacy, input form (id or url), auth precondition, and reversal, while the schema's property descriptions add proxy/auth pairing nuances. The only gap is that no output schema exists and the description doesn't hint at return values or already-bookmarked behavior; for such a simple write operation this is a minor omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 — the property descriptions already document the id/url mutual exclusion ('Provide exactly one of id or url'), ct0/auth_token pairing, proxy_url recommendation for writes, and header mappings. The top-level description merely restates 'Provide the tweet id or url' and adds no syntax or format detail beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+scope: 'Bookmark a tweet to YOUR authenticated account's private bookmarks.' It distinguishes from siblings by scoping the action to the caller's own account and explicitly naming the reverse tool (twitter_unbookmark_tweet), while the read-only bookmark siblings (twitter_bookmarks, twitter_bookmark_search) are clearly different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when this tool applies: it requires 'write capability behind your key' and names twitter_unbookmark_tweet as the explicit reverse/undo path. However, it doesn't explicitly state when NOT to use this versus the read-only bookmark tools (twitter_bookmarks, twitter_bookmark_search), so it falls just short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds beyond annotations by stating the tweet is public and 'not silently reversible', and points to an alternative for deletion. This gives the agent important side-effect information not captured in boolean hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences cover purpose, usage, prerequisites, side effects, and return value without redundancy. Highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers prerequisites, public nature, non-reversibility, and return value, which is sufficient given no output schema. Does not mention error handling or edge cases, but those are often not expected in tool descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all parameters in full detail. The description adds a small clarification on reply_to and quote usage, but does not significantly enhance parameter understanding beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action: 'Post a new tweet' with the resource being the user's account. It distinguishes from siblings by mentioning reply/quote functionality and points to twitter_delete_tweet for reversal, differentiating it from other tweet actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage scenarios (post, reply, quote) and prerequisites (authenticated session with write capability). Does not explicitly state when not to use, but the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds value by specifying the authentication requirement and the return shape ('profile data per overlap account plus a cursor'). This context helps the agent understand the operational constraints beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, each serving a distinct purpose: the first explains the core operation, the second adds requirements and output. It is front-loaded with the most critical information and contains no redundant or unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential aspects: what the tool does, required authentication, and output (profile data + cursor). While there is no output schema, the description gives a sufficient overview. It could be more complete by clarifying the response structure or edge cases, but for a read-only tool with extensive parameter documentation, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameter descriptions are already detailed (e.g., ct0, count, cursor). The tool description adds only the high-level requirement of an authenticated session, which is implicitly covered by the auth parameters. Given the high schema coverage, a score of 3 is appropriate as the description does not significantly augment the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool's purpose: listing 'Followers you know' for a target user, which is the overlapping followers between the target and the authenticated account. It uses specific verbs ('List') and resource ('target user id'), and the phrase 'mutual-connection overlap' distinguishes it from sibling tools like 'twitter_user_followers' (all followers) or 'twitter_check_follow_relationship' (single check).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'Requires an authenticated session behind your key,' which is a prerequisite for use. The concept of mutual-connection overlap implicitly indicates when to use this tool (to find known followers) versus other follower tools. However, it does not explicitly mention when not to use it or provide direct comparisons to sibling tools, which would elevate it to a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already marking the tool as non-read-only and non-destructive, the description adds valuable context: it acts as the registered account session, supports only base64 image data over JSON transport, and returns ok and the media_id. This goes beyond the structured annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences with no filler. It front-loads the core action and return value, then provides essential auth and format constraints. Every sentence contributes distinct, useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and rich descriptions in the schema, the description covers the essential operational context: purpose, prerequisites, supported input format, and return shape. It could mention success/failure details or size limits, but it is sufficiently complete for an agent to invoke it correctly when paired with the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reinforces the meaning of media_data and the auth_token/ct0 pairing, but does not add substantial new parameter semantics beyond what the schema already documents. The return-value mention is useful but not parameter-specific.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Upload an image to X and get a media_id to attach to a tweet via twitter_create_tweet's media_ids.' This clearly states the tool's function and distinguishes it from read-only Twitter tools and the media_status sibling by emphasizing the upload-and-return-media_id flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: it is for uploading images meant to be attached to tweets, it names the dependent tool (twitter_create_tweet), and it explains the required session setup ('register first with twitter_customer_session or twitter_user_login, or pass auth_token/ct0 for this call'). It does not explicitly list exclusions or alternative upload tools, but such alternatives are not evident among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations state readOnlyHint=false (so a write) and destructiveHint=false (not destructive). The description adds meaningful context: it mentions HMAC signing, shared poll interval, that it returns various fields, and that creation is 'account administration, not a metered read', which is beyond what annotations provide. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense paragraph. Each sentence adds new details (purpose, delivery mechanism, free status, return value) with no redundancy, and it fits on three sentences total.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (3 parameters, only 1 required) and presence of annotations, the description covers the action, delivery details, prerequisites, and return information. It does not elaborate on edge cases like invalid handle or webhook deletion, but those are not essential given the schema and sibling tool references. It lacks a reference to the poll interval value or further detail, but this is not critical for a first creation call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description itself only mentions 'handle' indirectly via return value ('normalized handle') and the webhook_ids are partially implied ('delivered to your registered webhook(s)'). It does not add additional meaning for parameters beyond what the schema already explains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Start watching an X account for new posts' – a specific action on a specific resource, and it distinguishes itself by outlining the monitoring/delivery behavior (HMAC signing, webhook delivery, shared poll interval) and references the return value (monitor id, status, poll_interval_ms).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly guides usage by noting 'see twitter_monitor_webhook_create to register a delivery URL first', which is a clear prerequisite. It also mentions that creation is free, distinguishing this from possibly metered reads, but doesn't explicitly contrast with other monitor tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'Read' is consistent. It adds valuable context beyond annotations by noting the call is 'Free per call' and by listing the specific status fields returned, which helps the agent anticipate the response shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that immediately states the action and resource, then enumerates the returned fields and the dashboard use case. No filler or redundant content; each word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool with no output schema, the description covers the return fields, purpose, and cost. It could mention error conditions or how the 'possibly-missed-event count' is computed, but the level of detail is adequate for an agent to select and call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single 'id' parameter, including its provenance from twitter_monitor_create or twitter_monitor_list. The tool description itself adds no extra parameter detail, so the schema carries the semantic burden; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and identifies the exact resource ('one monitor's current status') plus enumerates the fields returned (degradation flag, poll interval, possibly-missed-event count, cursor position). It clearly differentiates from sibling tools like twitter_monitor_list (all monitors) and twitter_monitor_account_health (account-level health).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for building your own health dashboard' provides a clear use case, and 'one monitor' signals this is for single-monitor checks rather than bulk listing. However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a safe read operation. The description adds useful behavioral details: default Worldwide behavior, precedence rules, returned timestamps and resolved location, and count truncation. The final sentence about 'A location X will not serve returns a 400' is garbled and slightly undermines the transparency, but the overall behavioral picture is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately short and front-loaded with the core purpose. However, the final sentence is malformed ('A location X will not serve returns a 400') and does not communicate clearly, so not every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with no output schema, the description does a good job covering what the caller gets back: resolved location, as_of/created_at timestamps, and ranked trends. It also covers defaults and parameter precedence, making it largely self-sufficient, though the error-case sentence needs repair for full clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema carries the parameter definitions. The description adds value by clarifying inter-parameter behavior: woeid precedence over country, country resolution against the locations list, omission meaning Worldwide, and count truncation semantics. This goes beyond a simple restatement of the schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get the current top trends for a location.' This clearly distinguishes the tool from siblings like twitter_trends_locations, which is about available locations rather than the trends themselves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: no location returns Worldwide, country or woeid can be used, and woeid wins if both are given. It implies the companion tool twitter_trends_locations as the source for woeids, though it does not explicitly say 'use twitter_trends_locations to find WOEIDs'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds useful behavioral context: it returns reply tweet fields and supports pagination with a cursor. This goes beyond annotation defaults without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four short, front-loaded sentences. Each sentence contributes either purpose, output details, pagination guidance, or usage context with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only paginated list endpoint, the description covers inputs, output, pagination, and intended use. There is no output schema, so the description appropriately summarizes return contents instead of leaving them unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with id/url described as mutually exclusive alternatives and cursor explained as an opaque pagination token. The description reinforces cursor usage but does not need to add much beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource, "Get replies to a specific tweet," and clarifies the output shape: each reply with author, text, and metrics. It naturally distinguishes itself from sibling tools like quotes, retweets, and thread views by focusing on replies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states intended use cases: "read the conversation under a tweet, gauge sentiment, or find notable responses." It does not mention alternative tools or when not to use it, but the guidance is clear enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds behavioral details: returns profile data and paginates with cursor. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each providing essential information: the action and result, pagination behavior, and a use case. No wasted words, perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, pagination, and typical use. Without an output schema, it could be more specific about what 'profile data' includes. However, it is mostly complete for a paginated list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema; it mentions pagination with cursor, which is already in the schema's cursor field description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists accounts that retweeted a specific tweet, returns profile data for each retweeter, and supports pagination. It distinguishes from siblings like twitter_retweet (which performs an action) and twitter_tweet_detail (which gets tweet content).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a use case: 'finding who amplified a piece of content or mapping a tweet's distribution network.' It does not explicitly state when not to use or give alternatives, but the context is clear enough given the sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With destructiveHint=true and readOnlyHint=false in annotations, the description correctly reinforces the mutating nature by using 'Remove' and adds the need for 'write capability behind your key.' It explains the authentication context without contradicting annotations, though it could also mention the requirement to be authenticated as the account owner.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences long, front-loads the core action, and wastes no words. Every clause earns its place, making it highly scannable for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with 6 parameters and no output schema, the description covers the essential behavioral context: what is removed, whose bookmarks are affected, what inputs are needed, and what permission is required. It is slightly light on post-conditions (e.g., what a successful removal returns), but this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with detailed descriptions for every parameter, including the mutual exclusivity of id/url and header mappings. The description adds minimal new parameter information beyond restating 'Provide the tweet id or url,' so a baseline score is appropriate given the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Remove') and resource ('a tweet from YOUR authenticated account's bookmarks'), making the tool's purpose unmistakable. It clearly distinguishes this from sibling tools like twitter_bookmark_tweet or twitter_bookmarks by focusing on removal from the user's own account.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells the agent to 'Provide the tweet id or url' and notes that write capability is required. While it doesn't explicitly describe when NOT to use this tool or name alternatives, the prerequisite and primary input are clear, providing solid practical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive and non-read-only. The description adds valuable context beyond those annotations by specifying that the action applies to the authenticated account and requires write capability, which is important behavioral information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the verb and target, then adds the key auth requirement. There is no fluff, repetition, or wasted wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple write operation, the description plus annotations and full schema coverage provide enough context for selection and invocation. It lacks explicit return or error behavior, but no output schema exists and the operation is straightforward, so this is not a major gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are already documented with their own descriptions. The tool description only restates that user_id is numeric, adding no meaningful semantic value beyond the structured schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Unfollow a user') and resource ('by numeric user_id'), and clarifies it operates on the authenticated account. This clearly distinguishes it from related siblings such as twitter_follow_user or read-only user info tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this unfollow acts AS the authenticated account and requires write capability behind the key. It does not explicitly name alternatives or when-not scenarios, but the auth and capability framing gives enough guidance for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safe read. The description adds value by stating it returns profile data per affiliate plus a pagination cursor, and returns empty for accounts with no affiliations. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose and details. No extraneous information; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the concept of affiliates, what is returned (profile data, pagination cursor), and the empty case. It lacks explicit error handling or rate limit info, but with openWorldHint and good schema, it's sufficient for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 5 parameters. The description does not add significant meaning beyond what the schema already provides (e.g., mentioning to provide exactly one of username or user_id is already in schema). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists affiliated accounts of an organization profile (the 'Affiliated' badge), specifying the resource (affiliates) and action (list). It distinguishes from sibling tools like twitter_user_followers or twitter_user_info by focusing on a specific Twitter feature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: for listing affiliated accounts of an org profile, providing a username or user_id. It does not explicitly exclude alternatives or mention when not to use, but the context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only. The description adds specificity about returned data (username, display name, bio, follower count) and pagination behavior, supplementing the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences) and front-loaded with the action. Every sentence adds value: what it does, what it returns, pagination guidance, and use case.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately covers return data and pagination. It omits error scenarios or user not found, but for a straightforward read tool with full parameter schema, this is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all four parameters. The tool description adds no extra parameter semantics beyond mentioning pagination with cursor, which the schema already covers. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List the accounts that follow a given user' with specific verb and resource. It distinguishes from siblings like 'twitter_followers_you_know' and 'twitter_user_verified_followers' by focusing on all followers, 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for use ('audience analysis, finding who follows a brand or influencer') and mentions pagination, but does not explicitly contrast with similar tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is established. The description adds value by noting behavioral differences from v1: 'richer profile fields' and 'more reliable cursoring for large audiences', which directly informs expected behavior beyond the 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and every clause earns its place. It efficiently conveys purpose, key differentiators, and usage guidance without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 4 parameters, full schema coverage, and no output schema, the description effectively explains why this variant exists and when to choose it. It could possibly elaborate on the return structure, but the 'fuller v2 payload' hint and cursoring mention provide adequate context for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific details (all four params are already well-documented in the schema), and 'Same inputs as twitter_user_followers' is redundant given the schema. No additional semantic value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb+resource ('List a user's followers') and immediately distinguishes itself with 'v2 response shape', 'richer profile fields', and 'more reliable cursoring', differentiating from the sibling twitter_user_followers. It names the alternative explicitly and states the key benefit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear guidance to 'prefer this when you need the fuller v2 payload or are paging deep follower lists', which directly addresses when to use this tool. However, it does not explicitly state when NOT to use it (e.g., when a lightweight v1 response suffices), though the alternative is implied by referencing twitter_user_followers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 clear. The description adds valuable behavioral context: it mentions pagination ('Paginate with cursor') and that it returns profile data for each account. This goes beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences—with no wasted words. It front-loads the core action and output, then adds the pagination note and use cases efficiently. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers the return value type ('profile data') and pagination behavior. It also mentions use cases. For a listing tool with good annotations (readOnlyHint, openWorldHint), this is sufficiently complete to guide an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema itself documents all parameters adequately. The description adds minimal extra meaning beyond the schema, only reiterating pagination behavior. Baseline 3 is appropriate as the description does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List the accounts that a given user follows') and specifies the output ('Returns profile data for each account followed'). It differentiates from sibling tools like 'twitter_user_followers' by focusing on the accounts being followed, not the followers. The use cases mentioned further clarify its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage contexts ('mapping a user's information sources, influencer networks, or competitor monitoring lists'), indicating when to use this tool. However, it does not explicitly state when NOT to use it or mention alternative tools, though the sibling list implies differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and destructiveHint. The description adds behavioral details: returns media-containing tweets with URLs, dimensions, and type, and requires pagination with cursor. This adds meaningful context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: purpose, return details, usage instruction. No wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description explains the return values (URLs, dimensions, type) and pagination. It covers the essential aspects for using the tool, though it omits error conditions or rate limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no additional meaning beyond what the schema provides for count, cursor, user_id, and username.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets images and videos a user has posted, specifying return details like URLs, dimensions, and types. This distinguishes it from sibling tools like twitter_user_tweets which return all tweets without media focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Use this to pull a user's visual content history,' providing clear context for when to use. However, it does not explicitly contrast with alternatives like twitter_advanced_search or specify when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only generic annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description adds meaningful context: it creates a draft, requires an authenticated session with write capability, and returns an id plus full object. No annotation contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences front-load the core action, then provide the returned id use and auth prerequisite. There is no filler or repetition; every sentence contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description correctly discloses return values (id + full article object), downstream tool names, and the write-session requirement. This is sufficient for an agent to select and safely invoke a simple no-input create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are already fully documented in the schema, so the high coverage baseline applies. The description adds a useful high-level note that no input is required and that auth/session context is needed, but it does not materially enrich parameter-level semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action ('Start a new DRAFT article') and identifies the actor ('AS your authenticated account') and artifact type ('Note'). It clearly distinguishes this creation tool from article mutation/publishing tools like twitter_article_update_title, twitter_article_publish, and twitter_article_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description frames this as the entry point to the article lifecycle by stating no input is required and explaining that the returned id feeds update/publish/delete tools. It does not explicitly contrast with twitter_create_tweet or name when to avoid this tool, so it falls just short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description reinforces with 'Read-only: this does not send DMs' and adds authentication requirement, which is useful beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, concise and front-loaded. Every sentence adds value: first states purpose and output, second clarifies read-only nature and prerequisite.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with annotations, description is complete: states what it returns (participant and conversation_id), usage context, and connection to sibling tool. No output schema needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds no extra meaning beyond what schema provides for the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states it lists your authenticated account's DM conversations (inbox), providing participant and conversation_id. It distinguishes from sibling twitter_dm_conversation by mentioning the conversation_id can be passed to that tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes prerequisite: requires an authenticated session behind your key. Does not explicitly state when not to use, but the context is clear for listing DMs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations by mentioning it's a read operation with 'no daily write cap applies' and pointing out that it 'Reads through YOUR OWN registered session', implying authentication side effects. However, it does not detail potential latency or error conditions beyond the error object in the return.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately lengthy but each sentence contributes unique information: purpose, usage, return fields, auth, and read-only status. It is structured logically, though the final sentence about read-only nature is a bit redundant with the annotations. Overall, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description provides essential return fields (media_id, state, check_after_secs, progress_percent, error object). It covers purpose, usage timing, authentication, and read-only nature. It could be more detailed about error handling or potential failures, but it is sufficiently complete for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for all parameters (media_id, ct0, proxy_url, auth_token, user_agent). The description only reiterates the auth_token/ct0 requirement and mentions media_id, without adding further detail about proxy_url or user_agent. It does mention the output parameter check_after_secs, but that is not an input parameter, so the added value is limited.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Check whether an uploaded media_id has finished processing' and distinguishes it from the upload tool by explaining the asynchronous nature. It uses specific verbs and provides a precise scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use it: 'before you attach it to a tweet' and explains the polling behavior: 'Poll this until then'. It also gives a clear directive to honor check_after_secs to avoid tight-looping, which serves as practical usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint: true, but the description adds valuable nuance: it is a soft delete, not a cascade delete, and delivery history is retained. It also discloses irreversibility from the caller's side and the fact that it is free per call. This goes beyond the raw annotation and gives the agent a precise behavioral model, though it does not detail any side effects on the delivery history beyond retention.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: two sentences that front-load the primary action and effect, then immediately address retention, irreversibility, and recovery. Every clause earns its place, and there is zero filler or repetition. This is an ideal example of efficient, high-signal writing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, clear destructive intent) and the strong annotations, the description covers all essential aspects: the action, immediate consequence, historical data handling, irreversibility, and the path to restore functionality. The combination of annotations and description fully equips the agent to make an informed call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the single 'id' parameter with 100% coverage, including its source. The description adds no additional semantic detail beyond the phrase 'by id', which is redundant. Baseline of 3 is appropriate because the description does not need to compensate for schema gaps, but it also does not enrich the parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool soft-deletes a webhook by id, explains the immediate effect (stops deliveries, disappears from list), and explicitly references sibling tools (twitter_monitor_webhook_list and twitter_monitor_webhook_create) to differentiate its role. The verb 'delete' combined with the resource and the nuanced 'soft' qualifier leaves no ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong contextual guidance: it notes the action is irreversible and recommends creating a new webhook via twitter_monitor_webhook_create to resume delivery. This effectively tells the caller when this tool is appropriate (when stopping a webhook) and what to do as an alternative. However, it does not explicitly state when not to use it or contrast it with other deletion-like tools (e.g., hard delete if it existed), so it stops short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description discloses critical behavioral details: the listener roster becomes empty for ended Spaces due to X's retention policy, and timestamps are given in millisecond-epoch format. It also clarifies that only metadata is returned, not audio. These are valuable additions that prevent misinterpretation and enrich agent understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense paragraph that front-loads the purpose and then lists returned fields, followed by important caveats and timestamp format. Every sentence contributes substantive information, but it is slightly long with many clauses. It is structured logically and avoids redundancy, so it earns a 4 rather than a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters and no output schema, the description provides a comprehensive list of returned fields and explains important behavioral nuances (e.g., empty listener roster for ended Spaces). It does not mention pagination, limits, or exact response structure, but given the tool's simplicity, these are not necessary. It successfully covers the key aspects an agent needs to know.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all three parameters with descriptions (id, with_replays, with_listeners). The tool description does not add extra parameter-specific explanations; it only indirectly mentions listener behavior in the context of ended Spaces, which relates to with_listeners. Since schema coverage is 100%, a baseline of 3 is appropriate, and the description doesn't elevate it further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get metadata and the participant roster for one X Space by id, live or ended' and enumerates the exact fields returned (title, lifecycle state, host, topics, times, counts, rosters). It also explicitly distinguishes itself by noting it returns metadata only, not audio, which differentiates it from any audio-related tools. This is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context about when the tool is appropriate (fetching Space metadata and rosters) and explicitly notes what it does NOT do (returns no audio). However, it does not mention any alternative tools for audio or other use cases, nor does it state explicit exclusions like 'use only for live Spaces'. Still, the context is sufficient for an agent to infer its use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint true, and the description reinforces this with 'account read'. It adds operational context by specifying free usage and no credit consumption, which goes beyond the annotations. No contradiction found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences. The first states the primary action and result, the second adds critical context (authentication, cost, and scope). No wasted words; front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description adequately covers what it returns (payment history), who it's for (your account), and key attributes (free, no credits). It might benefit from mentioning result format or pagination, but these are not essential given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100% trivially. The description appropriately does not add unnecessary parameter details, though it could mention that the result is scoped to the authenticated user's account, which is implied.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it retrieves the user's twitterapis.com payment history, listing top-ups and charges. It clearly distinguishes this from sibling tools that focus on Twitter data by emphasizing 'your account' and 'not Twitter data'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions authentication via API key and explicitly states it is free and does not spend credits, which guides when to use it. It clarifies it's an account read, not Twitter data, helping differentiate from other tools, though it does not explicitly name alternatives (there are none for payments).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnly, description adds details on what flags are returned (block/mute). No contradiction and provides extra context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences front-load purpose and usage, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with no output schema, description covers input, return value hints, and usage context. Minor gap: no mention of error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both params with descriptions; description rephrases roles ('subject' vs 'object') adding clarity. With 100% schema coverage, additional explanation earns above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks follow relationship between two accounts by numeric user id, including blocking/muting flags. It distinguishes from sibling tools like follow/unfollow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says both ids required and gives use cases: verify follow before/after or detect mutuals. Lacks explicit when-not but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations: it states cookies are stored server-side, never returned, and that the tool returns ok, resolved username, and validation status. This addresses security (sensitive data handling) and validation behavior, which is highly valuable given the write-capable scope. Annotations only state non-readOnly and non-destructive, so the description adds critical context without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph but information-dense, listing tool names and options clearly. It front-loads the primary purpose and security note, though the long list of tool names could be abbreviated for brevity. It is slightly long but each part contributes to usage clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (authentication setup, side effects), the schema covers all parameters, and the description explains the registration flow, storage, return values, and alternatives. Without an output schema, it still conveys what the agent can expect (ok, username, validation). It is complete for an authentication setup tool with this level of detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage, with each parameter described (auth_token, ct0, proxy_url, user_agent). The description adds context by mentioning that cookies are paired and that proxy_url is for residential proxies, but these details are largely redundant with the schema. Since the schema fully explains the parameters, the description adds minimal extra meaning, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool registers the user's own X account session via cookies against an API key, distinguishing it from alternatives like twitter_user_login. It explicitly lists the affected authenticated and write tools, making the purpose and resource clear. It loses one point because the main verb 'register' is implied rather than explicitly stated, and the title already conveys similar meaning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool ('Register YOUR OWN X account session') and contrasts with twitter_user_login for username/password, and notes per-call cookie alternatives for most tools. This provides clear guidance on alternatives and exclusions, which is exemplary. It also outlines optional parameters like proxy_url and user_agent for advanced use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by explicitly stating the tweet is 'permanently removed' (irreversible), reinforcing destructiveHint. It also discloses that only self-authored tweets can be deleted and that write capability is required, which are not present in the annotations. This adds critical context for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each adding value: the action, the irreversible consequence, and the author restriction. No fluff or redundant information. It is front-loaded with the primary purpose and gets straight to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a simple deletion tool and rich schema annotations, the description covers essential behavioral aspects: irreversibility, author scope, and authentication requirement. It does not explain error cases or post-delete behavior, but given the lack of output schema and the simplicity, it is sufficiently complete. Missing details like proxy usage are already in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already well-documented in the schema. The description only reiterates that id or url must be provided ('Provide the tweet id or url'), which matches the schema's mutual-exclusivity note. It adds no new parameter-level semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Delete a tweet AS your authenticated account.' It specifies the verb (delete) and resource (tweet), and distinguishes from siblings like twitter_unfavorite_tweet or twitter_unretweet by focusing on permanent deletion. The irreversibility and author restriction add precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: you can only delete tweets your own account authored, and it requires write capability. It instructs to provide the tweet id or URL. However, it does not explicitly compare to alternative tools (e.g., unfavorite or unbookmark), though the destructive nature makes it distinct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that authentication is required and reinforces the read-only nature, which is consistent and adds context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no redundancy. The main action is stated first, followed by requirements and read-only declaration. All sentences contribute essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description specifies what is returned ('each message with sender id, time, and text'). It covers the key parameter and requirement. It could mention error handling, but is complete enough for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description adds value by explaining that conversation_id comes from a sibling tool, which aids in selection. Baseline is 3 due to high coverage, but the cross-reference earns a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get the messages') and the resource ('Direct Message conversation'), and references the source of the identifier ('from twitter_dm_list'). This distinguishes it from other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It specifies a requirement ('Requires an authenticated session') and declares the tool is read-only ('does not send DMs'). However, it does not explicitly state when to use or not use this tool vs. alternatives, though the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the action requires write capability and is performed on behalf of the authenticated account, going beyond the annotation (readOnlyHint: false). It does not mention potential failure cases or side effects, but for a simple like operation this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct, consisting of three short sentences that convey the action, input requirement, permission note, and reverse operation. No redundant information or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the action and complete schema descriptions, the description adequately covers the core behavior, permission needs, and relationship to the opposite action. It stops short of mentioning error conditions or response format, but that is not critical for a like operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides detailed descriptions for all six parameters (100% coverage). The description adds a brief note to 'Provide the tweet id or url,' but this is already embedded in the schema. No significant additional parameter context is given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action: 'Like (favorite) a tweet AS your authenticated account.' It distinctly identifies the resource (tweet) and the operation (like), and differentiates from the sibling tool by mentioning the reverse operation (twitter_unfavorite_tweet).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to 'Provide the tweet id or url,' and notes the requirement for write capability. It also directs when to use the reverse tool, providing clear context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the write nature is known. The description adds important behavioral context beyond those booleans: the action is performed AS the authenticated account and specifically requires write capability. It does not contradict annotations, and mentions the reversible counterpart. Some side-effect detail (e.g., rate limits or failure semantics) is absent, but annotations lower the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences deliver the core purpose, authentication requirement, and reverse-tool pointer without wasted words. The most critical information is front-loaded in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with no output schema, the description covers what it does, how to authenticate, the required format of user_id, and the reverse operation. The schema fully documents all parameters, and annotations cover the safety profile. Minor gaps like expected response or failure behavior are not severe given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The main description adds meaningful guidance for the key user_id parameter ('Resolve a handle to a user_id first with twitter_user_info') and reinforces the auth-token pairing context visible in the schema. This extra semantic hint justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Follow') plus a clear resource ('a user AS your authenticated account, by numeric user_id'), making the action unambiguous. It also distinguishes itself from the sibling tool twitter_unfollow_user by explicitly naming the reverse operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states a key prerequisite ('Requires write capability behind your key') and points to the alternative for reversing the action ('Reverse with twitter_unfollow_user'). It does not exhaustively enumerate when to use this vs. relationship-checking tools, but the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations. It explains what the tool returns (eligibility, X's verbatim reasons when not eligible, free access status, model options) and explicitly states that eligibility is a property of the X account, not the API key. It also includes the 'Free' note, which is non-obvious. Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to repeat safety traits; it adds valuable return and account-dependency information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It opens with the primary purpose, then lists what it returns, adds a key caveat about account vs. API key, and ends with 'Free.' Every sentence earns its place, with no superfluous content. It is front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only configuration check with no output schema, the description is sufficiently complete. It covers the purpose, return contents, the account dependency, and cost. It does not mention error handling or authentication details, but the mention of 'authenticated account' and 'Free' implies the necessary context. Given the tool's simplicity and the rich schema annotations, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, as each of the four parameters has a detailed description. The tool description itself does not elaborate on parameter usage, but it does hint at the account-based nature (auth_token and ct0) indirectly. With full schema coverage, the description adds minimal extra over the schema, 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks whether the authenticated account can use Grok and which models are available. It specifies the resource (Grok) and the action (check eligibility and models), and it distinguishes itself from the sibling twitter_grok_chat by focusing on configuration and eligibility rather than chat. The description also clarifies the account-based nature of eligibility, which is a specific and unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly directs usage: 'ask this about the same account you intend to run twitter_grok_chat as.' This provides clear guidance on when to use the tool (before using Grok chat) and ties it to the specific account. It also notes that the tool is 'Free,' which is a practical usage consideration. While it does not list exclusions, the instruction is specific and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds value by detailing the return format ('tweets with author and metrics plus a cursor') and authentication requirements ('Requires an authenticated session behind your key'). It does not contradict annotations and provides useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise—four sentences front-loaded with the primary purpose. Every sentence provides essential information without redundancy. It efficiently covers purpose, usage, return data, and high-level guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters (none required) and no output schema, the description adequately covers pagination, authentication, and general return data. It could mention rate limits or typical response size, but the current completeness is sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description enriches parameters with practical details, such as the typical range for 'count', pagination instructions for 'cursor', and usage notes for 'proxy_url' (recommended for writes). This adds significant value beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the authenticated user's home timeline, specifying 'Get YOUR authenticated account's Home timeline (the 'Following'/'For you' feed), most recent first.' This verb+resource combination is specific and distinguishes it from sibling tools like twitter_advanced_search or twitter_user_tweets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool ('to read what your account would see when it opens X') and notes the requirement for an authenticated session. It implies a read-only context but does not explicitly exclude alternative tools for similar purposes, such as twitter_advanced_search. The guidance is clear but lacks explicit when-not-to-use statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: it notes cursor-paginated nature and clarifies that a small follower count is normal and not a truncated page. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, tightly written. It opens with the core action, then adds differentiating clarity and a usage hint. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, open-world tool with three well-documented parameters and no output schema, the description covers the essential aspects: what it returns, how pagination works, and a critical distinction from a sibling tool. It could mention the expected response structure, but given the simplicity and the absence of an output schema, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter already has a clear description (count, cursor, list_id). The tool description itself adds little beyond mentioning 'cursor-paginated' and the normality of small counts, which slightly reinforces the count/cursor semantics but does not materially enhance what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the resource 'public List's followers' by numeric id, and specifies cursor-pagination. It also explicitly distinguishes from twitter_list_members, which is a sibling tool, ensuring the agent picks the right one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use twitter_list_members for the member roster instead, and explains the conceptual difference between followers and members. It also preempts confusion about small result counts, providing clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false; the description builds on this with genuinely non-obvious behavior: search-index lag causing missing recent posts, no retweets returned, and the filterable nature. This goes beyond annotations without contradicting them. A small deduction for not addressing return-format or error behavior, though pagination via cursor is mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Five dense, front-loaded sentences, each earning its place: purpose → key filters → limitations/lag → alternative tool → pagination and ID location. No filler, no redundancy, and the critical differentiator ('FILTERABLE List feed') is bolded and appears early.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only 7-param list tool with 100% schema coverage, the description covers purpose, alternates, caveats, pagination, and ID discovery. With no output schema, it might briefly note the pagination response shape, but 'Paginate with cursor' plus the rich schema largely compensate. Minor gap keeps it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with exceptionally detailed parameter descriptions (clamping behavior, exclusive until semantics, 400 on bad format, string 'true'/'false' for include_replies). The description adds the 'Paginate with cursor' directive but this is also implied by the cursor schema entry. Per calibration, high coverage makes 3 the correct baseline since the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Uses a specific verb+resource pairing ('Read the posts written by the members of a public Twitter/X List, newest first, through X's search index') that fully specifies scope, ordering, and mechanism. Explicitly differentiates from sibling twitter_list_timeline by contrast ('Use twitter_list_timeline instead when...').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the alternative (twitter_list_timeline) and states exactly when to choose it over this tool ('when you want the List exactly as X shows it, retweets and native ordering included'), including the tradeoff ('accept that it takes no filters'). This is textbook when-to-use-vs-alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds genuine value by explaining the three-phase latency model (detected_lag from tweet post to enqueue, delivery_lag for queue-to-webhook, total_lag), revealing the underlying pipeline architecture that helps agents interpret results. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action verb and resource, with a dense but justified parenthetical explaining the latency semantics. The trailing 'Free per call' is slightly odd and the single-sentence structure with semicolons is dense, but every element serves a purpose in about 50 words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter, zero required params, and strong annotations, the description covers exactly the non-obvious parts: the latency breakdown definitions and cross-monitor scope. Nothing material is left unexplained that schema or annotations don't already handle.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — the limit parameter is fully documented with range (1-200) and default (50). The description's field list provides result context but doesn't add parameter-level meaning beyond schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource+scope: 'List your most recent monitor delivery events across every monitor, most recent first' with an explicit field list. Clearly distinguishes from siblings like twitter_monitor_webhook_list (webhook config) and twitter_monitor_list (monitors themselves) by scoping this to delivery events with latency metrics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
'Across every monitor' and 'most recent first' establish clear scope and ordering. The explanation of the three latency fields signals when this tool is needed (latency diagnosis). However, there's no explicit when-not-to-use guidance or named alternatives as seen in the top-tier calibration example.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It discloses critical behavior well beyond the annotations: the HMAC signing secret is returned only once, must be stored immediately, cannot be retrieved again, and is used to verify the X-TwitterAPIs-Signature header on every delivery. It also notes that IP restrictions are re-checked at every delivery, not just at registration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and every sentence earns its place: the first states the purpose, the second delivers the crucial secret-handling and signature-verification warning. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter creation tool with no output schema, the description covers purpose, side effects, secret handling, signature verification, URL validation, and cost. It could more explicitly describe the full response shape or mention limits, but the essential operational information is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the url parameter, including constraints on private, loopback, link-local, and metadata IPs. The tool description itself adds no additional parameter-level meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Register an HTTPS endpoint to receive signed monitor events.' This clearly distinguishes it from sibling tools like twitter_monitor_webhook_list, twitter_monitor_webhook_delete, and twitter_monitor_webhook_test.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the use case: registering an HTTPS endpoint to receive signed monitor events, and adds the cost note 'Free per call.' However, it does not explicitly contrast with the list/delete/test siblings or mention when not to use it, so it falls short of full alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description lists specific data returned, adding context beyond annotations (readOnlyHint, destructiveHint). No contradiction; it aligns with read-only nature and enriches what the tool outputs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with key details. First sentence lists returned fields; second provides usage context and parameter clarification. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with no output schema, the description adequately covers return fields. Does not mention potential nested objects or size limitations, but these are minor for a single-tweet detail tool. Good enough for agent selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and description adds: 'Accepts either the tweet id or its full URL' and clarifies exactly one should be provided. This adds value beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get the full detail of a single tweet' and lists specific fields (text, author profile, timestamp, engagement counts, media, quoted tweet, parent reply context). It distinguishes from siblings like twitter_tweet_replies and twitter_tweet_thread by noting use before fetching replies or thread.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes explicit guidance: 'Use this to inspect a specific tweet before fetching its replies or thread.' Also clarifies that either id or URL can be provided. Does not provide when-not-to-use or alternatives, but the context is sufficient for basic differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the destructive nature (remove a like) and requires write capability, adding context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with clear action and requirements, no unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Sufficient for a simple action; no output schema needed and input requirements are stated, though error handling is not mentioned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Clarifies that exactly one of id or url should be provided, which is not enforced in schema, adding value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it removes a like from a tweet, with verb and resource, and distinguishes from sibling favorite_tweet.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides instruction to provide tweet id or url and mentions write capability requirement, but lacks explicit comparison to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 known. The description adds behavioral context beyond annotations by noting 'more reliable cursoring' and 'richer profile fields,' which are useful for understanding pagination and output characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, then usage guidance. No filler or redundant information. Each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple list operation with well-documented parameters and safety annotations. The description mentions the v2 payload and cursor reliability, which gives reasonable context. Without an output schema, it doesn't describe return format, but for a read-only list tool this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all four parameters. The description adds no extra parameter meaning beyond saying 'Same inputs as twitter_user_following,' which is redundant. Baseline of 3 applies because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('accounts a user follows'), and explicitly differentiates from sibling tool twitter_user_following by mentioning the v2 response shape and richer profile fields. This is a specific and unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to prefer this tool over the alternative: 'prefer this when you need the fuller v2 payload or are paging deep following lists.' This gives clear selection guidance and implies when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds that it returns 'complete public profile' and is identical to twitter_user_info, providing useful context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with main action, no redundancy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with one required param and read-only nature. Description, schema, and annotations together provide sufficient context for an agent to use correctly. Could be improved by mentioning return fields, but not essential given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a detailed description for user_id. Tool description only mentions 'numeric user id', adding no extra meaning beyond what schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb (get), resource (public profile), and method (by numeric id). Explicitly distinguishes from sibling twitter_user_info by noting identical response but different input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: when user_id is already known and handle lookup is to be avoided. Implicitly contrasts with twitter_user_info which likely requires a handle.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare `readOnlyHint=true` and `destructiveHint=false`, and the description aligns by stating it retrieves public tweets without modifying data. It adds valuable behavioral details: using the `to:` operator, returning author info and metrics, and pagination via cursor. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) and front-loaded with the core action. Every sentence adds value: defining what it does, how it works, what it returns, and when to use it. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the return includes 'matching tweets with author info and metrics,' providing adequate context for a read-only list tool without an output schema. While it could detail fields further, the common structure of Twitter tweets is widely understood, making this sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters have full schema descriptions (100% coverage). The description reinforces cursor usage for pagination but does not add deeper semantics beyond the schema. Baseline of 3 is appropriate as the description adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves recent public tweets mentioning a user via the `to:` operator, specifying the resource (tweets mentioning a user) and verb (get). It provides concrete use cases like monitoring brand mentions or replies, distinguishing it from sibling tools like `twitter_advanced_search` or `twitter_user_tweets`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers explicit use cases (monitor brand mentions, replies, public conversations) but does not explicitly state when not to use the tool or name specific alternatives. However, the sibling tools list and the mention of the `to:` operator implicitly guide choice, leaving room for improvement in exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses what the tool returns (tweet text, author info, engagement metrics, pagination cursor) and explains pagination via cursor. Annotations already declare readOnlyHint and destructiveHint, so the behavioral burden is partially met. The description adds value without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph of four sentences, each serving a purpose: stating the use case, listing operators, describing output, and giving examples. No wasted words, front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 the return values, pagination, and parameter usage well. It could mention authentication or rate limits, but annotations already signal read-only safety. Overall, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions, but the tool description adds significant context: it explains the operators supported (from:, since:, min_faves:), provides example queries, clarifies default for count, and describes product values beyond the enum names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches recent tweets using X's advanced-search operators. It specifies the verb 'search' and the resource 'recent tweets', and distinguishes itself from siblings like twitter_home_timeline and twitter_user_tweets by focusing on advanced operators.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use product values ('Latest' for chronological, 'Top' for engagement-ranked) and includes example queries. However, it does not explicitly exclude alternatives like twitter_user_search or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description explains authentication requirements, the absence of a user_id parameter, and crucial error semantics—an empty users array is a valid result meaning no blocks, not a failure, because the endpoint returns an error instead. This is rich behavioral context beyond readOnlyHint and destructiveHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary action, and every sentence adds value—scope clarification, auth note, and error interpretation. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description covers key operational aspects: pagination via cursor, auth requirement, no user_id limitation, and empty-array semantics. It is fully 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds some context around pagination and authentication but does not significantly deepen parameter understanding beyond the schema's field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists blocked accounts for the authenticated user, with specific verb 'List' and resource 'accounts YOUR authenticated account has BLOCKED'. It distinguishes itself from siblings by emphasizing no user_id argument and reading only your own block list, unlike user-specific tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is for viewing your own block list, and explicitly notes that X provides no way to read another account's block list. It does not name alternative tools, but the scope and limitations are clear enough for an agent to decide when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only (readOnlyHint) and non-destructive (destructiveHint false). The description adds valuable transparency by mentioning the authenticated session requirement and specifying the exact output fields (id, name, cover image), which is 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise, with four sentences covering purpose, differentiation, auth, output, and alternative usage. Each sentence adds value, though it could be tightened by removing the parenthetical definition of 'collections' without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (list folders) and the presence of a full input schema with per-parameter descriptions, the description covers the essential aspects: what it does, auth prerequisite, output fields, and alternatives. It lacks details on error cases or rate limits, but these are not critical for this read-only operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides descriptions for each optional parameter (ct0, proxy_url, auth_token, user_agent). The description adds semantic clarity by stating 'Takes no arguments' meaning no resource-specific arguments, and implies these parameters are for session/auth context. However, the phrase 'Takes no arguments' could be slightly misleading given the schema parameters, but it is contextually clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('YOUR authenticated account's bookmark FOLDERS'), and differentiates from the flat bookmarks list (twitter_bookmarks) and the folder timeline tool. It also explains the internal name 'collections' for clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly contrasts with twitter_bookmarks (flat list) and directs users to twitter_bookmark_folder_timeline for reading tweets inside a folder, providing clear when-to-use guidance. It also notes the authentication requirement as a prerequisite.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. It adds behavioral context by specifying that it returns 'FULL user profiles' with detailed fields, which goes beyond the schema. It also clarifies the endpoint is about people, not the community object, adding useful nuance beyond what annotations convey. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, tightly written, and front-loaded with the core purpose. Every clause adds value: it states what it returns, contrasts with reduced-row siblings, and directs to the correct alternative for metadata. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with strong annotations and full schema coverage, the description provides complete context. It describes the output content (full profiles with specific fields), explains the differentiation from related tools, and clarifies the scope (people vs community object). No output schema exists, but the description sufficiently conveys what to expect. The tool's complexity is low, and nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description fully covers community_id with an example and URL context (100% coverage). The tool description does not add any extra parameter semantics, but the schema is sufficient. Baseline 3 applies because the parameter is already well-documented; the description does not need to repeat it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: returning full user profiles for a community's moderators and a preview of its members. It names the specific fields included and explicitly distinguishes it from sibling tools like twitter_community_members and twitter_community_moderators, which return reduced rows, and twitter_community_info, which covers community metadata. This makes the purpose unambiguous and easily differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance and names alternatives: it says to use this tool when full profiles are needed versus reduced rows from twitter_community_members/moderators, and directs users to twitter_community_info for community metadata. It also explains that this endpoint answers 'who runs a community' in one call, covering when and why to choose it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds valuable behavioral context: cursor-paginated results, compact hit structure with specific fields, and the guarantee that it returns only what X's own search sends. This goes beyond annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main action, followed by relationship context and response details. No filler words; every clause contributes meaningful information about usage or behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description covers purpose, pagination, response shape, and downstream tool usage. Annotations cover safety, and the tool is simple enough that this description is fully sufficient for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage for both parameters (query and cursor), so the description doesn't need to compensate. The description mentions cursor-paginated but adds no new parameter details beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Find X Communities by keyword') and resource (X Communities). It distinguishes itself from sibling community tools by explicitly positioning itself as the discovery step that produces community IDs, which other endpoints consume.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use: as the entry point for the community family, and directs users to specific sibling tools once an ID is obtained. It also implies when not to use it (when you already have an ID, use detail endpoints).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint, readOnlyHint), the description adds crucial behavioral context: 'Irreversible' clarifies the permanence, and 'Delivery history referencing this monitor is retained, not cascade-deleted' discloses the exact side-effect on related data. The 'Free per call' note also provides cost transparency. This meaningfully exceeds what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each serving a distinct purpose: action and irreversibility, alternative for future use, and retention of delivery history plus cost. It is tightly written, front-loaded with the core purpose, and contains zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete operation, this description is complete. It covers the action, irreversibility, relevant side-effect (delivery history retention), and cost. With no output schema required and the schema fully documenting the parameter, there are no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the sole parameter 'id' with a description ('The monitor's id, from twitter_monitor_create or twitter_monitor_list'), so the description does not need to add param semantics. The description references 'by id' but adds no new information beyond the schema. Baseline of 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Stop and remove') and resource ('a monitor by id'). It distinguishes itself from sibling tools by explicitly mentioning the irreversible nature and referring to twitter_monitor_create as the way to re-create a monitor, making it distinct from update/list/health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use this tool (to stop and remove a monitor) and gives an explicit alternative for the same goal after deletion ('create a new monitor with twitter_monitor_create'). However, it does not mention when not to use it, such as if a temporary pause is needed (which might warrant twitter_monitor_update instead). This slightly limits the guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 known. The description adds useful behavioral details: the signing secret is only returned at creation, and the status meanings are explained (e.g., 'disabled' means 410 Gone and requires re-registering). This goes 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first fronts the purpose and fields, the second provides a key caveat about the signing secret and confirms no arguments. Every sentence adds value with zero redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no output schema, the description fully covers what will be returned (id, url, status, created_at), explains status semantics, and notes the exclusion of the signing secret. It is complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and the schema is empty (100% coverage). The description explicitly states 'Takes no arguments,' which reinforces the schema and removes any ambiguity. Baseline for 0 params is 4, and this meets it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List every webhook registered on your account' and specifies the exact fields returned (id, url, status, created_at). It uses a specific verb and resource, and implicitly distinguishes itself from sibling tools like webhook_create, webhook_delete, and webhook_test.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The name and description make it obvious this is the listing operation; it provides context on when to use it (to see webhooks and check their status). However, it does not explicitly mention alternatives for create/delete/test operations, relying on sibling names for differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations indicate readOnlyHint=false and destructiveHint=false, the description adds substantial behavioral details: the event is HMAC-signed, sent synchronously with a delivery timeout, returns delivered/status_code/error, is never queued/retried/dead-lettered, and is free. This goes beyond the annotations and provides a clear understanding of the tool's side effects and guarantees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, immediately stating the primary action and return values. Every sentence adds value: the synchronous nature, the outcome fields, the contrast with real events, and the free pricing. No unnecessary repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is remarkably complete. It explains the exact behavior (synchronous send, timeout, outcome), the difference from regular events, and the purpose. It covers authentication (HMAC-signed), and the free aspect, leaving little ambiguity for an agent selecting this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents the 'id' parameter, including its source ('from twitter_monitor_webhook_create or twitter_monitor_webhook_list'). The description does not add any additional semantic meaning beyond what the schema provides, so the baseline score of 3 applies due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Send one HMAC-signed test event to this webhook's URL right now and return the outcome synchronously'. It identifies the specific verb (send) and resource (webhook), and the return values (delivered, status_code, error). It distinguishes itself from sibling tools like create/list/delete by focusing on testing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit timing: 'to confirm your endpoint and signature verification both work before relying on the webhook' and contrasts with real events: 'Unlike a real monitor event, a test send is never queued, retried, or dead-lettered'. It gives clear context for when to use, though it does not explicitly name alternative tools or state when not to use it; the contrast with real events implies alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only safety (readOnlyHint: true, destructiveHint: false). The description adds value by explaining the tool returns the full ordered sequence in a single call and specifically excludes replies, providing context on the output shape without contradicting 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, includes a critical exclusion, and contains zero redundant words. It efficiently conveys all essential information without excess.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with no output schema, the description fully covers what it does, how to invoke it (any id/url), and what it excludes, making it sufficient for an agent to correctly select and use it. No significant behavioral details are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for id and url, and the schema already notes 'Provide exactly one of id or url'. The description adds the crucial detail that any tweet id or URL from the thread works, reinforcing flexibility beyond the schema's basic field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Get all tweets in a thread') and clearly defines the scope (same author, ordered sequence). It distinguishes itself from the sibling tool twitter_tweet_replies by explicitly limiting to the author's own tweets, avoiding confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when NOT to use it ('Does NOT return replies from other users') and directs to the alternative twitter_tweet_replies. It also gives practical usage guidance ('Pass any tweet id/url from the thread'), but does not exhaustively cover all possible exclusions or alternative tools, so not a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint: true, destructiveHint: false) already signal a safe read operation. The description adds critical details about the two auth models (API key vs. session), the 404 error handling (returns article: null), and ownership requirements for drafts. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single comprehensive paragraph covering purpose, forms, auth, and errors. It is information-dense but not verbose; every sentence contributes. While it could be broken into bullets, it's appropriately sized for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the full API surface: purpose, both forms, authentication requirements, error conditions, and relationships to other article tools. Even without an output schema, it lists returned fields (title, content_state, etc.) and handles edge cases like drafts and 404s. For a tool with this complexity, it is exceptionally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions, so baseline is 3. The description adds value by explaining that id, url, and article_id are mutually exclusive and that article_id is the owner-only form. This metacommentary helps an agent choose the correct parameter, exceeding what the schema alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Read an article's full content') and clearly distinguishes the two invocation forms (PUBLIC via id/url, OWNER-ONLY via article_id). It differentiates this read operation from sibling tools like twitter_article_create/list/delete, which are referenced for context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly covers when to use the PUBLIC form (published articles, no session needed, id/url) versus the OWNER-ONLY form (requires authentication, drafts). It also explains the 404 behavior for not found/visible/owned. Although it doesn't explicitly name an alternative tool, the usage contexts are clear and reference sibling tools for article_id sources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint: false, destructiveHint: false), so the description rightly carries the burden and adds context: acts 'AS your authenticated account,' requires write capability, clarifies it does NOT upload, and discloses the return shape ('updated article object with cover_media populated'). 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four information-dense sentences, front-loaded with the core action in the first clause. Use of ALL-CAPS emphasis ('ALREADY-UPLOADED,' 'NOT') aids scanning. No wasted words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-param, 2-required tool with no output schema and no enums/nesting, the description covers the key gaps: return shape, auth requirements, and cross-tool dependencies. Adequately complete given the moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds genuine value by cross-referencing which sibling tool produces each identifier (media_id from twitter_media_upload, id from twitter_article_create/list), going beyond what the schema alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource: "Attach an ALREADY-UPLOADED image as the cover of a DRAFT or PUBLISHED article." Clearly distinguishes from siblings by explicitly contrasting with twitter_media_upload and naming provenance tools (twitter_article_create/twitter_article_list).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit workflow guidance: 'call twitter_media_upload first and pass the media_id it returns' gives when-to-use and sequencing, 'This does NOT upload' gives exclusions, and 'Requires an authenticated session with write capability' states preconditions. Names exact sibling tools for ID provenance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Exceptionally rich behavioral disclosure beyond the annotations: exact return fields, the member_count null-as-not-applied signal, the 422-with-identical-field-layout behavior for failed writes, and a 'not billed' note for non-applied writes. The description does not contradict readOnlyHint=false or openWorldHint=true; rather, it complements them with operational detail that annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Dense single paragraph with zero filler — every sentence carries meaning (purpose, example, response format, edge-case signal, reversal). It's on the longer side and slightly run-on in the middle sentence, but the information density justifies the length. A touch of formatting (e.g., separating the reversal note) would make it perfect.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a side-effect-heavy mutation with no output schema, the description is remarkably complete: full return value list, a concrete confirmation pattern (read member_count), explicit failure modes (already a member, not your list), status code (422), and billing implications. No output schema exists, so explaining the return shape in prose is exactly what's needed and it does so thoroughly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3; the description adds value by clarifying both IDs are numeric and connecting them to the write action. The schema descriptions themselves are strong (URL format for list_id, cross-reference to twitter_user_info for user_id resolution, proxy recommendation for writes). Slight deduction for the description text not adding much beyond 'numeric' since the schema already documents each parameter thoroughly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource pair ('Add one account to a Twitter/X List') and clarifies scope with 'that YOUR registered X session owns' and 'by numeric list id and numeric user id'. It clearly differentiates from the sibling twitter_list_remove_member by naming it as the reverse operation, and the ownership constraint distinguishes it from list-reading tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a concrete use case ('adding each speaker at a conference to a List as they are announced') and explicitly names twitter_list_remove_member for reversal. The ownership prerequisite is stated upfront. Loses a point because it doesn't explicitly enumerate when NOT to use it relative to other write tools (e.g., twitter_create_list), though the reverse tool reference helps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly=false, destructive=false), the description discloses that the operation creates a resource, returns a list id, and explains the public/private visibility semantics. This adds meaningful behavioral detail not implied by the annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is informative but slightly verbose, repeating 'registered X session' and including detailed return values. However, it is well-structured and free of fluff, earning a score above average.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage flow, return values (list_id, member_count, full list object), and privacy behavior. Given the lack of an output schema, it sufficiently explains what to expect from the call, making the context complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for all 7 parameters with clear descriptions (e.g., ct0, proxy_url, is_private). The tool description does not add extra parameter guidance, but since schema coverage is high, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new Twitter/X List and distinguishes it from related tools like twitter_list_add_member by positioning it as the initial step. The verb 'create' is specific and the resource is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs when to use it ('starting point for building a List') and how to chain it with twitter_list_add_member using the returned list id. It also clarifies privacy defaults and implications, giving clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint: false and destructiveHint: true, but the description goes further: it details the exact response fields, the meaning of null member_count (not-applied signal), and that non-applied writes return a 422 with a machine-readable reason and are not billed. This is rich behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but a bit long (4 sentences) and dives into response details and error semantics. However, it is front-loaded with the core purpose and use case, and every sentence adds value (response interpretation, billing, reversal). Slightly over-specified but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schemalint, the description thoroughly covers purpose, response fields, success/failure signals, and billing behavior. It also notes proxy recommendation for writes (in schema) and provides a clear reversal path. Complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter already described (e.g., list_id and user_id include URL and resolution guidance). The description adds little beyond schema, but the description does mention the dependency on resolving handle to user_id via twitter_user_info, which is implied in schema; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (remove one account from a Twitter/X List), specifies the required identifiers (numeric list id and user id), and scopes the operation to 'YOUR registered X session owns' a list. It explicitly distinguishes from sibling twitter_list_add_member by naming the reverse operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a concrete use case ('prune a curated List, for example dropping accounts that have gone quiet') and explicitly mentions the reverse tool (twitter_list_add_member) for undoing. It also states when the write will not apply (account not a member, list not yours), giving clear guidance on alternative actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already indicating read-only and non-destructive, the description adds extensive behavioral context: the endpoint is search-backed, count is not authoritative, and quote_matched indicates result quality. It also warns about junk pages, which is beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence adds value, starting with purpose, then differentiation, then critical caveats. It is logically structured, though the single-paragraph format could be improved with line breaks for readability. Still, it is appropriately sized for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description explains return fields (source, search_query, quote_matched) and edge cases like quote_matched zero on non-empty pages. It covers pagination via cursor and the fallback behavior of product, making it comprehensive for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with detailed parameter descriptions. The description does not add additional parameter-level meaning, though it contextualizes the importance of 'count' versus 'quote_count' in output interpretation. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists tweets that quote a specific tweet, with a specific verb and resource. It explicitly differentiates from sibling tools twitter_tweet_retweeters and twitter_tweet_replies, eliminating ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use and when-not-to-use guidance by contrasting with retweets and replies. It also warns about the search-backed nature and explains how to interpret the count, giving clear context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description does not contradict these. It adds value by detailing the fields returned (e.g., account category, verification flags, transparency panel), but does not introduce any new behavioral aspects beyond the read-only nature already annotated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat lengthy due to enumerating many returned fields, but each item is relevant and contributes to the tool's purpose. It is well-structured, front-loaded with the main function, and avoids unnecessary fluff, though it could be slightly tightened without loss of meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully compensates by naming the specific attributes returned (account category, labels, verification flags, joined date, location, etc.). It also provides usage context and differentiates from a sibling tool, making it complete for an agent to understand what it will get and when to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes both parameters and their exclusivity. The description reinforces this by stating 'Provide a username or a user_id,' which adds clarity on the mutual exclusivity but does not introduce significant new meaning beyond the schema. Given 100% schema coverage, this is above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it retrieves a user's full 'About' object with detailed profile facts, and explicitly distinguishes itself from twitter_user_info by indicating it provides richer data beyond that tool. The verb 'Get' and specific resource are precise, 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.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage instructions: 'Provide a username or a user_id' and 'Use this to enrich a profile beyond what twitter_user_info returns.' This tells the agent exactly when to employ this tool and mentions the alternative (twitter_user_info), offering clear contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses that it stores a session server-side and does not return cookies, warns against logging credentials, and lists typical failure states (bad_credentials, two_factor_required, etc.). This is valuable transparency beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense yet compact paragraph that efficiently packs key info: purpose, dependencies, return format, typical failures, and security advice. It is front-loaded with the core purpose and doesn't include filler. Slightly dense but concise overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, no output schema), the description fully covers the needed context: what it does, what it doesn't return, typical error codes with suggestions, and critical security warnings. It leaves no major gaps for an agent to misuse the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents each parameter. The description adds context: totp_secret is only required if 2FA, proxy_url is recommended to be a residential proxy (X treats datacenter logins as automated), user_agent should match the account's typical environment. These additional notes enhance parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Log in' and targets the resource 'X' (account). It clearly states the purpose: authenticate and store the session for subsequent authenticated reads/writes. It distinguishes from siblings (e.g., twitter_account_me) by being the login action and explicitly not returning session cookies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use: to authenticate before other account-scoped tools. It gives typical failure codes and how to resolve them. It doesn't explicitly mention when not to use or alternatives, but given the sibling set, there is no obvious alternative. Thus it lacks explicit exclusions but still useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, openWorldHint=true, destructiveHint=false) already declare a safe read operation; the description enriches this by explaining that every outcome is a successful HTTP response, that protected accounts count as 'alive', and how to interpret X's own reason. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured and front-loaded: purpose first, then return semantics, then comparisons, then edge cases. Every sentence contributes—the only quibble is the length could be trimmed, but nothing is wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter status-check tool with no output schema, the description provides everything needed: all four status values, conditions for each, numeric id disclosure, and the protected-account edge case. It is complete for the tool's complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%—the single parameter already includes a clear description with examples ('WITHOUT the leading @ (e.g. 'elonmusk', 'openai', 'sama')'). The description adds no parameter-specific info, but the schema carries the full burden, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+scope ('Check whether a Twitter/X account is alive, suspended, or deleted') and enumerates the exact statuses returned. It further distinguishes itself from twitter_user_info by explaining that the sibling cannot distinguish a ban from a typo, which is strong differentiation in a large sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the alternative tool ('Use this instead of twitter_user_info') and gives a precise decision rule—when the QUESTION is whether the account still exists—with a rationale (user info answers all miss-cases the same way). Adds operational guidance: 'read the status field rather than treating a suspension as an error.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it's not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds context by saying 'watch an X account' implying a monitoring setup, but it doesn't explicitly disclose potential side effects like creating a monitor or adding to an existing stream. However, it doesn't contradict annotations, and the annotation provides a baseline, so a score of 4 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a bit verbose with the colon-separated explanatory phrase and the migration note, but it remains focused and informative. It could be slightly more concise, but every sentence adds value (purpose, migration context, cost).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description doesn't explain what the tool returns, but it's a compat drop so the output might be implied. It covers the main purpose, usage, and the existence of an alternative. It doesn't mention error conditions or limitations, but for a simple one-parameter tool, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (x_user_name) is described clearly: 'The X username to watch, without the @.' This provides both the meaning and format. Schema coverage is 100%, and the description adds value by specifying the absence of '@'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'watch an X account for new posts' and explicitly distinguishes it from twitter_monitor_create by positioning it as a compat drop for migration. The verb 'watch' and resource 'X account' are specific, and it differentiates from the sibling tool twitter_monitor_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Prefer twitter_monitor_create for new integrations; this exists for migrating an existing x_user_stream-shaped integration without a rewrite.' It also notes 'Free per call' which is a cost consideration. This clearly indicates when to use and when to avoid the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and destructiveHint annotations, the description honestly documents that x_user_id is always null and is_monitor_profile is always 0, plus 'Free per call.' This is rich behavioral context and does not contradict any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences: the core purpose in the first, important field caveats in the second, and cost in the third. It is front-loaded and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the burden for return behavior. It explains key envelope fields and the monitoring scope, but does not enumerate the full output shape or pagination; still sufficient for a zero-param list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. No parameter documentation is needed, and the description adds useful output-field semantics instead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'list every account you are currently tweet-monitoring.' It also explicitly positions itself as a 'Compat drop-in for twitter_monitor_list', which distinguishes it from sibling list/add/remove tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
'Compat drop-in for twitter_monitor_list' gives clear context that this is the x_user_stream-shaped replacement for that sibling tool. It implies when to use it relative to the native monitor list, though it does not spell out when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the annotations by disclosing authentication via API key, clarifying that this is an account read (not Twitter data), and stating it is free with no credit cost. These details are not present in the annotations (readOnlyHint, openWorldHint, destructiveHint), enriching the behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the main purpose and followed by essential caveats. Every sentence earns its place without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, no-parameter read tool with no output schema, the description fully covers the return fields, authentication, and cost implications. It is complete for the agent to correctly select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage, the description doesn't need to explain params. It still usefully describes what the tool returns, which is more than sufficient given the baseline for 0 params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get), the resource (YOUR twitterapis.com account details), and enumerates the specific data returned (email, name, credits, etc.). It also distinguishes itself from sibling tools by explicitly noting this is an account read, not Twitter data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is for retrieving account details, not Twitter data, and it is free (does not spend credits). This implicitly tells the agent when to use this tool over data-focused siblings, though it does not explicitly name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's 'Irreversible' statement adds value by emphasizing permanence. It also discloses the extra round trip when hints are omitted, and the requirement for write capability. While it doesn't detail the exact response format, it states 'Returns ok/deleted and the id you targeted', which is sufficient given 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense paragraph that front-loads the core action and then adds necessary nuance. Every sentence earns its place: the draft vs. published distinction, the comparison to unpublish, the irreversibility warning, the fast-path hints, and the auth requirement. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (two lifecycle paths, optional hints, auth requirements) and the absence of an output schema, the description covers all critical aspects: what happens to drafts vs. published articles, the tweet deletion, the fast-path hints, the auth requirement, and the return value. It's complete for an agent to decide and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 7 parameters. The description adds value by explaining the fast-path hints (lifecycle, tweet_id) and their performance implications, and clarifies that auth_token/ct0 must be paired. This goes beyond the schema's basic descriptions, though the schema already covers the essentials.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes an article as the authenticated account, distinguishes between draft (hard-delete) and published (unpublish + delete tweet) behavior, and explicitly contrasts with twitter_article_unpublish. It names the specific resource (article) and the action (delete), 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.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use this tool (to fully remove a published article's public footprint) and when not to (compare twitter_article_unpublish, which leaves the tweet up). It also provides guidance on optional fast-path hints (lifecycle, tweet_id) and when to omit them, plus the requirement for an authenticated session with write capability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description complements by explaining that it's scoped to the authenticated account (not all articles), requires an authenticated session (ct0, auth_token), yields most recent first, and paginates via cursor. It doesn't contradict annotations and adds valuable context about session/auth requirements and the lack of a combined view. Slight deduction for not mentioning rate limits or potential errors, but generally strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact but information-dense, covering purpose, scoping, lifecycle behavior, authentication, pagination, and return structure. It front-loads the core message of listing your own articles, then adds necessary details without redundancy. Every sentence contributes value, and it stays well under 150 words for a tool with 7 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains return fields (count, next_cursor, article objects). It covers authentication requirements, pagination mechanics, and the lifecycle limitation. For a read-only list tool with comprehensive parameter descriptions and annotations (readOnlyHint, openWorldHint), this description is complete and self-contained. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a description. The description adds context by stating the default count (20), the behavior of cursor (null/absent means no more pages), and that lifecycle must be explicitly changed to published. It also explains the auth cookie requirement and proxy_url recommendation for writes. While the schema already explains each parameter clearly, the description enriches the semantics with default values and practical usage patterns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists the authenticated user's own articles, with a specific verb ('list'), resource ('articles'), and scope ('YOUR OWN', 'AS your authenticated account'). It distinguishes itself from sibling tools that list articles for other users or manage webhooks/tweets by emphasizing the authenticated account's own articles and the lifecycle filter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: for listing one's own published or draft articles, and when not to: when needing a combined view, as X exposes no combined view. It provides clear guidance on using the 'lifecycle' parameter (published vs draft) and explicitly mentions pagination via 'cursor', which is a direct alternative to not using it. No alternatives are needed since this is a unique tool for listing own articles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already mark the operation as non-read-only, the description goes far beyond by disclosing that the announcement tweet is REAL and PUBLIC, that the action is hard to fully undo, and that even after deletion the content was already public. It also describes authentication prerequisites and provides high-value context about the exact reversal behaviors of sibling tools, with no contradiction to 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and then builds out critical warning and side-effect context. Every sentence serves a distinct purpose: warning about irreversibility, naming alternatives, giving confirmation guidance, and covering defaults and prerequisites. The length is justified given the consequential nature of the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters, complex state transitions, and no output schema, yet the description succeeds in covering what matters: the outcome, the order of operations, side effects, undo semantics, defaults, return value, and authentication needs. The agent is equipped to decide, confirm, and invoke safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers 100% of parameters with detailed descriptions, so the baseline is 3. The description repeats a few key facts (id must be a draft, audience and reply_control default to 'Everyone', caption max 256 characters) but does not add new parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's core action—publish a DRAFT article as the authenticated account—and specifies the resulting state change: transitioning to Published and posting a REAL, PUBLIC announcement tweet. It distinguishes itself from sibling tools by explicitly naming twitter_article_unpublish and twitter_article_delete and their different reversal behaviors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: publishing a draft article with a public announcement tweet. It also gives exclusionary context by explaining that unpublish only reverts the article but leaves the tweet, and that only delete on a published article removes both. Additionally, it instructs the agent to confirm with the caller unless explicitly authorized, which is clear and actionable usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details side effects (tweet left in place), requirements (write capability, authenticated session), error behavior (invalid_lifecycle), and return value (updated Draft article). This goes beyond the annotation (destructiveHint) by specifying exactly what is and isn't affected, without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and structured: it states the action, the side effect, the alternative, the error condition, the requirement, and the return value in a few clear sentences without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers all critical aspects: what it does, side effects, when to use an alternative, error scenarios, authentication needs, and the return object. It is complete enough for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with per-parameter descriptions (e.g., id, auth_token), so the description doesn't need to add parameter details. It does mention authentication and write capability generally, but does not specifically elaborate on individual parameters, keeping it at the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (revert a PUBLISHED article to Draft) and distinguishes it from the delete alternative (which also removes the tweet). It specifies the resource (article) and the state transition, making it unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains when to use this tool versus the alternative (twitter_article_delete) when tweet removal is also desired. It also mentions the error condition if the article is not published, providing clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, but the description goes further by explaining why viewer-relative fields (role, can_join, is_pinned, viewer_relationship_type) are always null due to pooled rotating accounts, and why rules[].description is always null. This prevents misinterpreting expected nulls as errors—valuable behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then lists return fields, clarifies the ID format, highlights important null behavior, and closes with sibling pointers. It is long but every sentence carries essential information; no filler or repetition beyond what aids clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a response containing many heterogeneous fields (banners, rules, profiles, facepile IDs), the description compensates thoroughly by naming the return fields, explaining deliberate nulls, and clarifying ID semantics. It also gives usage boundaries with sibling tools, making it complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already provides detailed semantics for community_id, including type, format, example, and exclusions. The description restates the URL pattern and the 'NOT a Space id / NOT a user id' distinction, which reinforces but does not add significant new parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Get the metadata for one X Community by its numeric id" and then enumerates the exact fields returned. It distinguishes itself from sibling tools by pointing to twitter_community_members and twitter_community_tweets for other concerns, making its scope unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states both the context for use (single community metadata lookup by numeric ID) and directs users to alternatives: "Use twitter_community_members for the roster and twitter_community_tweets for the posts." It also clarifies the ID format with a concrete URL pattern, which guides correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and destructiveHint=false, and the description adds extra behavioral context: cursor-paginated output, the 'members' array name, absence of total count, and the presence of admins in results. No contradictions exist between description and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently written with a clear front-loaded purpose and every sentence adds meaningful value regarding behavior, correctness, or usage. It avoids redundant phrasing while packing in crucial distinctions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description provides the essential return shape and pagination behavior. It covers the row structure, the array name, the absence of a total count, and the mixed roles, giving an agent sufficient information to correctly interpret and paginate results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all parameters, so parameters are already well-documented. The description adds context about pagination ('bare next_cursor with no total count') which relates to the cursor parameter, but it doesn't substantially go beyond the schema information for count and community_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists moderators and admins of an X Community, with a specific verb ('List') and resource. It further distinguishes it from the sibling twitter_community_members by specifying the identical row shape and the fact it is a separate upstream operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use this tool over twitter_community_members, detailing that filtering member pages is incorrect due to arbitrary positions of moderators. It also advises reading each row's role because admins are present, which is actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description candidly discloses that the tool is stateless, buffered not streamed, requires session auth, and may return a model different from the one requested. It also clarifies that citations are merged/de-duplicated and that full conversation history must be re-sent. This is rich behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose and remains information-dense without padding. Each sentence gives genuinely new context: realtime Grok behavior, output shape, statelessness, and auth requirements. The formatting with clear term emphasis helps an agent parse key constraints quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 9 optional parameters and no output schema, this description covers the needed operational context: what returns, how citations are merged, how conversation continuity works, proxy/authentication concerns, and how turns are affected by mode. This is sufficient for an agent to invoke it with reasonable expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is already well served. The description adds useful semantics not obvious from the schema, such as treating a bare status URL as a first-class message for post summaries and showing that auth_token is never placed in the URL. Those details are not in the parameter names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action and resource: ask X's own Grok a question AS an authenticated account. It also describes the key output (single JSON reply with answer and citations) and the bare-tweet-URL summary use case, distinguishing it from the many other tweet/user/social-graph tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when this is uniquely useful, namely for questions about what is being said on X in real time, and that a bare status URL produces a structured post summary. It does not name sibling tools as alternatives or state explicit when-not-to-use cases, but the realtime Grok framing gives solid practical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only and non-destructive behavior, so the description adds valuable context: native feed semantics, retweet inclusion, inability to honor search operators, and pagination ending when the tweets array is empty. This goes beyond what annotations and schema alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: purpose, constraint, alternative comparison, and pagination stopping condition are each addressed once. The description is dense but well-organized and free of repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is self-sufficient for this tool: it communicates the data scope, ordering behavior, retweet inclusion, endpoint limitations, pagination signal, and the sibling tool to use for alternate needs. With provided annotations and a fully-documented schema, this is a complete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents list_id, count, and cursor. The description adds helpful high-level information about pagination and the absence of date/reply parameters, but it does not expand on individual parameter syntax, which keeps it at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and direct object: 'Read a public Twitter/X List's NATIVE feed.' It specifies the exact behavior (same posts and ordering as x.com, including retweets) and differentiates itself from twitter_list_tweets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit decision guidance: use twitter_list_tweets when you need a date range or filtered replies, and accept that the alternative drops retweets. It also clearly states what this endpoint cannot do (no date range, no reply filter).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral details: it reports service status and counts, zero-monitor behavior returns zeroed counts, takes no arguments, and mentions 'Free per call.' 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences but packs a wealth of information: purpose, contrast with sibling, output details, edge case, and cost. It is front-loaded with the main purpose and remains concise without superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully explains the tool's scope, return values, time window, and edge-case behavior. Given the tool has no parameters and no output schema, this description is complete and highly informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the description explicitly states 'Takes no arguments.' Per the rubric, zero parameters merit a baseline of 4, and this is adequately handled.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Account-wide monitoring rollup in ONE call' and distinguishes it from sibling twitter_monitor_health by specifying that the sibling requires an id and reports per-monitor cursor data. It also enumerates the exact outputs: service status, active/paused/total counts, and delivery counts from the last 24 hours.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides contrast with a specific alternative (twitter_monitor_health), giving clear context for when to use this rollup versus the per-monitor tool. It also notes the behavior for zero monitors ('A key with zero monitors gets zeroed counts back, never an error'), but does not include explicit 'when not to use' or other alternatives beyond the sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the readOnlyHint and destructiveHint annotations: muting is non-blocking, results are cursor-paginated, an empty users array means the account mutes nobody rather than a failure, and an authenticated session is required. This gives the agent a strong understanding of the tool's expected behavior and edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence and every subsequent sentence provides essential context: muting semantics, differentiation from blocking, auth requirements, no user_id limitation, and empty-array meaning. There is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full burden of explaining return behavior, and it does so well: full user objects, cursor-paginated results, and empty users array semantics. It also covers auth prerequisites and an important limitation, making the tool sufficiently complete for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all six parameters at 100% coverage, so the baseline is 3. The description does not add parameter-level detail beyond referencing cursor pagination and explicitly noting the absence of a user_id parameter, which is useful but not enough to raise the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists accounts the authenticated user has muted, returning full user objects with cursor pagination. It distinguishes itself from twitter_blocking by explaining the semantic difference between muting and blocking, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly names twitter_blocking as an alternative and explains why the lists differ. It also covers when not to use the tool by stating there is no user_id argument and X provides no way to read another account's mute list, and it clarifies the authenticated-session requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to repeat safety. It adds transparency by specifying the output (list of locations with WOEIDs) and its purpose, which goes 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that state the action, the output format, and the usage context. Every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description explains the return value (list of locations with WOEIDs) and how it integrates with twitter_trends. For a simple lookup tool, this is complete and enables correct invocation without further documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100%. The description explicitly states 'Takes no parameters,' which is sufficient for a parameterless tool. Baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists every location with its numeric WOEID, specifically for use with twitter_trends. It distinguishes itself from siblings by explaining its role as a lookup prerequisite, not just a generic list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use it: 'Use this to resolve a country or city to its WOEID before requesting trends for that place.' Also notes it takes no parameters, making invocation trivial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Building on the annotations (readOnlyHint true, openWorldHint true), the description discloses critical behavioral details: no server-side filtering, inclusion of retweets/replies, presence of boolean flags, author.username nuance, return fields (text, id, timestamp, engagement metrics), and pagination. This substantially exceeds what annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a concise purpose statement followed by a front-loaded critical caveat, return contents, pagination note, and an alternative tool reference. Every sentence serves a purpose with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description thoroughly explains response contents (flags, author field, text, id, timestamp, engagement metrics) and pagination behavior, making the tool's behavior fully understandable for correct invocation. The mention of the complete alternative covers larger data needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter fully described (count, cursor, user_id, username). The description adds no new parameter-level semantics beyond what the schema already states, though it mentions pagination via cursor. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as retrieving a user's recent posting timeline, using specific language ('Get a user's recent posting timeline') that distinguishes it from sibling tools. It explicitly names an alternative for the full back-catalogue (twitter_user_tweets_complete), further clarifying its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool vs alternatives, naming twitter_user_tweets_complete for full back-catalogue needs. It also explains client-side filtering for retweets/replies and pagination with cursor, giving clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations indicating readOnlyHint and openWorldHint, the description adds significant behavioral context: it mentions pagination via cursor, item booleans (is_retweet, is_reply, is_quote) for filtering, and the overlap behavior with sibling endpoint. This goes beyond the annotations, which are minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary purpose, and includes necessary filtering and pagination details without verbosity. Every sentence adds value, and the mention of sibling overlap is crucial.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list endpoint with no output schema, the description covers what the tool does, how to paginate, how to filter, and its relationship to a sibling tool. The complexity is moderate, and the schema already documents parameters well; the description fills the gap regarding response item booleans and overlap, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented in the schema. However, the description adds no additional param-specific meaning (e.g., examples or caveats). Since the schema covers everything, this is a solid baseline; the minor gap is not mentioning that 'cursor' is opaque but that is in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a user's full activity timeline, including original tweets and replies, which distinguishes it from the sibling tool twitter_user_tweets. It explicitly notes the overlap with twitter_user_tweets, making the distinction clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool (understanding engagement with a community) and notes that twitter_user_tweets does not filter replies or retweets, so they may produce overlapping results. It does not explicitly list when not to use it, but the context implies alternatives may be redundant.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations (readOnlyHint, openWorldHint) by disclosing auto-pagination, the Twitter's ~3200-tweet ceiling, and the return format (flat tweet array). It also mentions that higher max values take longer and cost more. Slight room for improvement: no mention of authentication or error behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with no unnecessary words. It front-loads the core purpose and efficiently covers usage guidance, prerequisites, and limitations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (auto-pagination, ceiling, cost) and no output schema, the description provides key context: ceiling, return type, prerequisite, and sibling differentiation. It could mention the structure of individual tweet objects or handling of errors, but overall it is sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds value beyond the schema: it clarifies that user_id must be numeric and resolved from a handle, and for max it provides a default (800) and explains performance/cost implications. Schema coverage is 100% but the description enriches understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a user's near-complete original-tweet history in a single call with auto-pagination. It distinguishes itself from the lighter sibling twitter_user_tweets by emphasizing it is for the whole back-catalogue rather than page-by-page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'use when you want the whole back-catalogue at once'. It also mentions when not to use it (vs page-by-page) and provides a prerequisite: 'Requires the numeric user_id (resolve a handle first with twitter_user_info)'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond that. It reveals that this is a 'pooled read' and that role/can_join/is_pinned/viewer_relationship_type are always null. It also discloses that an empty array is a real success, not an error, and that the result includes the full community object shape. This adds substantial behavioral context that annotations alone do not provide, and it does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but every sentence earns its place: it starts with the core purpose, then differentiates from siblings, explains the return shape, warns about the id type, clarifies empty results, and notes pooled-read quirks. It is front-loaded with the primary use case. Though not the shortest, the density of essential information justifies its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description fully explains what the caller will receive: 'Each row is the FULL community object (the same shape twitter_community_info returns...), so no follow-up call per community is needed.' It also covers pagination via cursor, the empty-array case, and the null fields on pooled reads. For a 3-parameter tool with no output schema, this is highly complete and self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 three parameters clearly. The description adds extra value by emphasizing that user_id is NOT a @handle and NOT a community id, and by recommending resolving a handle with twitter_user_info first to avoid a hidden second call. It also confirms count defaults and clamping, reinforcing the schema. This exceeds the baseline of 3 for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'given a numeric X USER id, list the communities that account belongs to'. It uses a specific verb (list) and resource (communities) and explicitly differentiates from other community tools by calling itself the 'INVERSE community lookup' and noting that every other community tool starts from a community, while this one starts from an account. This fully distinguishes it among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'makes it the tool for profiling which audiences a person sits inside'. It also provides when-not-to-use details: 'Takes a numeric user id ONLY, not a @handle: resolve a handle with twitter_user_info first' and warns about the cost of resolving a handle here. It also clarifies that an empty array is a successful answer, not a not-found, which prevents misinterpretation. These are strong usage guidelines.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses important behaviors: atomic application of changes, re-run of capacity and per-account cap checks on resume (adding load to shared pool), and that it's free per call. This adds valuable context not available 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Despite being information-dense, the description is compact and well-structured. It front-loads the core purpose, then adds critical behavioral notes (atomicity, resume checks, free) and finally clarifies optionality. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With four parameters (one required) and no output schema, the description covers all necessary aspects: what, how, when, and side effects. It explains the update semantics, the optional fields, and the resume behavior. It's complete for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description enhances parameter understanding beyond the schema. It explains that all three optional fields can be omitted to leave unchanged, clarifies how to clear restrictions (empty string for webhook_ids, empty string/null for domain_filter), and notes the domain_filter validation (400 if non-empty doesn't normalize). This goes well beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Partially update an existing monitor' with specific fields (status, webhook_ids, domain_filter) and the ability to combine changes atomically. This distinguishes it from siblings like twitter_monitor_create and twitter_monitor_delete, which are for creation and deletion respectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it: for updating an existing monitor, as opposed to creating or deleting. It also provides context about resuming a paused monitor triggering capacity checks. However, it doesn't explicitly mention alternatives or when not to use it, so it falls slightly 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the readOnlyHint annotation by detailing the reduced user object (no bio, follower counts, created_at), the interleaving of admins/moderators at arbitrary positions, and the pagination behavior (bare next_cursor, no total count, stop when members is empty or has_more is false). This provides critical behavioral context that annotations alone 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured, front-loading the core purpose and then providing necessary caveats and usage notes. Every sentence adds value, covering the row structure, reduced user object, role semantics, pagination behavior, and alternatives. It is appropriately sized for the complexity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (pagination, reduced user object, role semantics, interleaving), the description is complete. It covers the return structure, pagination termination conditions, and when to use alternative tools. The absence of an output schema is compensated by the detailed description of the row structure and user object fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% coverage with detailed descriptions for all three parameters, including defaults, clamping, and the meaning of cursor absence. The description adds value by explaining the pagination semantics (next_cursor, end-of-list signal) and the reduced user object, but the schema already covers the parameter basics well, so the description's additional contribution is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists the member roster of an X Community with cursor pagination, and specifies the exact row structure (user, role) and the reduced user object fields. It distinguishes itself from sibling tools like twitter_community_moderators and twitter_user_info by explicitly noting what it does not provide and what to use instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives: it notes that the role on a member row is not caller-relative and is returned in full, unlike the community object's role field, and explicitly warns against deriving a moderator list by filtering the first page, directing to twitter_community_moderators instead. It also explains when to use twitter_user_info for full profiles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/openWorldHint annotations, the description adds crucial behavioral detail: pinned posts are returned in a separate 'pinned' field, not repeated in 'tweets', so naive iteration silently loses them. It also warns that ranking_mode is an upstream parameter and that 'Relevance' is not confirmed live, which goes far beyond the schema and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but every sentence carries essential information: response shape, pinned-post pitfall, flat-list construction, ranking_mode semantics, and the alternative tool. The most important answer of 'what does this return and how do I handle it' is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description adequately defines the key response structure: the top-level 'pinned' field plus the 'tweets' array, and explains how to combine them without duplication. It also covers pagination, sorting caveats, and the principal alternative, so the agent has enough context to invoke and process results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has rich descriptions for all four parameters, so the description does not need to repeat them. It still adds meaningful parameter context by explaining that ranking_mode is a real upstream request parameter and cautioning that only 'Recency' is confirmed against a live capture, which helps the agent make safer invocation decisions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Starts by explicitly saying 'Read an X Community's own post timeline', which identifies the action, resource, and scope. It also distinguishes itself from search tools by emphasizing it returns the community's own feed, not cross-community results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Directly provides the alternative: 'Use twitter_advanced_search instead when the search should span all of X rather than one community.' This gives the agent a clear when-to-use versus when-not-to-use rule and explicitly names the sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds crucial transparency: idempotency (revoking twice returns ok with deleted=false), zero cost (works even out of balance), self-serve nature, scoping to own API key, and the limitation about not logging out of X. This goes beyond structured fields and does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but every sentence serves a purpose: action, result, side effects, and external behavior. It is well-structured with a clear front-loaded main statement. Slightly verbose due to the need to explain idempotency and external effects, but this is justified for a delete operation. Not overly long for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a session-deletion tool with side effects on other tools and external X account, the description covers all needed aspects: return behavior, cost, scope, idempotency, and the limitation regarding x.com cookies. The absence of an output schema is compensated by describing what the response looks like (deleted=false). This is complete for an agent to understand the full ramifications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is 100%. The description explicitly states 'it takes no account identifier of any kind' and explains why, which adds semantic meaning about the absence of parameters beyond the schema. This is valuable for an agent to understand that no input is needed and why.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool revokes an X account session and deletes stored credentials. It distinguishes from siblings like twitter_customer_session (which creates sessions) by explicitly mentioning it is the reverse operation. The verb 'revoke' is specific and the resource is well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use: after registering with twitter_customer_session. It also tells when not to rely solely on this tool (does not log out of x.com) and suggests additional action. The effect on other authenticated tools is clearly explained, making usage context unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it sends a real, non-silently reversible DM, which goes beyond the readOnlyHint=false annotation. It also reveals the need for residential proxy to avoid IP-based blocks, and notes that it returns message_id and conversation_id. No contradictions with annotations; adds actionable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that front-loads the primary action. Every clause serves a purpose: action, destination, prerequisite, proxy recommendation, return info, and irreversibility warning. No redundant fluff; well-structured for quick agent comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with auth and proxy requirements, the description covers all critical aspects: authentication, IP restrictions, parameter handling, and irreversibility. It also specifies the return fields, compensating for the lack of an output schema. Given the tool's complexity, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3, but the description enriches parameter meaning: it explains the necessity of numeric recipient_id and how to resolve handles, recommends proxy_url for reliability, and clarifies that text must be non-empty. These practical hints are not in the schema, adding significant value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: send a Direct Message as the authenticated account. It specifies the resource (DM) and distinguishes itself from sibling read tools like twitter_dm_list and twitter_dm_conversation. It also notes this is a real, irreversible action, setting it apart from other write tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit directives: resolve recipient_id via twitter_user_info, require authenticated session with write capability, and recommend residential proxy for reliability due to X's soft-blocking of datacenter IPs. It effectively tells the agent when and how to use the tool, including prerequisites and alternatives for handle resolution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by detailing return content ('each liked tweet with author and metrics, plus a pagination cursor'), ordering, and the behavioral quirk of returning empty if likes are hidden. Annotations already indicate readOnly, and description does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each with a distinct role: purpose, return details, and usage guidance. No redundant phrases; information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description sufficiently explains what is returned (tweets with author and metrics, cursor) and covers edge cases (hidden likes) and prerequisites. No additional information is needed for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds useful context: for 'count', it mentions the endpoint default; for 'cursor', it explains pagination; for 'user_id', it reinforces that numeric ID is required and directs to twitter_user_info for resolution.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'tweets a user has liked', and specifies ordering 'most recent first'. It distinguishes itself from sibling tools like twitter_user_tweets by focusing on likes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance ('infer interests or find content a user has endorsed') and a prerequisite ('Requires the numeric user_id; resolve a handle first with twitter_user_info'). It also notes the case where the account hides its likes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/TwitterAPIs/twitterapis-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server