feat: add x-twitter

[AbdulShahzeb]

X (Twitter)

Post tweets, send direct messages, and search for X users. Requires X Developer account with credit balance for API usage.

Field	Value
Category	social
Type	Tool Suite with actions: tweet, dm, search
Services	X (Twitter)
Icon	x.svg
Contributor	@AbdulShahzeb

Voice Triggers

• "Hey Cal, Post a tweet saying hello world"
• "Hey Cal, Send a direct message to someone on Twitter"

Required Credentials

• TWITTEROAUTH2API_CREDENTIAL (twitterOAuth2Api)

Required Variables

None required

---

🤖 Automated submission via registry.caal.io

[CAALBot]

✅ Tool Review: APPROVED

Feedback

The x-twitter tool is exceptionally well-implemented! The webhook description is comprehensive and clearly explains all three actions (tweet, dm, search) with their parameters. The tool suite structure correctly uses a Switch node routing on the action parameter, matching the actions array in the manifest. Error handling is robust with user-friendly messages for common scenarios like out-of-credits, suspended accounts, and forbidden access. The voice-friendly responses include message previews and proper formatting. All credentials are parameterized correctly. Excellent work, ready to merge!

---

Automated review by CAAL Tool Registry Bot

[CAALBot]

✅ Tool Review: APPROVED

Feedback

Excellent submission for the x-twitter tool! The implementation is thorough with proper credential handling, comprehensive error handling (including out-of-credits scenarios), and voice-friendly responses. The tool suite structure correctly implements the Switch node with matching actions array, and the webhook description is detailed and helpful for LLM tool selection. The README includes clear OAuth2 setup instructions with a visual guide. Ready to merge.

---

Automated review by CAAL Tool Registry Bot

[CAALBot]

✅ Tool Review: APPROVED

Feedback

The x-twitter tool submission looks excellent! All security requirements are met: credentials are properly nullified with ${TWITTEROAUTH2API_CREDENTIAL} placeholders, no hardcoded secrets or IPs are present, and the webhook description is comprehensive and LLM-optimized. The tool suite structure is correctly implemented with a Switch node routing on the 'action' parameter, matching the manifest's actions array ['tweet', 'dm', 'search']. Voice triggers are natural and varied, the README includes detailed OAuth2 setup instructions with screenshots, and error handling is robust with user-friendly messages. The workflow properly sets availableInMCP to true and includes only allowed settings fields. Great work on the voice-friendly response formatting with conversational messages!

---

Automated review by CAAL Tool Registry Bot

[cmac86]

@AbdulShahzeb, this looks great! I’ll have a more thorough review later today. I don’t have a X developer account with API credit, so not sure I can test myself. But I’ll have a look regardless.

Looks like I need to tweak CAALBot to not do a full review every time there is a commit to a PR. I’ll work on that.

If you have any other suggestions/ideas on the submission workflow, please let me know.

Thanks again for contributing!

[cmac86]

Hey Abdul,

I spent $5 on X API credits to properly test this (down to $4.94 now after testing 😅). Good news - all 3 actions work perfectly:

• Search - tested both "get self" and "get user by username"
• Tweet - posted successfully with natural voice command
• DM - sent and received without issues

Critical bug to fix:

The webhook path doesn't match the tool name:

• manifest.json has "name": "x_twitter" (underscore)
• workflow.json webhook has "path": "x-twitter" (hyphen)

This causes a 404 when CAAL tries to call the tool. Change the webhook path to "path": "x_twitter"

I've updated CAALBot to check for this. Not sure how I missed this in the pr review code/prompt. Its in now though.

Question about search functionality:

I'm a bit confused about the use case for the search action. It takes a username and returns the display name - but if I already know someone's username, why do I need their display name?

I originally thought search would help discover usernames from real names (like "search for Abdul Shahzeb" → find @AbdulSH), but it's the opposite direction. What's the intended workflow for this action?

Once the webhook path is fixed, this is ready to go.

cmac

[cmac86]

I think the naming convention is causing confusion after thinking about it more.

Current convention:

Registry tool name: x-twitter
n8n workflow name: x_twitter
webhook: x_twitter

It might make sense to just do underscore everywhere.

Registry tool name: x_twitter
n8n workflow name: x_twitter
webhook: x_twitter

For now if you update the webhook to x_twitter. The tool will work. Then I will think about this further and I can do a wholesale change of the registry.

[CAALBot]

✅ Tool Review: APPROVED

Feedback

The x-twitter tool is well-structured and ready to merge! The tool suite implementation is correct with the Switch node properly routing between tweet/dm/search actions that match the manifest. All credentials are properly nullified, the webhook path matches the tool name, and the webhook description is comprehensive and LLM-friendly. The voice triggers are natural, error handling is robust with user-friendly messages, and the code uses proper v2 syntax. Great work on the ASCII conversion helper for handling non-ASCII characters in display names and the detailed setup documentation with screenshots.

---

Automated review by CAAL Tool Registry Bot

[AbdulShahzeb]

Hey @cmac86,

Thanks for testing the tool and providing feedback.

Regarding the bug, this probably occurred because I manually renamed the tool from x_twitter to x-twitter to follow the existing convention, e.g. google-calendar, google-contacts, google-tasks, notion-tasks, weather-aus, weather-can, etc., but I missed a few names. Already fixed in the above commit :)

Regarding the search tool, I actually agree with your assessment. The original goal was indeed to support "search by query" user discovery, but n8n’s built-in X node doesn’t currently expose that capability. What’s there now is more of a completeness placeholder than a strong use case. I’ll either rework it using direct API calls via HTTP Request if feasible, or remove the search action altogether to avoid redundancy.

Thanks for the careful review, and pls let me know if you’d prefer one direction over the other for the search action.

Cheers
Abdul

[CAALBot]

❌ Tool Review: NEEDS_CHANGES

Issues

• manifest.json actions array does not match all Switch node outputKey values - manifest has 14 actions but the Switch nodes route by category first (tweet_action, user_action, get_user), then by individual action. The actions in manifest should match the final action routing values, which they do appear to match.
• Warning: The pinData section in workflow.json contains test data that should be removed before merge (includes hardcoded webhook test payload)
• Warning: SELF_USER_ID is listed as a credential type "selfUserID" in manifest but it's actually a variable used in the code node, not a credential - should be moved to required_variables instead

Feedback

Review completed.

---

Automated review by CAAL Tool Registry Bot

[cmac86]

Hey Abdul,

I see you expanded this to 14 actions - this is actually brilliant for CAAL's architecture. Let me explain why:

Multi-turn context (current): CAAL already injects the last 3 (configurable) tool responses' data arrays into the next prompt. So "What's Elon's latest tweet?" → tool returns {tweets: [{id: "123", ...}]} → "Retweet that" → LLM extracts the ID from context. No URL copying needed - pure voice conversation.

Short-term memory (coming soon): I'm about to ship a memory_hint system where tools can auto-store IDs for later reference. Your ID-based actions will work even better with persistent context across sessions.

Training data goldmine: I'm building training datasets for caal-ministral (fine-tuned model). Your 14-action suite teaches the model complex multi-turn reasoning - context extraction, action chaining, implicit references ("that tweet", "the first user"). Way more valuable than simple single-shot tools.

CAALBot found a couple issues but keep cooking. I’m really excited about how this one plays out and how the LLM handles it.

Have you tested with 14 tools already?

Corey

[CAALBot]

✅ Tool Review: APPROVED

Feedback

The x-twitter v2.0.0 tool is now ready to merge. Both issues from the previous review have been addressed: SELF_USER_ID has been correctly moved from required_credentials to required_variables, and the pinData test data has been removed from workflow.json. The tool now supports 14 actions covering tweet interactions, user lookups, DMs, and mute functionality with proper credential handling and comprehensive webhook documentation.

---

Automated review by CAAL Tool Registry Bot

[AbdulShahzeb]

Hey @cmac86

I've significantly expanded the X workflow since the initial version. Here's what's new:

Major Changes

Expanded Actions (from 3 → 14)

Tweet Interactions:

• get_tweet - retrieves tweet content + full engagement metrics (views, likes, retweets, replies, quotes, bookmarks)
• post_tweet (same as original)
• like_tweet, unlike_tweet
• retweet_tweet, unretweet_tweet
• delete_tweet

User Actions:

• dm_user (same as original)
• mute_user, unmute_user

User Lookup:

• get_user_by_query - search by name/description (e.g., "elon musk")
• get_user_by_username - exact handle lookup
• get_my_user - your own user profile
• get_blocked_users - list of accounts you've blocked

All user lookup actions return comprehensive profile data: follower/following/tweet counts, bio, location, account creation date, connection status (following/followed_by/blocking/muting), DM availability, and pinned/recent tweet IDs.

Architecture Improvements

• Two-tier switch routing - Level 1 routes by category (tweet_action, user_action, get_user, etc.), Level 2 routes to specific actions within each category. Much cleaner than 14 flat switch cases.
• Comprehensive input validation - the Validate Input node checks for required fields per action and provides helpful error messages
• Updated webhook description with clearer guidance and examples to help LLMs pick the right action, but it still might need an extra push every now and then

Technical Notes

