This server provides read-oriented access to Twitter/X with limited low-risk write operations (liking/bookmarking), built-in anti-rate-limit protection, and cookie-based authentication.
Search & Discovery
Search tweets by query, sorted by "Top" or "Latest" (search_twitter)
Search for users by query (search_user)
Get trending topics (get_trends)
Tweet Operations
Fetch a tweet by ID (get_tweet_by_id)
Get detailed tweet information (get_tweet_details)
Get a full conversation thread (get_conversation_thread)
Find similar tweets (get_similar_tweets)
See who retweeted or liked a tweet (get_retweeters, get_favoriters)
Like or unlike a tweet (favorite_tweet, unfavorite_tweet)
Timelines & User Tweets
Browse "For You" or "Following" home timelines (get_timeline, get_latest_timeline)
Get tweets from a specific user (get_user_tweets)
Get highlighted or mentioned tweets for a user (get_highlights_tweets, get_user_mentions)
View scheduled tweets (get_scheduled_tweets)
User & Account Information
Get your authenticated user ID and profile (get_user_id, get_user)
Look up any user by screen name or ID (get_user_by_screen_name, get_user_by_id, get_user_profile)
Followers & Following (Read-Only)
List followers or following (get_user_followers, get_latest_followers, get_user_following, get_latest_friends)
Get verified followers, common followers, or subscriptions (get_user_verified_followers, get_user_followers_you_know, get_user_subscriptions)
Fetch follower/friend IDs in bulk (get_followers_ids, get_friends_ids)
Bookmarks
Retrieve bookmarks, paginated or all at once (get_bookmarks, get_all_bookmarks)
List bookmark folders (get_bookmark_folders)
Add or remove bookmarks, optionally in a folder (bookmark_tweet, delete_bookmark)
Direct Messages (Read-Only)
Read DM conversation history with a specific user (get_dm_history)
Miscellaneous
Fetch a community note by ID (get_community_note)
Notable Limitations
❌ No posting, deleting, or retweeting tweets
❌ No sending DMs or managing DM groups
❌ No follow/unfollow, block/unblock, or mute/unmute
❌ No account updates, media management, or poll voting
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@x-mcp-lite show my bookmarks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Safety-focused lite fork of lord-dubious/x-mcp.
Note on AI involvement: This fork was authored by Claude Code (Anthropic) under human direction. The human collaborator (
strobekiss) made all product decisions — scope of cuts, naming, design tradeoffs (in-memory vs SQLite, active cooldown vs passive sleep, retry vs no-retry on 429, cookie-based auth flow, set_proxy/sing-box integration, etc.) — and reviewed/verified the code at each step. Claude Code did the source reading, pattern analysis, and mechanical refactoring (commenting decorators, wrapping calls withwith_rate_limit, writing thethrottle.py/twikit_patch.py/singbox.pymodules). The anti-rate-limit design is informed by readingDataWhisker/x-mcp-server's official-API rate-limit module and adapting its "learn from real 429 + active intercept" pattern to twikit's reverse-engineered endpoints.
Keeps the read-only tools + bookmark/like management, cuts the high-risk write tools (post/delete tweets, DM, follow/block/mute, groups, cookie ops), and adds:
An anti-rate-limit layer the original project lacks entirely
twikit 2.3.3 patches for three upstream bugs it hasn't shipped fixes for: the KEY_BYTE indices breakage (x.com changed homepage HTML on 2026-03-18), KeyError crashes when parsing users whose accounts omit optional legacy.* fields (e.g. no bio link → KeyError: 'urls'), and KeyError: 'itemContent' in get_tweet_by_id from x.com's flattened cursor entries
A cookie-based auth flow (get_cookie) so the server can run on datacenter IPs without triggering Cloudflare blocks
This is an unofficial reverse-engineering library (via twikit) that talks to Twitter's internal endpoints. It is not affiliated with Twitter/X. Use of such libraries may violate Twitter's Terms of Service and can lead to:
Account being rate-limited (transient, recovers in ~15 min)
Account being locked (requires Arkose challenge / phone verification)
Account being suspended (permanent)
Use at your own risk. Recommendations:
Use a secondary account, not your main one
Keep call frequency low (the built-in throttler defaults to 2–5s random intervals)
Do not run unattended long-running jobs
If the account gets locked, stop and verify manually before resuming
Related MCP server: x-mcp
Category | Tools |
Bookmarks |
|
Tweet search/detail |
|
User info |
|
Follower/following lists |
|
Timeline/search |
|
DM read-only |
|
Retweeters/favoriters |
|
Community note |
|
Scheduled (read) |
|
Likes (low-risk write) |
|
Cookie setup |
|
@mcp.tool() decorators commented — function bodies retained for diff clarity)Post/delete tweets, polls, scheduled tweets, retweets, all DM write operations, all group operations, follow/unfollow/block/unblock/mute/unmute, set_delegate_account, update_user, all cookie management (get_cookies / save_cookies / set_cookies / load_cookies / logout / unlock), delete_all_bookmarks, geo (reverse_geocode / search_geo / get_place), media metadata, bookmark folder create/edit, vote / vote_on_poll.
src/x_mcp/
├── __init__.py
├── twikit_patch.py # Three twikit 2.3.3 monkey-patches, applied at import:
│ # - ClientTransaction.get_indices (2026-03-18 x.com
│ # HTML format change)
│ # - User.__init__ (KeyError on optional legacy.*
│ # fields x.com omits, e.g. no-bio-link accounts)
│ # - GQLClient.tweet_detail (KeyError itemContent from
│ # x.com's flattened cursor entries)
│ # Loaded BEFORE `import twikit` via twitter.py.
├── throttle.py # Anti-rate-limit layer (state persisted to
│ # ~/.x-mcp/throttle_state.json):
│ # - Throttler (2-5s random pacing, persisted)
│ # - with_rate_limit (rolling request budget +
│ # active cooldown + bounded 429 backoff/retry;
│ # distinct AccountLocked/Suspended handling;
│ # get_cookie hint on other TwitterException)
│ # - paginate_all (3-8s inter-page delay, budget-aware)
├── singbox.py # Archived: historical sing-box management module.
│ # No longer imported by twitter.py. Kept in the repo
│ # (and git history) as a record of the proxy/sing-box
│ # approach. See ARCHIVE.md for details.
└── twitter.py # 39 MCP tools, all wrapped with throttler.wait()
# + with_rate_limit(). get_twitter_client handles
# cookie loading / login.throttle.py)Throttler — random-pacing throttler. Every tool call awaits throttler.wait() first, which sleeps to enforce a 2–5s random interval since the last call. Randomization avoids fixed-pattern detection. The last-call timestamp is persisted, so pacing holds even when the host spawns the server fresh per call.
with_rate_limit(endpoint, fn) — DataWhisker-style active cooldown tracking, plus a request budget and bounded backoff. In order:
Rolling budget: if we've already made X_MCP_MAX_CALLS_PER_WINDOW calls (default 250) in the last 15 min, refuse with a clear "try again in Ns" error instead of adding fuel to a burst that could trip detection. Set to 0 to disable.
Active cooldown: if a previous 429 recorded a reset time for this endpoint, either sleep it out (if within X_MCP_MAX_BACKOFF) or refuse with a retry hint (if further out) — active intercept, no wasted request.
On TooManyRequests: read e.rate_limit_reset (from the x-rate-limit-reset response header, confirmed in twikit 2.3.3 errors.py), record it (persisted), then sleep + retry once only if the wait is within X_MCP_MAX_BACKOFF (default 60s); otherwise refuse with a retry hint. This caps in-call blocking so a single call can't hang for the full 900s window and blow past your MCP client's timeout — the cooldown is still honored on the next call.
On AccountLocked / AccountSuspended: convert to a RuntimeError that says re-cookieing won't help and the account must be fixed manually in a browser (no misleading get_cookie() hint).
On any other TwitterException subtype (BadRequest / Unauthorized / Forbidden / NotFound / etc): convert to RuntimeError with the short "Call get_cookie()" hint, do not retry.
paginate_all — for get_all_bookmarks. Iterates Result.next() with 3–8s random delay between pages; each page goes through with_rate_limit so the budget, cooldown and 429 backoff all apply, and any refusal cleanly stops pagination and returns what was collected so far. Default max_pages=50 (~1000 bookmarks).
Persistence: pacing (last_call), per-endpoint 429 cooldowns (resets), and the rolling request log (calls) are stored in a small JSON file (default ~/.x-mcp/throttle_state.json, override with X_MCP_STATE_PATH; atomic writes, tolerant of a missing/corrupt file). This is what lets a cooldown survive across per-session server spawns (e.g. mcphub over stdio), instead of being lost every time the process restarts.
Documented so you know what the layer still does not cover:
Budget/pacing count tool calls, not underlying HTTP requests. Some tools issue several requests internally (e.g. get_user does settings + get_user_by_screen_name + get_user_by_id) but count as one. The budget is a coarse safety cap, not an exact request meter.
No fingerprint hardening. The client uses twikit's default User-Agent unless you set USER_AGENT. If you exported cookies from a browser, setting USER_AGENT to match that browser is the most consistent choice.
get_user / get_user_id depend on a flaky endpoint. They call /1.1/account/settings.json, which x.com currently returns 404 for intermittently. This is an x.com/twikit issue, not a rate-limit one — retry, or use get_user_by_screen_name / get_bookmarks which don't hit that endpoint.
Concurrent writers race. The state file is best-effort: two servers running against the same file could lose an update. Fine for the normal single-host case.
twikit_patch.py)twikit_patch.py applies three independent monkey-patches at import time (must run before from twikit import Client). Remove each once twikit ships a release that fixes the corresponding bug.
1. ClientTransaction.get_indices — Couldn't get KEY_BYTE indices
twikit 2.3.3 raises this because x.com changed its homepage HTML on 2026-03-18 — the ondemand.s filename and its hash are now split into two separate ,<N>:"..." entries instead of one inline "ondemand.s":"<hash>". Upstream issue: d60/twikit#408. Fix is upstream in iSarabjitDhiman/XClientTransaction commit 2ff8438, but twikit hasn't pulled it in. Patched using the regex from @audioeng89's comment.
2. User.__init__ — KeyError on optional legacy.* fields
twikit 2.3.3's User.__init__ hard-indexes many optional legacy.* fields that x.com omits for some accounts, so any call that parses a User object crashes. Observed in the wild:
legacy['entities']['description']['urls'] for accounts with no link in their bio (x.com sends entities == {"description": {}}) → KeyError: 'urls'
legacy['withheld_in_countries'] → KeyError: 'withheld_in_countries'
This hit get_user, get_user_id, get_bookmarks, timelines, follower lists — anything returning users. Same class of bug as d60/twikit#341 (can_media_tag). Rather than whack-a-mole each field, the patch wraps the incoming data in a recursive lenient dict so a missing key at any depth degrades to an empty value instead of raising; present keys keep their real values, so normal accounts parse unchanged.
3. tweet_detail cursors — KeyError: 'itemContent'
twikit 2.3.3 reads reply/next-page cursors from the tweet-detail response at entries[-1]['content']['itemContent']['value'] and reply['item']['itemContent']['value'] (in Client.get_tweet_by_id and Client._get_more_replies). x.com flattened cursor entries — the value now sits directly on the cursor object ({'entryType': 'TimelineTimelineCursor', 'cursorType': ..., 'value': ...}) with no itemContent nesting → KeyError: 'itemContent'. This broke get_tweet_by_id, get_tweet_details, and get_conversation_thread. All the crash sites parse the response from GQLClient.tweet_detail, so the patch wraps that one method and re-nests each flattened cursor's value back under itemContent, leaving the original code unchanged.
x-mcp-lite previously supported HTTP/SOCKS5 proxies via X_MCP_PROXY/proxy= and local sing-box forwarding for trojan/anytls/ss/vmess nodes via set_proxy(). In practice, every tested proxy path was blocked by Cloudflare before login could succeed on the deployment machine (datacenter/VPS IP). The sing-box binary download and startup were eventually fixed, but the outbound nodes themselves could not reach x.com from the server environment.
To keep the auth surface simple and reliable, proxy support was removed. Only cookie-based auth remains. You generate cookies on a network that x.com trusts (e.g. a home browser or residential machine) and copy them to the MCP server. See ARCHIVE.md for the historical proxy/sing-box implementation.
git clone https://github.com/strobekiss/x-mcp-lite
cd x-mcp-lite{
"x-mcp-lite": {
"command": "uvx",
"args": ["--from", "git+https://github.com/strobekiss/x-mcp-lite", "x-mcp-lite"],
"env": {
"TWITTER_USERNAME": "your_username",
"TWITTER_PASSWORD": "your_password"
}
}
}Variable | Required | Default | Purpose |
| Yes¹ | — | X username (used by auto-login) |
| Yes¹ | — | X password (used by auto-login) |
| No | — | Email if your account has one; omitted if not set (twikit accepts |
| No |
| Path to cookies file. Set this on both the login machine and the deployment machine. |
| No | twikit default | Custom User-Agent. Recommended: match the browser you exported cookies from. |
| No | — | Capsolver API key (only needed if you hit Arkose challenges) |
| No |
| Where the throttle layer persists pacing / cooldowns / request log |
| No |
| Max seconds a single call will block waiting out a cooldown before it refuses with a retry hint (the cooldown is still persisted) |
| No |
| Client-side request budget per 15-min window. |
¹ Only required if you ever use get_cookie() Strategy 3 (auto-login). If you only ever paste cookies via get_cookie(cookie_json=...), credentials aren't needed.
The MCP server starts automatically when your MCP host launches. uvx will pull the latest code from GitHub on each startup.
This server only supports cookie-based auth. Proxy-based login was removed because Cloudflare blocks every proxy path we tested from datacenter/VPS IPs (residential proxies, datacenter proxies, trojan/vless nodes, etc.).
Credentials (TWITTER_USERNAME / TWITTER_PASSWORD) must be set in the MCP server env at startup — agents can't pass them at runtime (security: don't let LLMs handle plaintext passwords). They are only used when the server performs auto-login, which usually only makes sense from a residential/uncensored IP.
Use the get_cookie MCP tool. It picks a strategy based on what you pass:
Best when you already have cookies exported from a browser or received from another machine.
Use a browser extension (e.g. EditThisCookie) on x.com while logged in, export as JSON — OR — read the cookies file saved by another x-mcp-lite instance.
Call get_cookie(cookie_json="<the JSON string>").
Writes directly to X_MCP_COOKIES_PATH. Validates JSON is a non-empty object; atomic write (tmp + rename) won't corrupt an existing file.
Best when cookies are already saved somewhere on this machine.
Call get_cookie(cookie_file="/path/to/cookies.json").
Reads, validates, and atomically writes to X_MCP_COOKIES_PATH. Refuses if source equals target.
Best when you don't have cookies yet and the MCP server is running on a network that x.com trusts (e.g. home, office, or a VPN exit that x.com accepts).
Ensure TWITTER_USERNAME / TWITTER_PASSWORD are set in MCP server env.
Call get_cookie() with no args.
twikit logs in directly (no proxy), saves cookies to X_MCP_COOKIES_PATH.
If this fails with 403/ConnectTimeout, your server's IP is blocked — use Strategy 1 or 2 instead.
When an agent calls any tool (e.g. get_bookmarks) and cookies are missing/expired, the error message tells the agent to call get_cookie (one-line hint). The agent then either:
Asks the user to paste cookies from elsewhere (browser export or another machine) and calls get_cookie(cookie_json="<JSON>")
Asks the user to copy a local cookies file and calls get_cookie(cookie_file="<path>")
Asks the user to restart the MCP server with TWITTER_USERNAME / TWITTER_PASSWORD on a trusted network and calls get_cookie()
Cookies live at X_MCP_COOKIES_PATH (default ~/.x-mcp/cookies.json). To deploy to another machine:
Copy the cookies file to that machine.
Set X_MCP_COOKIES_PATH to its absolute path there.
No proxy is needed — cookies are reused without proxy.
If cookies later expire (Twitter requires re-verification), API calls fail with AccountLocked or Unauthorized. Re-run get_cookie to refresh.
get_cookie call)If you skip the get_cookie flow entirely, the server will attempt auto-login on first run with TWITTER_USERNAME / TWITTER_PASSWORD and save cookies to ~/.x-mcp/cookies.json. This works if the server's IP can reach x.com (residential or trusted VPN); fails with 403 on blocked datacenter IPs — use the cookie flow above for server deployments.
Couldn't get KEY_BYTE indicesThis means the twikit patch isn't loaded. Check that twikit_patch.py is in src/x_mcp/ and that twitter.py imports it before import twikit:
from . import twikit_patch # noqa: F401 must run before `import twikit`
import twikitForbidden (403) or NotFound (404 "page does not exist") on loginThe server's IP is blocked by Cloudflare. x-mcp-lite no longer supports proxy-based login (see ARCHIVE.md for the historical reason). Generate cookies on a network that x.com trusts (home, office, or a VPN exit that x.com accepts) and deploy them via get_cookie(cookie_json=...) or get_cookie(cookie_file=...).
Unauthorized (401) on API callsCookies are missing or expired. Call get_cookie() to refresh (see Cookie setup above).
Account locked (Arkose challenge) / Account suspendedThe account got flagged by Twitter's anti-automation. Re-cookieing will not help. Stop all automated calls, log into x.com in a browser, complete the challenge (locked) or appeal (suspended), then — only for a lock — re-run get_cookie to refresh cookies.
Client-side request budget exceededYou've hit the built-in safety cap (X_MCP_MAX_CALLS_PER_WINDOW, default 250 calls / 15 min). Wait the stated number of seconds, or raise/disable the cap via the env var. This is a client-side guard, not an X rate limit.
... is rate-limited; cooldown ends in NsX returned a 429 and the reset is further out than X_MCP_MAX_BACKOFF (default 60s), so the call refused instead of blocking. The cooldown is persisted (X_MCP_STATE_PATH) and honored automatically — just retry after the stated time. Raise X_MCP_MAX_BACKOFF if you'd rather have calls block and auto-retry.
KeyError: 'urls' / KeyError while reading users or bookmarksFixed by the User.__init__ patch in twikit_patch.py (see twikit patches). If you still see it, the patch isn't loaded — confirm twitter.py imports twikit_patch before import twikit.
get_user / get_user_id return NotFound (404 "page does not exist")These go through /1.1/account/settings.json, which x.com returns 404 for intermittently. It's not a rate-limit or cookie problem — retry, or use get_user_by_screen_name / get_bookmarks, which don't hit that endpoint.
MIT, inherited from the upstream project.
Adds the tweet to bookmarks.
| Name | Required | Description | Default |
|---|---|---|---|
| tweet_id | Yes | ||
| folder_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states a write operation but gives no details on side effects, duplicates, error behavior, or authentication needs. Minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no extra words, but it is under-specified. Efficiency is neutral without enough information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 parameters, no annotations, and an output schema not described, the description is too terse. It fails to explain the optional folder_id or return value, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds no meaning to parameters. 'folder_id' is not explained, leaving its purpose ambiguous. The description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Adds' and identifies the resource 'tweet' and destination 'bookmarks', clearly distinguishing it from siblings like 'delete_bookmark' and 'get_bookmarks'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives, no prerequisites, and no context on when not to use it. Siblings cover similar actions without differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Removes the tweet from bookmarks.
| Name | Required | Description | Default |
|---|---|---|---|
| tweet_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits, but it only states the action. It does not mention side effects (e.g., irreversibility), error cases (e.g., if tweet is not bookmarked), authentication requirements, or any constraints, leaving the agent underinformed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core action. However, it sacrifices necessary detail for brevity, so it does not achieve a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description could be minimal but still misses essential behavioral details (e.g., what happens on failure). No edge cases or usage context are covered, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description adds no meaning for the sole parameter 'tweet_id'. It is just listed as a required string with no format, source, or usage context, forcing the agent to guess.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Removes the tweet') and the resource ('bookmarks'), making it unambiguous. It effectively distinguishes from sibling tools like bookmark_tweet (adds) and get_all_bookmarks (reads).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit guidance on when to use this tool versus alternatives. While the purpose is clear, no scenarios, prerequisites, or when-not-to-use information is provided, which would help with selection among many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Favorites a tweet.
| Name | Required | Description | Default |
|---|---|---|---|
| tweet_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided and the description does not disclose behavioral traits such as idempotency, authentication needs, or side effects like duplicate favoriting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is concise, though it could benefit from structured formatting for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimally adequate for a simple action, but lacks details on behavior and return value, though an output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no meaning beyond the input schema; the single parameter 'tweet_id' is undefined and schema description coverage is 0%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Favorites a tweet' uses a specific verb and resource, clearly distinguishing it from siblings like 'unfavorite_tweet' and 'bookmark_tweet'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., bookmark_tweet, unfavorite_tweet) or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read all bookmarks by paginating until end or max_pages reached.
Built-in anti-rate-limit: 3-8s random delay between pages, 429 auto-backoff. Returns markdown of all collected tweets.
| Name | Required | Description | Default |
|---|---|---|---|
| folder_id | No | ||
| max_pages | No | ||
| page_size | No | ||
| page_delay_range | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses anti-rate-limit behavior (random delay, 429 back-off) and return format (markdown). Lacks details on error handling or auth needs but is generally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no redundant words. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are documented. Description covers pagination end condition and anti-rate-limit, but omits error scenarios and folder_id filtering behavior. Adequate but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explains max_pages (default 200) and page_delay_range (3-8s via anti-rate-limit), but folder_id and page_size are not described. Partial but insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads all bookmarks via pagination, with a specific verb 'Read' and resource 'all bookmarks'. It distinguishes from siblings like 'get_bookmarks' by implying full pagination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing all bookmarks, but does not explicitly compare to alternatives like 'get_bookmarks' or state when not to use. No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves bookmark folders.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description fails to disclose behavioral traits such as authentication requirements, rate limits, pagination behavior, or whether the tool is read-only. The cursor parameter suggests pagination but is not explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (3 words), but this is under-specification rather than conciseness. It lacks necessary details and does not earn its place as a complete description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema and the cursor parameter, the description is severely incomplete. It does not explain what the tool returns, how pagination works, or how to interpret results. The minimal description is inadequate for an AI agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for the 'cursor' parameter. The description adds no meaning beyond the schema itself, leaving the parameter's purpose and usage entirely unspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description 'Retrieves bookmark folders' is essentially a tautology of the tool name. It states the action and resource but does not differentiate from siblings like 'get_bookmarks' or 'get_all_bookmarks', which could easily be confused.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives such as 'get_bookmarks' or 'get_all_bookmarks'. There is no mention of context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves bookmarks from the authenticated user’s Twitter account.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| cursor | No | ||
| folder_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description is minimal. Does not disclose pagination behavior, rate limits, or authentication requirements beyond implicit mention. Falls short for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but under-specified. It's not verbose, but it lacks essential details, making it less than optimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 3 parameters, no annotations, and an output schema not described. Description fails to cover parameter semantics or return value context, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and description does not explain any of the three parameters (count, cursor, folder_id). No addition beyond schema's bare structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it retrieves bookmarks from the authenticated user's account. Specific verb and resource, distinct from sibling tools like bookmark_tweet or delete_bookmark.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives such as get_all_bookmarks or other retrieval tools. No context on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches a community note by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose any behavioral traits such as authentication needs, rate limits, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no filler; front-loaded with the essential action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists but description does not explain what a community note is or what the response contains; adequate for a simple tool but lacks completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%; description only hints that note_id is an identifier but adds no additional guidance on format or expected values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Verb 'Fetches' + resource 'community note' + method 'by ID' clearly states the action and differentiates it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like searching for notes or retrieving other resources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full conversation thread for a tweet.
| Name | Required | Description | Default |
|---|---|---|---|
| tweet_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It does not mention any behavioral traits such as authentication requirements, rate limits, or what constitutes a 'full conversation'. The description adds no behavioral insight beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that efficiently states the tool's purpose. It is front-loaded and avoids unnecessary words. However, the brevity comes at the cost of missing important details, balancing conciseness against completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one required parameter, no annotations, and an expected output schema (not described), the description is insufficient. It lacks context about output structure, edge cases (e.g., what if tweet has no thread), and relationship to sibling tools. The description is not complete enough for an agent to use without additional assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the parameter 'tweet_id' has no description in the schema. The tool description does not explain the parameter's format, source, or constraints. While the parameter name is self-explanatory, the description fails to compensate for the missing schema descriptions, leaving the agent without guidance on proper input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and identifies the resource as 'the full conversation thread for a tweet', clearly indicating the tool's function. It distinguishes from siblings like 'get_tweet_by_id' (single tweet) and 'get_timeline' (timeline of tweets). However, it does not specify the exact scope of 'full conversation thread' (e.g., depth or inclusion of replies), which slightly reduces clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. Given the sibling list includes many tweet retrieval tools (e.g., 'get_tweet_by_id', 'get_tweet_details', 'get_timeline'), the absence of usage context or when-not-to-use instructions is a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the DM conversation history with a specific user.
| Name | Required | Description | Default |
|---|---|---|---|
| max_id | No | ||
| user_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It does not mention authentication requirements, rate limits, pagination behavior (e.g., use of max_id), or whether the conversation is returned in full or partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is too brief to be useful. It under-specifies the tool's behavior and parameters, making it more incomplete than concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists, the description does not mention what data is returned (e.g., messages, metadata). For a tool retrieving conversation history, essential context such as pagination support and result structure is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage. The description does not explain the purpose of 'max_id' (likely a pagination cursor) or clarify that 'user_id' is required. No additional meaning is added beyond the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'retrieves' and the resource 'DM conversation history with a specific user'. It is distinct from all sibling tools, which are focused on tweets, bookmarks, and user profiles, not DMs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or context for usage. It simply states the action taken.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve users who favorited a specific tweet.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| cursor | No | ||
| tweet_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states 'retrieve', implying read-only, but does not mention pagination via cursor, rate limits, or any other behavioral traits beyond the bare minimum.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, front-loading the essential purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters with zero schema descriptions and no behavioral annotations, the description is insufficiently complete. It does not address pagination, default behavior, or how to interpret results despite having a reasonable number of siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to the parameters (tweet_id, count, cursor). It does not explain what each parameter does or how to use them, leaving the agent entirely reliant on the schema names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve'), the resource ('users who favorited'), and the specificity ('a specific tweet'), distinguishing it from siblings like get_retweeters or get_followers_ids.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing a list of users who favorited a tweet but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches the IDs of the followers of a specified user.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| cursor | No | ||
| user_id | No | ||
| screen_name | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral disclosure burden. It only states it fetches IDs, but omits pagination behavior (cursor, count), authentication needs, rate limits, or how multiple user identifiers are handled. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence (10 words) that front-loads the action. It is appropriately sized but could benefit from slightly more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description lacks essential context about parameters (4 with 0% schema coverage) and does not differentiate from numerous sibling tools. The agent is left to infer usage patterns, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds zero information about the parameters (count, cursor, user_id, screen_name). It does not explain how to specify a user, what count does, or how cursor works, leaving the agent without necessary usage details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetches') and the resource ('IDs of the followers of a specified user'). However, it does not distinguish from sibling tools like get_user_followers (which returns full objects) or get_latest_followers, missing an opportunity for differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., get_user_followers, get_friends_ids). No prerequisites, limitations, or context for choosing this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches the IDs of the friends (following users) of a specified user.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| cursor | No | ||
| user_id | No | ||
| screen_name | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It does not disclose pagination behavior, authentication requirements, rate limits, or what happens if both user_id and screen_name are provided. Simply states it fetches IDs, which is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no fluff, front-loading the core purpose. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered elsewhere. However, the description lacks details on parameter usage and pagination, which are important for execution. It adequately states the basic purpose but is not complete for a 4-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It mentions 'of a specified user' but does not explain the parameters (count, cursor, user_id, screen_name), their defaults, or how to specify the user. No parameter details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetches' and the resource 'IDs of the friends (following users) of a specified user.' It specifies the scope (by user) and differentiates from sibling tools like get_followers_ids by focusing on friends (following) rather than followers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as get_user_following (which may return full objects) or when not to use it. No exclusions or context for choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves highlighted tweets from a user’s timeline.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| cursor | No | ||
| user_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only states it retrieves data, implying a read operation, but lacks details on authentication, rate limits, pagination (cursor usage), or what 'highlighted' means. Minimal 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but lacks structure. It front-loads the purpose but omits parameter details and usage guidance, making it too terse to be fully helpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no schema descriptions, no annotations, and sibling tools, the description is severely incomplete. It fails to explain pagination, the meaning of 'highlighted,' output details (despite an output schema), or how to differentiate from similar tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to the parameters (count, cursor, user_id). The agent must rely solely on parameter names and defaults, which is insufficient for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves highlighted tweets from a user's timeline, specifying the verb and resource. However, it does not differentiate this from sibling tools like get_timeline or get_user_tweets, which also retrieve tweets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. No conditions, prerequisites, or exclusions are mentioned, leaving the agent to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the latest followers.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| cursor | No | ||
| user_id | No | ||
| screen_name | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose any behavioral traits (e.g., pagination, rate limits, authentication). With no annotations, this is a significant gap for a data retrieval tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise but at the expense of useful information. Every sentence should earn its place; this one sentence lacks specificity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description fails to explain the tool's purpose, parameter usage, or output structure. Inadequate for a tool with zero annotation coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not explain any of the four parameters (count, cursor, user_id, screen_name). The agent cannot determine how to use them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Retrieves the latest followers' states a verb and resource, but 'latest' is ambiguous and does not differentiate from siblings like get_user_followers or get_latest_friends.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as get_user_followers or get_followers_ids. No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the latest friends (following users).
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| cursor | No | ||
| user_id | No | ||
| screen_name | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and a minimal description, behavioral traits like pagination, rate limits, authentication needs, or default behavior for missing parameters are not disclosed. The description adds little beyond the bare action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but lacks any structure. It is minimally viable with no unnecessary words, but also no informative organization.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four parameters and no annotations, the description is too sparse. It does not cover pagination, filtering, or output format context, even though an output schema exists. The agent lacks sufficient information to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the four parameters (count, cursor, user_id, screen_name). This is a critical gap, as the agent cannot understand parameter purpose or valid values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Retrieves the latest friends (following users)', which identifies the verb and resource. However, it does not differentiate from sibling tools like get_user_following or get_latest_followers, leaving ambiguity about what 'latest' means and how this tool is unique.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives, such as get_user_following or get_latest_followers. There is also no mention of prerequisites or context for effective use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tweets from your home timeline (Following). Takes count (default: 20), seen_tweet_ids (optional), and cursor (optional)
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| cursor | No | ||
| seen_tweet_ids | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behaviors like pagination, rate limits, or deduplication logic. It only mentions parameters tersely (count, seen_tweet_ids, cursor) without explaining their behavior or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded. However, it is so brief that it sacrifices useful details, making it only adequately concise but not well-structured with explanatory sections.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the context of social media timeline fetching, the description lacks information on pagination, ordering, deduplication, and rate limits. While an output schema exists, the description is insufficient for proper usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It lists parameter names and defaults/optionality but does not explain what 'cursor' or 'seen_tweet_ids' do, missing the opportunity to add meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets tweets from the user's home timeline (Following), which is a specific verb and resource. However, it does not explicitly differentiate from sibling tool 'get_timeline', which likely serves a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'get_timeline' or 'get_user_tweets'. The description does not mention prerequisites, limitations, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve users who retweeted a specific tweet.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| cursor | No | ||
| tweet_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states 'retrieve', implying a read operation. There is no disclosure of behavior like pagination (despite cursor parameter), rate limits, or error handling. The description does not add value beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence) and front-loaded, but it omits important details. It earns its place for brevity but sacrifices completeness, making it minimally adequate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description does not describe the return format or pagination behavior. With no annotations and low schema coverage, the description leaves significant gaps in understanding the tool's usage and behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the three parameters (tweet_id, count, cursor). It fails to add meaning beyond the input schema, leaving the agent without guidance on how to use the parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves users who retweeted a specific tweet, specifying the verb 'retrieve' and the resource. It is distinct from siblings like get_favoriters or get_followers, though no explicit differentiation is provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives, such as get_favoriters for likes or get_followers for follow relationships. There is no mention of prerequisites or context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves scheduled tweets.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only says 'Retrieves scheduled tweets' without disclosing behavior like pagination, auth requirements, rate limits, or what it returns. Leaves critical gaps for a mutation-less tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, complete sentence with no wasted words. It is front-loaded and efficiently conveys the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an existing output schema, the description provides the basic purpose. However, it lacks context about what 'scheduled' means (e.g., time-based, user-specific), and doesn't indicate if there are any limitations or prerequisites. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100% (empty schema). Description adds no additional meaning beyond the schema, achieving baseline adequacy. Could have explained the tool's scope or output structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves scheduled tweets, using a specific verb and resource. However, with 37 sibling tools, it doesn't differentiate itself from similar tools like get_timeline or get_user_tweets, lacking specificity about what 'scheduled tweets' entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No context about prerequisites, whether it's for a specific user, or how it differs from other tweet retrieval tools. Fails to help the agent select appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves tweets similar to the specified tweet (Twitter premium only).
| Name | Required | Description | Default |
|---|---|---|---|
| tweet_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only mentions the action and a condition, without discussing authentication, rate limits, or other effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (not shown), the description is minimally adequate but could be enhanced with additional context like result count or ordering.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds no detail about the tweet_id parameter beyond what the name implies. It does not clarify format or requirements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieves') and the resource ('tweets similar to the specified tweet'), distinguishing it from sibling tools like get_tweet_by_id or search_twitter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finding similar tweets and includes a constraint ('Twitter premium only'), but lacks explicit guidance on when to use or not use alternatives. The tool is unique among siblings, so the constraint is useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tweets from your home timeline (For You). Takes count (default: 20), seen_tweet_ids (optional), and cursor (optional)
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| cursor | No | ||
| seen_tweet_ids | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It only states 'Get tweets', implying a read operation, but fails to disclose behavioral traits such as authentication requirements, rate limits, or how parameters affect behavior beyond defaults.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loading the main action and listing parameters. It is reasonably concise but omits important details about parameter usage, which could be efficiently included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the presence of an output schema, the description lacks critical context for a timeline tool, such as how cursor pagination works and the purpose of seen_tweet_ids. Without these details, an agent cannot use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning beyond the schema. It lists parameter names and the default for count, but does not explain the role of cursor (pagination) or seen_tweet_ids (deduplication), providing minimal value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets tweets from the home timeline with the qualifier 'For You', indicating the algorithmic feed. However, it does not differentiate from sibling tools like get_latest_timeline or get_highlights_tweets, which serve similar purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus alternatives. No prerequisites, when-not-to-use, or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get trending topics on Twitter. Takes category (default: trending) and count (default: 20)
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| retry | No | ||
| category | No | trending | |
| additional_request_params | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description bears full responsibility. It only states it 'gets' data (read operation) but does not disclose authentication needs, rate limits, pagination, or side effects. Parameters like retry and additional_request_params are not explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences. However, it sacrifices completeness for brevity, missing details on parameters and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, the description need not detail return values. Still, for a tool with four parameters (including a complex anyOf), the description is insufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description only clarifies two of four parameters (category and count). It ignores retry and additional_request_params, leaving their purpose opaque.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get trending topics on Twitter' which is a specific verb and resource. It distinguishes itself from sibling tools like get_timeline or search_twitter by focusing on trending topics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention that for other types of content (e.g., user tweets), other sibling tools should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches a tweet by tweet ID.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | ||
| tweet_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'Fetches', omitting critical details like authentication requirements, rate limits, error handling (e.g., tweet not found), or the role of the 'cursor' parameter. The agent is left without essential 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loading the core action. However, it achieves conciseness at the expense of necessary details, making it too brief to be fully helpful. It earns a middle score for being clear but inadequate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (not shown), return values are less of a concern. However, with 2 parameters, no annotations, and many sibling tools (e.g., get_tweet_details), the description lacks completeness by not explaining cursor usage or distinguishing from similar tools. The agent is under-informed for correct invocation and selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description adds no parameter-level explanations. While 'tweet_id' is self-explanatory, 'cursor' (optional, string/null) is undocumented, leaving its purpose (likely pagination) unclear. The description fails to compensate for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetches' and the resource 'a tweet by tweet ID', making the tool's purpose unambiguous. It distinguishes from sibling tools like search_twitter or get_timeline, though get_tweet_details might overlap; still, the purpose is specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus siblings like get_tweet_details or search_twitter. The description does not mention prerequisites, fallbacks, or when not to use it, leaving the agent guessing about appropriate contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific tweet.
| Name | Required | Description | Default |
|---|---|---|---|
| tweet_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits like read-only status, side effects, or what 'detailed information' entails. This leaves the agent without essential context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded, but it sacrifices necessary detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description does not elaborate on what 'detailed information' includes, leaving a significant gap in completeness for an information retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'tweet_id' is not explained beyond its type and requirement. With 0% schema description coverage, the description should add meaning but does not clarify what format or scope the ID expects.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (get) and resource (tweet), and specifies 'detailed information about a specific tweet'. However, it does not differentiate from sibling tools like get_tweet_by_id, which may also retrieve tweet details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as get_tweet_by_id or get_conversation_thread. The agent is left without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve detailed information about the authenticated user.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It implies a read-only operation without side effects, but does not disclose potential rate limits, authentication requirements, or behavior on error. The minimal disclosure is adequate for a simple retrieval.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-constructed sentence that front-loads the action and resource. Every word adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description is complete enough. It does not explain the output shape, but the output schema handles that. The description could mention typical use cases (e.g., verifying identity) but is not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. The description adds no parameter-specific information, which is acceptable given zero parameters. Baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve') and the resource ('detailed information about the authenticated user'). It effectively distinguishes from sibling tools like 'get_user_by_id' or 'get_user_profile' by specifying 'authenticated user', though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the many sibling tools (e.g., get_user_by_id, get_user_by_screen_name). The agent receives no information about context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches a user by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It only states 'Fetches a user by ID' without indicating read-only nature, return structure, or any side effects. Output schema exists but is not referenced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no waste, but it is under-specified for the tool's role. Conciseness is good, but at the cost of missing critical details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description still lacks sufficient context about what is returned or how the user ID is expected to be formatted. Does not stand alone for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, leaving the description to explain parameters. The description merely repeats the parameter name's implication ('by ID'), adding no format, constraints, or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Fetches' and resource 'user' with method 'by ID'. It distinguishes from siblings like get_user_by_screen_name by specifying the lookup key, but does not explicitly differentiate from get_user or get_user_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like get_user_by_screen_name or get_user. No context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches a user by screen name.
| Name | Required | Description | Default |
|---|---|---|---|
| screen_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits like read-only nature, authentication requirements, or error handling. It only states the basic operation, leaving agents uninformed about side effects or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence. It is front-loaded and efficient, though it could be slightly expanded to improve completeness without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (fetch by one param) and the presence of an output schema, the description is minimally adequate. However, it lacks context about edge cases (e.g., non-existent user) and any caveats, which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description does not elaborate on the parameters. The single parameter 'screen_name' is only mentioned implicitly ('by screen name') and adds no additional meaning (e.g., format, case sensitivity).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('fetches') and the resource ('user by screen name'), differentiating it from siblings like 'get_user_by_id' which use a different identifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'get_user_by_id' or 'search_user'. The description lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves a list of followers for a given user.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| cursor | No | ||
| user_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose pagination behavior, authentication requirements, rate limits, or data shape beyond 'list of followers'. With an output schema present, more detail would be expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence with no wasted words. It is appropriately sized for a simple retrieval tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the three parameters, zero param descriptions, and an output schema (unseen), the description is incomplete. It does not explain pagination or how parameters control the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no extra meaning to parameters like 'count', 'cursor', or 'user_id'. The description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (retrieves) and resource (list of followers) for a given user. However, it does not differentiate from sibling tools like 'get_followers_ids' or 'get_latest_followers'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'get_followers_ids' or 'get_latest_followers'. The description lacks usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves a list of common followers.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| cursor | No | ||
| user_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'Retrieves a list of common followers' with no details on authentication, rate limits, pagination behavior (despite cursor parameter), or what happens when user_id is invalid. The tool's behavior is mostly opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, but it is under-specified. It sacrifices necessary details for brevity, making it less useful than it could be. A good structure would front-load key information but still cover essentials.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters (including pagination) and no sibling differentiation, the description is incomplete. It does not explain the concept of 'common followers', the role of 'count' and 'cursor', or the required nature of 'user_id'. An output schema exists but does not compensate for missing behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain any of the three parameters (user_id, count, cursor). Users must infer their meanings from names alone, which is insufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool retrieves a list of 'common followers', which distinguishes it from 'get_user_followers' that retrieves all followers. However, 'common' is ambiguous—it likely means common with the authenticated user, but this is not explicitly stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'get_user_followers', 'get_latest_followers', or 'get_followers_ids'. The description does not specify when this tool is appropriate or when to use other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves a list of users whom the given user is following.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| cursor | No | ||
| user_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must carry the full burden. It fails to disclose any behavioral traits such as pagination behavior, authentication requirements, or any constraints like only public follows. The output schema exists but is not described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded. However, it is too brief and lacks necessary detail, failing to earn its keep by providing valuable information beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 parameters, output schema, no annotations), the description is incomplete. It does not cover pagination, parameter semantics, or behavioral details. The output schema exists but is not leveraged in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description must compensate. It does not explain the count parameter (default 20), cursor for pagination, or the required user_id. No additional meaning is added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieves' and the resource 'list of users whom the given user is following'. It accurately distinguishes from sibling tools like 'get_user_followers' which retrieves followers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. There is no mention of pagination, rate limits, or prerequisites. The description only states what it does, not when to choose it over similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the user ID associated with the authenticated account.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the purpose, omitting behavioral details such as authentication requirements, read-only nature, or return type.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words, directly stating the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple, the description lacks mention of output format or authentication. An output schema exists, but additional context about the read-only nature would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema coverage is 100%, so the description does not need to add parameter details. Baseline is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'retrieves' and the resource 'user ID associated with the authenticated account', which is specific and distinguishes it from sibling tools like get_user_by_id or get_user_by_screen_name that require explicit identifiers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for authenticated user ID, but does not explicitly state when to avoid or mention alternatives like get_user_by_id for specific users.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tweets mentioning a specific user.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| cursor | No | ||
| user_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It fails to mention any behavioral traits such as authentication requirements, rate limits, pagination behavior (despite having a cursor parameter), or the structure of the output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence), which is efficient, but it sacrifices necessary detail. It is front-loaded with the core purpose but lacks supporting context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of a cursor parameter for pagination and many sibling tools, the description is incomplete. It does not clarify the scope of mentions (e.g., recency), pagination semantics, or how to interpret results. The output schema may compensate, but the description itself is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain parameters. It only implies user_id via 'specific user', but gives no information about count or cursor (e.g., default values, format, null handling). The agent has no guidance on parameter usage beyond the schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get tweets mentioning a specific user' succinctly states the action (get) and object (tweets mentioning a user), clearly distinguishing it from sibling tools like get_user_tweets (tweets by user) or get_tweet_by_id (single tweet). It 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description implies this tool is for mentions versus other tweet retrieval tools, it provides no explicit guidance on when to use it over alternatives (e.g., for recent mentions, with pagination). No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed profile information for a user
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It implies a read-only operation but provides no details on authentication, rate limits, or any side effects. The minimal description adds little beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence, very concise. However, conciseness comes at the cost of completeness; it could be slightly expanded to include parameter context or usage notes without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of multiple sibling tools and no annotations, the description is insufficient. It does not clarify the output format (though an output schema exists) or the exact identifier expected (e.g., numeric ID vs screen name). The agent may misinterpret the tool's purpose or input.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate by explaining the single parameter 'user_id'. However, it only mentions 'for a user' without specifying required format, type, or meaning. This leaves the agent without sufficient context to populate the parameter correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get detailed profile information for a user' clearly specifies the action (get) and resource (profile information), but does not differentiate from siblings like 'get_user' or 'get_user_by_id'. While the core purpose is evident, the lack of specificity about what 'detailed' entails leaves ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'get_user', 'get_user_by_id', or 'get_user_by_screen_name'. The description does not mention use cases, prerequisites, or conditions, making it difficult for an agent to choose correctly among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves a list of users to which the specified user is subscribed.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| cursor | No | ||
| user_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read operation but lacks details on pagination (despite count and cursor parameters), rate limits, authentication, or output structure. No annotations exist to supplement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff, but it is too brief and omits essential information. Conciseness is not a virtue when it sacrifices clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no param explanations, and an output schema not described, the description is incomplete. It does not address pagination, result format, or how this tool differs from similar siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage), and the description does not explain any parameter. Users are left to infer the meaning of count and cursor from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a list of users a user is subscribed to. However, it does not differentiate from the sibling tool get_user_following, which likely serves the same purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_user_following or get_user_followers. The description is purely functional.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tweets from a specific user's timeline. Takes user_id, tweet_type (default: Tweets), count (default: 40), and cursor (optional)
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| cursor | No | ||
| user_id | Yes | ||
| tweet_type | No | Tweets |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description bears full responsibility. It does not disclose behavioral traits like authentication needs, rate limits, sorting order, inclusion of retweets, or pagination behavior beyond noting cursor is optional. This leaves significant gaps 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, efficiently listing purpose and parameters. It is concise with no wasted words. However, the structure could be improved by front-loading behavioral context before parameter details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters and no annotations, the description is too sparse. It omits prerequisites, authorization context, and pagination details beyond cursor. While an output schema exists (reducing need to describe returns), the description still lacks completeness 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must add meaning. It lists parameters with defaults (e.g., tweet_type default 'Tweets'), but does not explain possible values for tweet_type or cursor format. It largely repeats schema information without adding semantic context, making it minimally helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get tweets from a specific user's timeline', specifying the verb 'get' and resource 'user's timeline'. Among siblings like 'get_user_mentions' and 'get_timeline', it distinguishes by targeting a specific user's tweets. Could be clearer by contrasting with 'get_timeline' but overall specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. No mention of when not to use it or prerequisites. Sibling tools include many user-tweet related functions, but the description provides no conditions or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves a list of verified followers for a given user.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| cursor | No | ||
| user_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description bears full burden. Does not disclose pagination behavior, what 'verified' means, authentication needs, or rate limits. Minimal 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise (one sentence), but may be too brief given the tool's complexity. Could include hints about pagination or filtering.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description lacks completeness for a tool with many siblings and 3 parameters. Missing explanation of pagination and count behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% parameter description coverage, and description adds no semantics. Does not explain 'count', 'cursor', or how they affect the output. User_id is implied but not elaborated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly uses verb 'Retrieves' and specifies resource 'list of verified followers for a given user'. Differentiates from sibling tools like 'get_user_followers' by including 'verified'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidelines provided on when to use this tool versus alternatives like 'get_user_followers' or 'get_latest_followers'. Lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search twitter with a query. Sort by 'Top' or 'Latest'
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| query | Yes | ||
| cursor | No | ||
| product | No | Top |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full burden. It does not disclose pagination (cursor), count limits, or any behavioral traits beyond sorting. Minimal insight into tool behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. Appropriate length but missing important details that would justify a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered, but the description lacks essential details like pagination, count meaning, and query syntax. For a search tool, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It only explains 'query' and sort options (Top/Latest), but the parameter is named 'product', not 'sort', causing potential confusion. 'count' and 'cursor' are not explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Search twitter with a query' which is a clear verb+resource. It also mentions sort options. However, it does not explicitly state that it searches for tweets, which could be inferred from context but is not as precise as possible given sibling tools like search_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like get_timeline or search_user. The description does not provide any usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches for users based on the provided query.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| query | Yes | ||
| cursor | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states 'Searches for users' but does not reveal whether authentication is needed, if mutation occurs, or any side effects. The behavior beyond the name is opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (one sentence) but front-loaded with the core action. However, it lacks essential details, making it under-specified rather than appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, a simple schema with three parameters, and sibling tools that overlap, the description is insufficient. It omits search behavior, pagination (cursor, count), and return format. An output schema exists but its contents are not addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only mentions 'query'. It does not explain the meaning of 'count' or 'cursor', nor how they affect the search. The description adds no value beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches for users based on a query. The verb 'searches' and resource 'users' are specific, and it distinguishes from sibling tools like search_twitter (tweets) and get_user (specific user lookup). However, it lacks details on search scope or matching criteria.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_user_by_screen_name or get_user_by_id. The description does not indicate prerequisites or scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unfavorites a tweet.
| Name | Required | Description | Default |
|---|---|---|---|
| tweet_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a mutation (unfavorites) but provides no details on side effects, authentication requirements, error conditions (e.g., if tweet not favorited), or rate limits. Since no annotations exist, the description carries the full burden and does not disclose behavioral traits beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no fluff. It is front-loaded and efficient, though slightly under-specified. The conciseness is appropriate for a simple tool, earning a high score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema (which need not be described), the description is minimally complete. It conveys essential purpose but lacks behavioral details and usage context that would fully inform an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and one required parameter (tweet_id), the description fails to mention or explain the parameter at all. The agent receives no additional meaning beyond the schema's type and requirement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Unfavorites a tweet' uses a specific verb and resource, clearly indicating the action and object. It is different from sibling tools like 'favorite_tweet' and 'bookmark_tweet', which have distinct verbs and targets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a user wants to remove a favorite from a tweet, but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternative tools. Usage is clear from context but not formally explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have clearly distinct purposes, but slight overlap exists between get_timeline and get_latest_timeline (For You vs Following) and between get_tweet_by_id and get_tweet_details, which could cause misselection if descriptions are not carefully read.
All tools follow a consistent verb_noun snake_case pattern (e.g., bookmark_tweet, delete_bookmark, get_user_followers), with no mixing of conventions or irregular verbs.
38 tools is on the higher end for a Twitter API client, but given the breadth of Twitter's features (bookmarks, tweets, users, timelines, trends, search, DMs), the count is still reasonable and each tool has a specific function.
The server covers a wide range of read operations but lacks essential write operations like creating or deleting tweets, and missing DM sending. This leaves notable gaps in the typical Twitter workflow.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Twitter/X read-only MCP server — 12 tools: search, users, tweets, followers, timelines, trends.
Read-only public Twitter data and TweetAPI docs for AI agents. Not affiliated with X Corp.
X/Twitter reads, search, monitors and posting. Pay-per-call in USDC — no signup, no API keys.
Search, label, and manage your X (Twitter) bookmarks from any MCP client via Tweetsmash
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Huakira/x-mcp-lite'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
