Skip to main content
Glama
X Use

X Use

by felixlark

Search X posts

x_search
Read-onlyIdempotent

Search X posts by query and time window, choose recent or full-archive scope, and control results with pagination and field filters.

Instructions

Search X posts. scope=recent covers the last 7 days; scope=all requests full-archive search and may be forbidden by account entitlement. Read-only.

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>"
    },
    "name": "x_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYesX search query using official search operators.
scopeNorecent
end_timeNoRFC 3339 end time.
since_idNoReturn posts newer than this ID.
until_idNoReturn posts older than this ID.
expansionsNoX API expansions, for example author_id,attachments.media_keys,referenced_posts.
sort_orderNo
start_timeNoRFC 3339 start time.
max_resultsNoRecent search accepts 10-100; full-archive search accepts 10-500.
poll_fieldsNoMapped to poll.fields.
post_fieldsNoMapped to the current query parameter post.fields.
user_fieldsNoMapped to user.fields.
media_fieldsNoMapped to media.fields.
place_fieldsNoMapped to place.fields.
pagination_tokenNoOpaque next_token from a previous page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so "Read-only" is largely redundant. The description does add genuinely new behavioral context the annotations lack: the 7-day window for scope=recent and the entitlement-based failure mode for scope=all, which directly affects whether and how the agent should call it.

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?

Three short sentences, front-loaded with the action, then the scope trade-off, then the safety note. No filler, and the most consequential constraint (entitlement) is stated before any call is made.

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 15-parameter search tool with no output schema, the description covers the decisive behaviors: what it searches, the two scope regimes, and the failure mode. It stays silent on pagination flow, rate limits, and how expansions/field arrays affect the response, which an agent handling multi-page results would still want.

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

Parameters4/5

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

Schema coverage is 87%, so the schema carries most parameter meaning and the baseline is 3. The description adds real value on the one parameter the schema leaves bare: the scope enum is not described in the schema, and the description supplies its time window and entitlement implication, which is the highest-stakes choice in the call.

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?

The description states a specific verb and resource ("Search X posts") and pairs it with the query/scope mechanism, so the agent knows this is a query-driven post search rather than a timeline fetch. It does not name any sibling such as x_user_posts or x_thread, so differentiation from those tools is left to inference.

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?

Usage guidance exists for the scope parameter: recent covers 7 days, all requests full-archive and 'may be forbidden by account entitlement', which tells the agent when the call will fail. There is no guidance on when to prefer this tool over siblings like x_user_posts or x_thread, so the when-to-use versus alternatives is only implied.

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