The X MCP Server presents a well-structured collection of 26 tools with consistent naming patterns and comprehensive input schemas. Most tools follow verb_noun naming conventions (get_*, create_*, delete_*, etc.). However, there are critical gaps in output schema documentation, parameter descriptions lack depth in several cases, and error handling guidance is minimal. Tool descriptions are present but often generic. The server demonstrates good baseline quality but falls short of production-grade standards in schema completeness and error recovery patterns.
Tools (26)
bookmark_tweetwriteauthsource verified73/100
Bookmark a post for later
create_tweetwriteauthsource verified83/100
Create a new post with optional media attachment. Media upload requires OAuth 2.0 credentials.
delete_tweetdestructiveauthsource verified77/100
Delete one of your posts
get_articleread onlyauthsource verified73/100
Fetch the full body content of an X Article post by its tweet ID
Output schemas are not documented. No tool description specifies what fields or structure is returned to the LLM. LLMs cannot determine downstream parameter compatibility (e.g., does get_user return a user_id field that create_tweet can use?) without trial and error.
Tool descriptions are generic and lack action guidance. Descriptions like 'Get recent posts from your home timeline' and 'Look up a specific post by its ID' do not explain WHEN to use this tool vs similar ones (e.g., get_home_timeline vs search_tweets vs get_user_tweets). LLMs cannot disambiguate without explicit guidance.
get_home_timelinesearch_tweetsget_tweet
Recommendations
Document the output schema for every tool. For list tools (get_home_timeline, search_tweets, etc.), explicitly state that results are returned as a JSON array with fields like tweet_id, author_id, created_at, public_metrics. For single-item tools, document the object structure. Example: 'Returns an object with fields: tweet_id (string), text (string), author_id (string), created_at (ISO 8601), metrics {likes, reposts, replies}.'
Expand tool descriptions to 100-200 characters and include WHEN to use each tool. Example for get_home_timeline: 'Retrieves your personalized feed of recent posts from accounts you follow. Use this for discovering new content. For searching specific posts, use search_tweets instead. Returns up to 100 posts, newest first.'
Add tool annotations to definitions. Wrap each tool registration with annotations: readOnlyHint=true for all get_* and search_tweets tools; destructiveHint=true for delete_tweet and unlike_tweet; idempotentHint=true for tools that are safe to retry (get_*, bookmark_*, like_tweet).
For all list/pagination tools, add pagination guidance to descriptions. Example: 'Results are paginated; call multiple times with the limit parameter to fetch batches. Each response includes a total_count field to indicate whether more results exist. X API limits to 100 results per request.'
Add error handling guidance to destructive operations. For delete_tweet, add to description: 'This operation is irreversible. Always confirm the tweet ID before calling. On error, returns a message indicating why deletion failed (e.g., tweet not found, insufficient permissions).'
No pagination guidance in tool descriptions. Tools like get_home_timeline and get_user_followers accept a 'limit' parameter (capped 1-100) but do not explain in the description what happens when there are more results, whether pagination is supported, or how to fetch the next batch. This forces the LLM to guess.
Destructive operations lack confirmation or dry-run guidance. delete_tweet description does not mention that deletion is irreversible or suggest a safeguard. Agents can accidentally delete posts without user consent if the LLM chooses to call this tool during exploration.
No error recovery guidance. Tool descriptions do not explain what the LLM should do if an operation fails. For example, create_tweet description does not state what error occurs if media upload fails, or whether the agent can retry. Handlers throw McpError but descriptions don't guide recovery.
Parameter descriptions lack specificity on constraints and format. For example, 'text' in create_tweet is described as 'The text content of the post (max 280 characters)' but does not explain what characters are forbidden, whether URLs are counted differently, or handling of emoji. image_path and video_path lack detail on supported formats and file size enforcement.
Authentication and permission requirements are mentioned in some descriptions (e.g., like_tweet: 'Not available on Free tier') but not consistently applied or explained for all tools. No tool description states what OAuth scopes are required or how to resolve permission errors.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are present in tool definitions, despite the risk classification being provided in the evaluation metadata. These hints are critical for LLM safety, without them, an agent cannot distinguish a safe read operation from a destructive one at parse time.
all 26 tools
Parameterize media constraints explicitly in descriptions. For create_tweet image_path: 'Absolute path to image file. Supported: PNG, JPEG, GIF, WEBP. Max 5MB. If upload fails, returns error with reason (e.g., unsupported format, file too large). Cannot be used with video_path.'
Add OAuth scope requirements to tool descriptions. Example for like_tweet: 'Requires OAuth 2.0 with write:tweets scope. Not available on Free tier (removed Aug 2025); requires Basic tier or above. Returns error if user lacks permission or tier.'
Document parameter interdependencies. For create_tweet, clarify: 'Exactly one of image_path or video_path may be provided. Providing both will return an error. If neither is provided, the post is text-only.'
Add a discovery tool or document available search filters. For search_tweets, mention: 'Query supports X search operators: from:user, to:user, has:links, is:retweet, lang:en. Example: from:elonmusk has:media.'
Implement per-item error responses for batch-style operations. For tools that accept a limit parameter and return multiple results, add guidance: 'If one post in the batch is unavailable (deleted, restricted), it is skipped in the result. Check the returned total_count against the requested limit to detect skips.'
Document rate limits and retry behavior. Add to descriptions: 'Subject to X API rate limits (varies by endpoint). On rate limit, returns error code RATE_LIMIT_EXCEEDED. Recommended backoff: exponential with 15-minute window. Safe to retry.'
For get_user and similar lookup tools, add fallback guidance: 'If user not found, returns null. Consider using search_tweets with from:username to verify the account exists. Note: Some accounts are deleted or restricted.'
Add response filtering guidance for list tools. For get_user_tweets: 'Returns tweets from the specified user. Retweets and quoted tweets are excluded by default. Replies are included. To filter, post-process the response in the client.'
Document OAuth credential injection. Add a note in the server README and per tool that API credentials are injected at runtime (environment variables or vault), users do not pass credentials as parameters.