Social Fetch

Search Twitter posts

twitter_search_list

Read-only

Search X posts or people by query. Returns a list (use cursor when paginated).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`q`	No	Alias for `query`. Prefer `query`.
`trim`	No	Ignored if this tool does not support it.
`limit`	No	Optional 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.
`query`	No	Search query for public posts on X. Supported post-type operators include `include:nativeretweets`, `filter:nativeretweets`, and `filter:retweets`; `is:retweet` is not supported.
`cursor`	No	Opaque pagination cursor returned by a previous response.
`offset`	No	Ignored if this tool does not support it.
`context`	Yes	Describe the user's underlying goal in one sentence — not the tool you are calling.
`endDate`	No	Optional end date filter in YYYY-MM-DD format.
`section`	No	Search section: `top` (default), `latest`, `people`, `photos`, or `videos`.	top
`keywords`	No	Alias for `query`. Prefer `query`.
`language`	No	Optional language filter.
`minLikes`	No	Optional minimum like count filter.
`pageSize`	No	Ignored if this tool does not support it.
`llm_model`	Yes	The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" — never guess.
`startDate`	No	Optional start date filter in YYYY-MM-DD format.
`maxResults`	No	Ignored if this tool does not support it.
`minReplies`	No	Optional minimum reply count filter.
`max_results`	No	Ignored if this tool does not support it.
`minRetweets`	No	Optional minimum retweet count filter.
`conversation_id`	No	Echo 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.

Changed2 schema fields changedSep 22, 2026

changedInput schema / properties / limit / description

Previous value: -"Optional page size (1–20). Best-effort; the actual page size may differ."New value: +"Optional 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."

changedInput schema / properties / query / description

Previous value: -"Search query for public posts on X."New value: +"Search query for public posts on X. Supported post-type operators include `include:nativeretweets`, `filter:nativeretweets`, and `filter:retweets`; `is:retweet` is not supported."

Changed8 schema fields changedSep 21, 2026

addedInput schema / properties / keywords

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "number"
+    },
+    {
+      "type": "boolean"
+    }
+  ],
+  "description": "Alias for `query`. Prefer `query`."
+}

addedInput schema / properties / maxResults

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "number"
+    },
+    {
+      "type": "boolean"
+    }
+  ],
+  "description": "Ignored if this tool does not support it."
+}

addedInput schema / properties / max_results

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "number"
+    },
+    {
+      "type": "boolean"
+    }
+  ],
+  "description": "Ignored if this tool does not support it."
+}

addedInput schema / properties / offset

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "number"
+    },
+    {
+      "type": "boolean"
+    }
+  ],
+  "description": "Ignored if this tool does not support it."
+}

addedInput schema / properties / pageSize

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "number"
+    },
+    {
+      "type": "boolean"
+    }
+  ],
+  "description": "Ignored if this tool does not support it."
+}

addedInput schema / properties / q

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "number"
+    },
+    {
+      "type": "boolean"
+    }
+  ],
+  "description": "Alias for `query`. Prefer `query`."
+}

addedInput schema / properties / trim

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "number"
+    },
+    {
+      "type": "boolean"
+    }
+  ],
+  "description": "Ignored if this tool does not support it."
+}

changedInput schema / required

Previous value: -[
-  "query",
-  "context",
-  "llm_model"
-]New value: +[
+  "context",
+  "llm_model"
+]

Changed4 schema fields changedSep 12, 2026

changedInput schema / properties / limit / description

Previous value: -"Optional page size. Maximum supported value is 20."New value: +"Optional page size (1–20). Best-effort; the actual page size may differ."

changedInput schema / properties / query / description

Previous value: -"Search query text to run against public posts on X."New value: +"Search query for public posts on X."

addedInput schema / properties / section / default
```
Added value: +"top"
```

changedInput schema / properties / section / description

Previous value: -"Optional search section filter. Omit to use the default `top` section."New value: +"Search section: `top` (default), `latest`, `people`, `photos`, or `videos`."

Changed5 schema fields changedSep 5, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```

addedInput schema / properties / context

Added value: +{
+  "description": "Describe the user's underlying goal in one sentence — not the tool you are calling.",
+  "type": "string"
+}

addedInput schema / properties / conversation_id

Added value: +{
+  "description": "Echo 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.",
+  "type": "string"
+}

addedInput schema / properties / llm_model

Added value: +{
+  "description": "The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. \"claude-opus-4-8\", \"gpt-5.2\"). Used for analytics only. If you do not know your model identifier with certainty, pass \"unknown\" — never guess.",
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "query"
-]New value: +[
+  "query",
+  "context",
+  "llm_model"
+]

Changed1 schema field changedAug 27, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed1 schema field changedJul 29, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
Changed16 schema fields changedJul 29, 2026
- removedInput schema / properties / limit / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  }
-]
```
- addedInput schema / properties / limit / maximum
```
Added value: +20
```
- addedInput schema / properties / limit / minimum
```
Added value: +1
```
- addedInput schema / properties / limit / type
```
Added value: +"integer"
```
- removedInput schema / properties / minLikes / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  }
-]
```
- addedInput schema / properties / minLikes / maximum
```
Added value: +9007199254740991
```
- addedInput schema / properties / minLikes / minimum
```
Added value: +0
```
- addedInput schema / properties / minLikes / type
```
Added value: +"integer"
```
- removedInput schema / properties / minReplies / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  }
-]
```
- addedInput schema / properties / minReplies / maximum
```
Added value: +9007199254740991
```
- addedInput schema / properties / minReplies / minimum
```
Added value: +0
```
- addedInput schema / properties / minReplies / type
```
Added value: +"integer"
```
- removedInput schema / properties / minRetweets / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  }
-]
```
- addedInput schema / properties / minRetweets / maximum
```
Added value: +9007199254740991
```
- addedInput schema / properties / minRetweets / minimum
```
Added value: +0
```
- addedInput schema / properties / minRetweets / type
```
Added value: +"integer"
```
First observedJul 20, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds that it returns a list and mentions cursor-based pagination, which is useful behavioral context beyond the annotations. It does not describe other behaviors like rate limits or field details, but the annotations carry the primary safety burden.

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?

The description is two short sentences that front-load the action and include the key pagination note. There is no filler or redundant detail, making it highly efficient.

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 tool with 20 parameters, the schema carries the parameter details and annotations cover the read-only nature. The description covers the return type and pagination, which are the core operational aspects. It does not explicitly differentiate from sibling search tools, but that gap is more relevant to usage guidelines than to calling the tool correctly. Given the schema and annotations, the description is sufficient for an agent to invoke it properly.

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 every parameter is documented in the schema. The description itself adds no parameter-specific guidance beyond implicitly referencing 'query' and 'cursor' for pagination. Since the schema is comprehensive, the baseline score 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?

The description clearly states it searches X posts or people by query, a specific verb and resource. While it does not explicitly name sibling tools, the combination of posts and people distinguishes it from more specialized search tools like twitter_hashtag_list or twitter_community_search_list, making the purpose unambiguous.

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

Usage Guidelines2/5

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. Siblings include twitter_hashtag_list, twitter_community_search_list, and many platform-specific search tools, but the description does not mention selection criteria or exclusions. The only usage note is about pagination, which is not a decision aid.

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

All Social Fetch tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Search Twitter posts

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources