Agent Tools API

Read an X (Twitter) post

read_x_post

Read-onlyIdempotent

Read public X (Twitter) posts from x.com or twitter.com URLs or post ids, through X's documented oEmbed endpoint (publish.x.com/oembed), with no login and no key. Use when the user shares a link to a post and wants what it says, who wrote it, the day it went up and its language. Each post row has text, author (handle, name), createdAt (YYYY-MM-DD), lang, the links in the text and hasMedia. X cuts posts longer than 280 characters in the embed and ends them with an ellipsis. The embed carries no media files, quoted post, like or view counts, replies or thread, so this tool cannot return them. A post X will not embed (deleted, protected, age-restricted, suspended author) comes back as a type "error" row with code unavailable, never partial data. Reads only the posts asked for; no timelines, search or profiles.

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": {
      "posts": "<posts>"
    },
    "name": "read_x_post"
  }
}

Input Schema

Name	Required	Description	Default
`posts`	Yes	Post URLs or numeric ids, e.g. ["https://x.com/jack/status/20", "20"]

Output Schema

Name	Required	Description	Default
`cache`	Yes	How the result was served: HIT or STALE from a cache tier, MISS or BYPASS when it was fetched now.
`results`	Yes	One row per requested post, read through X's oEmbed endpoint, or an error row with a code.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 23, 2026

removedInput schema / properties / includeThread

Removed value: -{
-  "description": "Also return the author's earlier posts in the same self-thread, oldest first (default false, at most 25 posts)",
-  "type": "boolean"
-}

changedOutput schema / properties / results / description

Previous value: -"One row per requested post (and its earlier thread posts when asked), or an error row with a code."New value: +"One row per requested post, read through X's oEmbed endpoint, or an error row with a code."

changedOutput schema / properties / results / items / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "properties": {
-      "article": {
-        "additionalProperties": true,
-        "type": [
-          "object",
-          "null"
-        ]
-      },
-      "author": {
-        "additionalProperties": true,
-        "type": "object"
-      },
-      "counts": {
-        "additionalProperties": true,
-        "type": "object"
-      },
-      "createdAt": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "id": {
-        "type": "string"
-      },
-      "input": {
-        "type": "string"
-      },
-      "media": {
-        "items": {
-          "additionalProperties": true,
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "quote": {
-        "additionalProperties": true,
-        "type": [
-          "object",
-          "null"
-        ]
-      },
-      "replies": {
-        "properties": {
-          "available": {
-            "const": false
-          },
-          "count": {
-            "type": [
-              "number",
-              "null"
-            ]
-          },
-          "reason": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "available"
-        ],
-        "type": "object"
-      },
-      "text": {
-        "type": "string"
-      },
-      "threadOf": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "type": {
-        "const": "post"
-      },
-      "url": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "id",
-      "url",
-      "text",
-      "author",
-      "counts",
-      "replies",
-      "input"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": true,
-    "properties": {
-      "code": {
-        "type": "string"
-      },
-      "input": {
-        "type": "string"
-      },
-      "message": {
-        "type": "string"
-      },
-      "postId": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "retryable": {
-        "type": "boolean"
-      },
-      "status": {
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "type": {
-        "const": "error"
-      }
-    },
-    "required": [
-      "type",
-      "input",
-      "code",
-      "message",
-      "retryable"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "properties": {
+      "author": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "createdAt": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "hasMedia": {
+        "type": "boolean"
+      },
+      "id": {
+        "type": "string"
+      },
+      "input": {
+        "type": "string"
+      },
+      "lang": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "links": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "source": {
+        "const": "oembed"
+      },
+      "text": {
+        "type": "string"
+      },
+      "type": {
+        "const": "post"
+      },
+      "url": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "id",
+      "url",
+      "text",
+      "author",
+      "input"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": true,
+    "properties": {
+      "code": {
+        "type": "string"
+      },
+      "input": {
+        "type": "string"
+      },
+      "message": {
+        "type": "string"
+      },
+      "postId": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "retryable": {
+        "type": "boolean"
+      },
+      "status": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "type": {
+        "const": "error"
+      }
+    },
+    "required": [
+      "type",
+      "input",
+      "code",
+      "message",
+      "retryable"
+    ],
+    "type": "object"
+  }
+]

Changed1 schema field changedOct 10, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "cache": {
+      "description": "How the result was served: HIT or STALE from a cache tier, MISS or BYPASS when it was fetched now.",
+      "properties": {
+        "ageSeconds": {
+          "type": "number"
+        },
+        "source": {
+          "enum": [
+            "worker",
+            "origin",
+            "coalesced"
+          ],
+          "type": "string"
+        },
+        "status": {
+          "enum": [
+            "HIT",
+            "STALE",
+            "MISS",
+            "BYPASS"
+          ],
+          "type": "string"
+        },
+        "tier": {
+          "type": "string"
+        },
+        "ttlSeconds": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "status",
+        "tier",
+        "ageSeconds",
+        "ttlSeconds"
+      ],
+      "type": "object"
+    },
+    "results": {
+      "description": "One row per requested post (and its earlier thread posts when asked), or an error row with a code.",
+      "items": {
+        "anyOf": [
+          {
+            "additionalProperties": true,
+            "properties": {
+              "article": {
+                "additionalProperties": true,
+                "type": [
+                  "object",
+                  "null"
+                ]
+              },
+              "author": {
+                "additionalProperties": true,
+                "type": "object"
+              },
+              "counts": {
+                "additionalProperties": true,
+                "type": "object"
+              },
+              "createdAt": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "id": {
+                "type": "string"
+              },
+              "input": {
+                "type": "string"
+              },
+              "media": {
+                "items": {
+                  "additionalProperties": true,
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "quote": {
+                "additionalProperties": true,
+                "type": [
+                  "object",
+                  "null"
+                ]
+              },
+              "replies": {
+                "properties": {
+                  "available": {
+                    "const": false
+                  },
+                  "count": {
+                    "type": [
+                      "number",
+                      "null"
+                    ]
+                  },
+                  "reason": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "available"
+                ],
+                "type": "object"
+              },
+              "text": {
+                "type": "string"
+              },
+              "threadOf": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "type": {
+                "const": "post"
+              },
+              "url": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "type",
+              "id",
+              "url",
+              "text",
+              "author",
+              "counts",
+              "replies",
+              "input"
+            ],
+            "type": "object"
+          },
+          {
+            "additionalProperties": true,
+            "properties": {
+              "code": {
+                "type": "string"
+              },
+              "input": {
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              },
+              "postId": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "retryable": {
+                "type": "boolean"
+              },
+              "status": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "type": {
+                "const": "error"
+              }
+            },
+            "required": [
+              "type",
+              "input",
+              "code",
+              "message",
+              "retryable"
+            ],
+            "type": "object"
+          }
+        ]
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "results",
+    "cache"
+  ],
+  "type": "object"
+}

First observedOct 3, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already declare a safe, read-only, idempotent, open-world operation, yet the description adds substantial context the annotations cannot: no login or key required, 280-character truncation with an ellipsis, and the exact categories of data that will never be present (media files, quoted post, like/view counts, replies, thread). It also specifies failure behavior — a type "error" row with code unavailable, "never partial data" — which is precisely the kind of contract an agent needs to avoid misreporting results.

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?

Front-loaded with the action and the mechanism, then trigger, then return shape, then limitations, then error behavior. Every sentence carries a distinct fact — truncation, absent fields, error rows, scope limits — with no restatement of the title or name.

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?

An output schema exists, yet the description still summarizes the row fields (text, author handle/name, createdAt, lang, links, hasMedia) and defines the error-row shape, so an agent can interpret both success and failure without guessing. Nothing needed to call the tool correctly or report results accurately is missing.

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% and the single `posts` parameter already carries a concrete example, so the schema does the heavy lifting. The description only marginally adds by naming twitter.com alongside x.com as an accepted URL form. Baseline 3 is appropriate; no array-limit or id-vs-URL handling detail is added beyond the schema.

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 ("Read public X (Twitter) posts") plus the exact mechanism (X's oEmbed endpoint at publish.x.com/oembed) and the accepted input forms. It also explicitly bounds scope — "no timelines, search or profiles" — which separates it from any timeline/feed sibling an agent might otherwise reach for.

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

Usage Guidelines5/5

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

Gives an explicit trigger: "Use when the user shares a link to a post and wants what it says, who wrote it, the day it went up and its language." It also names what the tool is not for (timelines, search, profiles), so the agent has both a positive and a negative selection rule.

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

All Agent Tools API 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.