• Using both OAuth 2.0 and OAuth 1.0a credentials (as many endpoints don't support OAuth 2.0)
• I tried implementing block_user but got an Authentication error using both credentials, so I haven't included it.

Manual Setup Required

There's one manual step: you'll need to paste your own X user ID into the workflow variables to avoid wasted API calls fetching it on every request. The workflow initialises it as const SELF_USER_ID in the Validate Input node for endpoints that require it. You can grab your ID by running the get_my_user action once and copying it from the response, or use a third-party tool.

---

P.S. it's 8am here and I've been developing this for 11 hours straight xd, so there might be bugs I glossed over. I'm keeping an eye on CAALBot's response and updating as needed. Would really appreciate any feedback you can provide! And fingers crossed I didn't leak any credentials.

Cheers,
Abdul

[cmac86]

@AbdulShahzeb,

See my comment above, I’m stoked for this one! This is pushing the limits that I have pushed with tool complexity.

11 straight hours! I haven’t pulled an all-nighter like that since my Counter-Strike days, haha. Go get some sleep mate!

I will do a thorough review and test of this one. This could be a flagship example if it plays out.

Curious if you have done your own tests with all 14 tools.

I also want to confirm that you’re using the latest version of the builder prompt located at caal-tools/prompts/ .

Also happy to see that my CAALBot tweaks worked. It’s looking at the incremental changes, not the full PR every time. Changed it to resume the previous Claude-code review session and just pipe in the commit diff.

Corey

[AbdulShahzeb]

Hey @cmac86

Regarding testing, I've tested all 14 actions extensively using cURL, and at least once each using CAAL. That said, as mentioned above, it may require further testing and fine-tuning. For example, I tried the following sequence:

• "Look up Elon Musk's profile"
• "What's his pinned tweet?"
• "Can you like it?"
• "Now retweet it"
• (possibly) "Can you unlike it now?"

However, CAAL did fail around the RT or unlike step as it forgot the tweet ID from the earlier context. I found it helpful to get CAAL to explicitly print/mention the tweet ID at the first or second step, though that's more useful in text mode than during pure voice conversation where you can't reference it visually.

That's not to say that this is the only failure - I also had issues where CAAL responded with, "Sure, I can send the DM to AbShahzeb now," almost like it was asking for confirmation. I had to repeat myself to confirm the action.

Regarding the builder prompt, I actually missed that completely. I've been developing the workflows manually in n8n since Gemini absolutely sucked during the first few iterations of weather-aus. That said, I have been referencing the existing tools occasionally to keep naming conventions and style consistent. I'll make sure to read through the builder prompt for future contributions to keep things standardised. Appreciate you pointing it out!

Looking forward to your feedback on this one.

Cheers
Abdul

[cmac86]

Quick feedback on the ID being forgotten: this makes sense as the default setting is to inject the last 3 tool calls back into the prompt, so by the time RT prompt happens, the ID is no longer injected back into the prompt. This is configurable and can be increased. I haven’t done testing on context limits with this setting, not sure how far you can push it.

The other thing that will help is the next feature I’m working on, which is short-term memory. We can add to your workflow a {memory_hint: {id: 124124}}. And it will be stored in short term memory and injected into every prompt until it expires or is manually removed using the frontend interface, or by asking CAAL to delete it.

Thanks again for the contributions. Really grateful.

Cheers

[cmac86]

Hey Abdul, I tested all 14 actions tonight. Here's the rundown:

13/14 actions confirmed working:

• get_tweet ✓
• post_tweet ✓
• delete_tweet ✓
• like_tweet ✓
• unlike_tweet ✓
• retweet_tweet ✓
• unretweet_tweet ✓
• mute_user ✓
• unmute_user ✓
• get_user_by_query ✓
• get_user_by_username ✓
• get_my_user ✓
• get_blocked_users ✓
• dm_user - untested; model refused to call the tool claiming the user "doesn't follow you" (LLM hallucination, not a tool issue)

One piece of feedback: get_tweet response doesn't include author info - the model had to guess who wrote the tweet (and got it wrong). Adding expansions=author_id with user.fields=username,name to the API call would fix that.

Solid work. The tool itself is clean - every action executed correctly. I ran into some issues with model consistency on tool calling, not the tools issue. I'm going to add a bunch of example uses of this tool the training data and re-train the caal-ministral:8b model. I'll train it on some tool chains as well. It actually did one tool chain where it looked up a user then muted the user, two calls in one prompt.

I'm going to go ahead and merge. The get_tweet improvement can be made in a follow up.

Well done on this!

p.s. - after merging I tested install successfully. It prompted for user id parameter, x oauth1 and x oauth2 credentials. I entered mine and it successfully replaced the parameters across the workflow.

I also noticed after merging that it didn't have a Sticky Note with the CAAL Tool Registry information, it must have got lost between commits. I added one back in. I'm updating the merge gh action to add a sticky if one doesn't exist so this should happen automatically.

Corey

[AbdulShahzeb]

Hey @cmac86

Thanks for the thorough testing and detailed feedback!

I may test the configurable tool-call memory parameter to see how CAAL behaves when retaining the last 5-10 callbacks. It might also help if the tool itself returned user/tweet ID wherever possible, so that they always stay within the memory window. This is something I can look into, including for get_tweet, as you mentioned. The changes would look like this:

Current:

Input
- tweet ID

Output
- text
- metrics

Updated:

Input
- tweet ID

Output
- text
- metrics
- tweet ID

Speaking of which, the reason get_tweet currently doesn’t return the author is that I initially thought it would be redundant, since the author is typically required to obtain the tweet ID in the first place. For example:

• Hey Cal, what's Sam Altman's username on X? Can I DM him?
• Can you read out his pinned tweet for me and tell me how many retweets it has?

That said, I’m happy to add author information to the response - that shouldn’t be an issue. I’ll also include a dm_user example at the bottom of the webhook notes and see if that helps.

Cheers
Abdul