TweetAPI MCP

Official

by tweetapi

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

Get List Tweets

tweetapi_list_tweets

Read-onlyIdempotent

Fetch one page of posts from a Twitter List timeline by List ID or link, with cursor-based pagination for retrieving subsequent pages.

Instructions

Fetch one page of the posts in a List's timeline, by List ID or List link. Use tweetapi_list_members to see whose posts the List includes. Read-only. Needs a TweetAPI API key and makes one TweetAPI request per call, usually costing 1 unit; each result includes a cost estimate. Returns one page: to get the next one, call again with cursor set to this result's completeness.nextCursor.

Input Schema

Name	Required	Description
`cursor`	No	completeness.nextCursor from the previous page. Omit it for the first page.
`listId`	Yes	Numeric list ID, or a list link such as https://x.com/i/lists/1234567890.
`responseFormat`	No	full (default) returns TweetAPI's JSON unchanged. compact keeps full post text, IDs, links, original dates, counts, and cursors but drops bulky fields; output.fieldsOmitted lists what was dropped.

Output Schema

Name	Required	Description
`cost`	Yes
`mode`	Yes
`tool`	Yes
`notice`	Yes
`output`	Yes
`result`	Yes
`endpoint`	Yes
`usageDocs`	No
`pagination`	No	Pagination exactly as TweetAPI returned it.
`statusCode`	Yes
`retrievedAt`	Yes	When the MCP server received this response (ISO 8601). Not the post or profile date, and not a promise that X's data was fresh at that moment.
`completeness`	Yes
`resolvedInput`	No	Identifiers the MCP server parsed from links or @handles before calling TweetAPI.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.3.3Nov 5, 2026
- addedInput schema / properties / cursor / description
```
Added value: +"completeness.nextCursor from the previous page. Omit it for the first page."
```
Addedv0.2.1Nov 5, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already cover read-only/idempotent safety, yet the description adds genuinely new behavior: an API key is required, one request per call, roughly 1 cost unit with a per-result cost estimate, and the exact next-page mechanism via completeness.nextCursor. This is the kind of context structured fields do not carry.

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

Conciseness5/5

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

One dense paragraph, front-loaded with the action and scope, then alternatives, cost, and pagination in priority order. Every sentence carries information the agent needs; nothing is filler.

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

Completeness5/5

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

With an output schema present, return-value detail is unnecessary, and the description covers everything else an agent needs: auth requirement, cost model, pagination loop, and the sibling for membership. Nothing material is missing for a paginated read tool.

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

Parameters3/5

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

Schema coverage is 100%, so cursor, listId, and responseFormat are already documented. The description restates listId accepted forms and cursor semantics but adds no new meaning for responseFormat, so the baseline of 3 applies.

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

Purpose5/5

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

States a specific verb and resource ("Fetch one page of the posts in a List's timeline") and scopes the input domain (by List ID or List link). It is clearly distinguishable from siblings such as tweetapi_list_members or tweetapi_user_tweets without opening any schema.

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

Usage Guidelines4/5

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

Explicitly routes the agent to tweetapi_list_members for the membership question, and gives clear continuation guidance for paging. It does not state exclusions against other post-listing siblings (e.g. user_tweets), so it stops short of full when/when-not coverage.

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

Deploy Server