Skip to main content
Glama
Social Fetch MCP

Social Fetch MCP

Official

Search Twitter posts

twitter_search_list
Read-onlyIdempotent

Search X posts or people by query and page through results with cursors; filter by section, date, language, and engagement to find relevant public conversations.

Instructions

Search X posts or people by query. Requires query. Returns a list (use cursor when paginated). limit is 1–20; use cursor for more. Pick top, latest, people, photos or videos with section; there is no sort field.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>",
      "context": "<context>",
      "llm_model": "<llm_model>"
    },
    "name": "twitter_search_list"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoOptional page size (1–20). Requests cannot ask for more than 20 posts; the actual page size may be smaller. Use the response cursor for subsequent pages.
queryYesRequired. Search query for public posts on X. Supported post-type operators include `include:nativeretweets`, `filter:nativeretweets`, and `filter:retweets`; `is:retweet` is not supported.
cursorNoOpaque pagination cursor returned by a previous response.
contextYesDescribe the user's underlying goal in one sentence, not the tool you are calling.
endDateNoOptional end date filter in YYYY-MM-DD format.
sectionNoSearch section: `top` (default), `latest`, `people`, `photos`, or `videos`.top
languageNoOptional language filter.
minLikesNoOptional minimum like count filter.
llm_modelYesThe exact model identifier you (the assistant) are running as, taken from your system prompt or environment (for example "claude-opus-4-8" or "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" and do not guess.
startDateNoOptional start date filter in YYYY-MM-DD format.
minRepliesNoOptional minimum reply count filter.
minRetweetsNoOptional minimum retweet count filter.
conversation_idNoEcho the conversation_id from the server's previous response. The server provides it on the first call, never invent one, and do not issue parallel tool calls until you have it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.1

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds real behavior beyond that: it returns a list, results are paginated via an opaque cursor, page size can never exceed 20, and there is no sort field. It omits any note on rate limits, result freshness, or what a 'people' section result looks like, which keeps it at adequate rather than rich.

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

Conciseness4/5

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

Four short sentences, front-loaded with the purpose, then pagination, then section choice. 'Requires `query`' and the 1–20 limit restate schema facts and could be cut, but there is no filler or rambling structure.

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

Completeness4/5

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

For a 13-parameter, no-output-schema search tool, the description covers the essentials an agent needs to call it correctly: required query, pagination mechanics, page-size ceiling, and section selection. The rich filter parameters (dates, language, minLikes/minReplies/minRetweets) and the analytics-only llm_model are left entirely to the schema, which is acceptable given full coverage.

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 description coverage is 100%, so all 13 parameters are already documented, giving a baseline of 3. The description's contribution is limited: repeating that query is required and that limit is 1–20 duplicates the schema, while 'there is no sort field' is the one genuinely additive semantic hint about how section substitutes for sorting.

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

Purpose4/5

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

States a specific verb and resource ('Search X posts or people by query'), which is clear and agent-legible. It does not, however, differentiate itself from близкие siblings such as twitter_community_search_list, twitter_hashtag_list, or twitter_profile_tweets_list, so the agent must infer which search surface applies.

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

Usage Guidelines3/5

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

The description gives operational guidance ('use cursor when paginated', 'limit is 1–20; use cursor for more', 'Pick top, latest, people, photos or videos') but every one of those pointers targets a parameter rather than the choice of tool. It never says when to prefer this search over the community, hashtag, or profile-post siblings, so usage is only implied.

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

Deploy Server

Other Tools