Skip to main content
Glama
XcrapCC

@xcrap/mcp

Official
by XcrapCC
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Search X posts

xcrap_search
Read-only

Search X/Twitter posts by query, including operators like from:, to:, exact phrases, filters, and date ranges. Returns matching posts with author, timestamp, text, metrics, and pagination.

Instructions

Full-text search over X/Twitter posts, with the same operators X's own search understands.

This is how you answer "what are people saying about Y", "find posts from @x about Z", "any recent posts linking to this site" or "what did @x post about the launch last week". The query is passed to X as-is, so operators work: from:nasa, to:jack, "exact phrase", -exclude, lang:en, filter:links, min_faves:100.

When to use this instead of the alternatives:

  • Use xcrap_get_user_tweets or xcrap_get_user_history to read one account's posts without a topic.

  • Use xcrap_get_trends for what is trending in general, with no query.

  • Use xcrap_get_replies for the conversation under one specific post.

Args:

  • q (string, required): the search query, operators included.

  • feed ('latest' | 'top' | 'photos' | 'videos'): 'latest' (default) for newest first, 'top' for X's most relevant, or only posts with photos or videos.

  • since (string): oldest post to match, as a date such as "2025-01-01".

  • until (string): newest post to match, as a date.

  • cursor (string): the next_cursor from a previous call, for the next page. Omit for the first page. Do not invent one.

  • format ('markdown' | 'json'): default 'markdown'.

Returns markdown: a "Search:" heading with the result count and feed, then each post with its author, timestamp, permalink, text and metrics, and a "Next page" cursor line when there is more. Returns json: { query, feed, since, until, count, next_cursor, tweets[ ] }.

Costs 15 calls per 15 minutes — the tightest budget here. Write one precise query with operators instead of several broad ones. A 503 means search capacity is used up for now; wait for the time it gives.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
qYesThe search query, including any X search operators, e.g. "from:nasa mars".
feedNo'latest' (default) for newest first, 'top' for most relevant, 'photos' or 'videos' for media posts only.latest
sinceNoOldest post to match, as a date: "2025-01-01" or an ISO timestamp.
untilNoNewest post to match, as a date: "2025-03-31" or an ISO timestamp.
cursorNoPagination cursor from a previous call. Omit for the first page; never construct one by hand.
formatNoOutput format. 'markdown' (default) is compact, human-readable and costs roughly a tenth of the tokens of the same data as JSON — prefer it for reading and summarising. Use 'json' only when you need exact field access: numeric ids, media URLs, per-metric values, or provenance metadata.markdown

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is safe to call. The description adds substantial behavioral context beyond that: it states that the query is passed to X as-is (operators work), explains the cost ('Costs 15 calls per 15 minutes'), describes the error handling ('A 503 means search capacity is used up for now; wait for the time it gives'), and details the return format for both markdown and JSON, including pagination via 'next_cursor'. This is comprehensive behavioral disclosure that goes well beyond the annotations.

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 well-structured and front-loaded: a concise one-liner about the tool's core function, followed by usage examples, then explicit sibling differentiation, then parameter details, then return format, and finally rate-limit/error info. Every section earns its place—no fluff, no repetition of schema content verbatim. It's long but efficient, with clear headers that make it scannable for an agent.

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?

For a tool with search operators, pagination, rate limits, and multiple output formats, this description covers all necessary context: what the tool does, when to use it, how each parameter behaves (including defaults), what the return structure looks like for both markdown and JSON, the rate limit, and error handling. Since there is no output schema, the description must explain the return values, which it does thoroughly. No critical information is missing for an agent to call the tool correctly.

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?

The input schema covers 100% of parameters with descriptions, so the baseline is 3. However, the tool description adds significant extra semantic value: it explains the operator syntax in the description (from:nasa, etc.), clarifies the 'cursor' parameter ('Do not invent one'), and expands on the 'format' parameter with token-cost guidance ('prefer it for reading and summarising'). These additions go beyond the schema's descriptions, making the parameter semantics richer and more actionable.

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 opens with a clear, specific statement: 'Full-text search over X/Twitter posts, with the same operators X's own search understands.' It immediately conveys the verb (search), the resource (X/Twitter posts), and the scope (full-text with operators). It further differentiates from siblings by naming alternatives (xcrap_get_user_tweets, xcrap_get_trends, etc.) and explaining when to use each. This is unambiguous and distinguishes it from the sibling tools.

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?

The description includes an explicit 'When to use this instead of the alternatives:' section that lists specific sibling tools and the conditions for choosing this tool over them. For example, 'Use xcrap_get_user_tweets or xcrap_get_user_history to read one account's posts without a topic.' This leaves no ambiguity about when to invoke this tool versus its alternatives.

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