Skip to main content
Glama
RajGehlot28

@twitterapis/mcp

by RajGehlot28
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

twitter_bookmark_search

Read-only

Search your authenticated X bookmarks by keyword to retrieve previously saved tweets. Returns matching results and a pagination cursor.

Instructions

Full-text search within YOUR authenticated account's bookmarks. Requires an authenticated session behind your key. Returns matching bookmarked tweets plus a cursor. Use this to retrieve a previously bookmarked tweet by keyword.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
ct0NoOptional. The account's ct0 cookie, paired with auth_token. Sent as the x-ct0 header.
countNoRequested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.
queryYesSearch terms to match against your bookmarked tweets' text.
cursorNoOpaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.
proxy_urlNoOptional. Residential proxy URL to egress this call through. Recommended for writes: X soft-blocks writes from datacenter IPs as automated. Sent as the x-proxy-url header.
auth_tokenNoOptional. The account's auth_token cookie, to act AS that account for this call (must be paired with ct0). Sent as the x-auth-token header; never placed in the URL.
user_agentNoOptional. User-Agent string to send for this session. Sent as the x-user-agent header.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.9.9

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it states an authenticated session behind the key is required and discloses the return shape (matching tweets plus a cursor), which the annotations do not convey.

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 sentences, the scope constraint and auth requirement front-loaded, and the return shape and use case follow. Every sentence carries distinct information with no redundancy.

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?

With no output schema, the description compensates by stating the return is matching tweets plus a cursor, and it covers the auth prerequisite. Pagination mechanics live in the cursor parameter's schema description, so what is missing here is minimal, though a brief note on paging would have made it fully self-contained.

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 the schema already documents all seven parameters, including the advisory count cap, the ct0/auth_token pairing, and the proxy recommendation. The description adds no parameter-level detail beyond what the schema provides, so the baseline 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?

States a specific verb (full-text search), a precise resource (bookmarks), and crucially scopes it to "YOUR authenticated account's bookmarks," which separates it from twitter_advanced_search and from the plain twitter_bookmarks listing sibling. An agent can identify it without opening the schema.

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?

"Use this to retrieve a previously bookmarked tweet by keyword" gives an explicit use case, so usage is more than implied. However, it names no alternatives (e.g., twitter_bookmarks for listing all bookmarks) and states no conditions under which this tool should not be chosen, leaving the when-not side entirely to inference.

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