Skip to main content
Glama
Social Fetch MCP

Social Fetch MCP

Official

Search with a Boolean query

query_search_post
Read-only

Search X, Reddit, YouTube, TikTok, LinkedIn, Instagram, Threads, and Hacker News live with one Boolean query; each platform uses its syntax, duplicates merge, and maxCredits caps cost.

Instructions

Search X, Reddit, YouTube, TikTok, LinkedIn, Instagram, Threads and Hacker News live with one Boolean query: each platform is searched in its own syntax, every post is checked against the whole query, and duplicates are merged. Charges what its searches cost, never more than maxCredits, and says how far it got on each platform. Check the query with query_validate_post first: it's free and estimates the cost. Returns every match at once, no cursor. Pass the same idempotencyKey to retry a search without being charged again; without one, each call is a new, charged search.

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>",
      "maxCredits": "<maxCredits>",
      "context": "<context>",
      "llm_model": "<llm_model>"
    },
    "name": "query_search_post"
  }
}

Input Schema

NameRequiredDescriptionDefault
noiseNoKinds of post to leave out of the matches, such as job ads. Checked on each post after it's found, so the search itself isn't narrowed and the credits are the same. How many each left out is in `filtered`. None by default.
queryYesThe Boolean query. Check it for free first with POST /v1/query/validate.
sinceNoEarliest post time, between 2000 and 2100. Overrides a date in an imported query.
untilNoLatest post time, between 2000 and 2100, not before `since`. Overrides a date in an imported query.
strictNoLeave out posts whose match depends on something the platform didn't return (`outcome: unknown`). Default false.
syntaxNoSyntax the query is written in: `native` (Social Fetch's Boolean language), or another tool's to import: `x` (X search), `onclusive`, `talkwalker`, `brandwatch` (also Cision Social Listening) or `meltwater`.
contextYesDescribe the user's underlying goal in one sentence, not the tool you are calling.
insightsNoJudge each post found: is it about what the topic is about, what is it (a complaint, question, praise, buying, promotion or news), does it need a reply, is it a risk, and up to 3 yes/no questions of your own. 1 credit per 10 posts given them, on top of maxCredits, as sentiment: only posts given insights are charged; if your balance or the key's monthly limit can't cover it, posts come back without them and nothing is charged, said in warnings. Every post is still returned, whatever its relevance. Not available with zero data retention.
llm_modelYesThe exact model identifier you (the assistant) are running as, taken from your system prompt or environment (for example "claude-opus-4-8" or "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" and do not guess.
platformsNoPlatforms to search. Every platform when omitted.
sentimentNoEstimate each post's sentiment (positive, neutral or negative), for 1 credit per 10 posts given one, on top of maxCredits: the searches still get all of maxCredits, and every post they find with text is given one. Only posts given one are charged. If your balance or the key's monthly limit can't cover it, the posts come back without one and nothing is charged for it, said in warnings. Default false.
maxCreditsYesThe most this search may charge, shared evenly between the platforms with something to search. Held from your balance while it runs; what isn't used is given back.
idempotencyKeyNoA key you choose for this search, such as a UUID; send the same one to retry it safely: the first response comes back, charging nothing. Each call is its own search without one.
conversation_idNoEcho 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.
platformSearchesNoSearches to run on a platform instead of those planned from the query, by platform. A platform left out is searched as planned. Only changes what's searched: every post is still checked against the whole query.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.1

TDQS

A4.7/5.0
Behavior5/5

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

Annotations declare readOnly/openWorld/non-idempotent, and the description goes well beyond them: the charging model ('Charges what its searches cost, never more than maxCredits'), the partial-coverage reporting ('says how far it got on each platform'), and the no-cursor all-at-once return. The idempotency explanation ('without one, each call is a new, charged search') is consistent with idempotentHint=false rather than contradicting it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Zero filler and front-loaded with the core capability, then cost, then the validation prerequisite, then the return/retry model. The sentences are very dense and pack multiple clauses each, which costs a little scannability but nothing is redundant.

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, nested-object search with no output schema, the definition covers the essential agent-facing facts: cost ceiling, partial results, no cursor, retry safety, and a free pre-validate step. It leaves the response shape of insights/filtered/warnings to the schema and annotations, which is reasonable, though a one-line note on what comes back would close the last gap.

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 100%, so the baseline would be 3, but the description adds cross-parameter meaning the schema cannot: cost is bounded by maxCredits, an idempotencyKey replays the first response at no charge, and validation estimates cost before spending. It does not touch noise, strict, syntax, or platformSearches, which remain schema-only.

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 ('Search X, Reddit, YouTube, TikTok, LinkedIn, Instagram, Threads and Hacker News live with one Boolean query') and adds the distinguishing mechanics: per-platform syntax, whole-query verification, and dedupe merging. An agent can tell this apart from single-post siblings and from query_validate_post without opening a schema.

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?

Explicitly names the prerequisite alternative and the reason to use it first: 'Check the query with query_validate_post first: it's free and estimates the cost.' It also gives retry guidance tied to idempotencyKey and states the without-key consequence, so the when-to-use and how-to-retry conditions are both spelled out.

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