Skip to main content
Glama
Social Fetch MCP

Social Fetch MCP

Official

Create a saved query

saved_queries_create

Save a Boolean social media query to run on a schedule, store new matching posts, and optionally send them to a webhook with alerts or briefings.

Instructions

Save a Boolean query to run on a schedule and keep the posts it matches. Each run searches live, charges what its searches cost (never more than maxCreditsPerRun) and stores new matches; optionally sends them to a webhook endpoint. alertThreshold optionally alerts when it finds at least that many posts in an hour or a day (the saved_query.threshold webhook event); briefing optionally adds a daily or weekly briefing, in the app and to that endpoint; noise leaves out job ads, giveaways or crypto spam; platformSearches optionally sets what each run searches on a platform instead of what's planned from the query (every post is still checked against the whole query); sentiment optionally gives each new match a sentiment estimate, a paid extra out of each run's credits; insights (what the topic is about, and up to 3 yes/no questions) optionally judges each new match's relevance, kind, need of a reply and risk, 1 credit per 10 matches judged. Runs once straight away unless runNow is false. Check the query with query_validate_post first. Refused for a workspace that keeps no request content.

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": {
      "name": "<name>",
      "query": "<query>",
      "maxCreditsPerRun": "<maxCreditsPerRun>",
      "cadenceMinutes": "<cadenceMinutes>",
      "context": "<context>",
      "llm_model": "<llm_model>"
    },
    "name": "saved_queries_create"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesA name for the query, shown in the dashboard and in alerts.
noiseNoKinds of post its runs leave out: `jobs` (job ads and job seekers' posts), `giveaways` (giveaway and contest entry posts), `crypto-spam` (crypto promotion and money scams). Checked on each post after it's found, so a run costs the same. Empty, the default, leaves everything in.
queryYesThe Boolean query. Check it for free first with POST /v1/query/validate.
runNowNoRun it once straight away rather than at its first scheduled time. Default true.
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.
briefingNoA briefing on what it found: `daily` covers the day before (UTC) and comes at 08:00 UTC; `weekly` covers Monday to Sunday and comes on Monday at 08:00 UTC. It counts the posts, the change on the period before, the stories, each platform's posts, the loudest voices and the 5 most engaged posts, is shown on the query in the Listening app, and is sent to its webhook endpoint as the `saved_query.briefing` event. Only for an active query that ran in the period without failing. Null for none, the default.
insightsNo
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. Empty means every platform search covers.
sentimentNoGive each new match a sentiment estimate (positive, neutral or negative), for 1 credit per 10 matches given one, on top of each run's maxCreditsPerRun but within monthlyCreditCap when one is set. Only matches given one are charged. A match keeps its sentiment: it's never estimated or charged again. Default false.
alertThresholdNoA volume alert: when a run brings the posts it found in the trailing `window` to at least `posts`, it sends the `saved_query.threshold` webhook event, at most once a window. The first run of a query or of a new wording doesn't alert (it finds the backlog). Null for none.
cadenceMinutesYesMinutes between scheduled runs, from 15 to 10080 (a week).
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.
maxCreditsPerRunYesThe most one run may charge, held while it runs as with POST /v1/query/search; what isn't used is given back.
monthlyCreditCapNoThe most all its runs may charge in a calendar month (UTC). Null for no cap beyond each run's.
platformSearchesNo
webhookEndpointIdNoA webhook endpoint of this workspace to send new matches to (event `saved_query.matches`), spikes (event `saved_query.spike`: far more posts in 24 hours than its usual day), volume alerts (event `saved_query.threshold`) and briefings (event `saved_query.briefing`).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.1

TDQS

A4.2/5.0
Behavior5/5

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

The annotations only declare the generic write/open-world profile, and the description goes far beyond them: it explains that each run searches live, charges per search but never above maxCreditsPerRun, that unused credits are returned, that insights/sentiment bill incrementally (1 credit per 10 matches) within monthlyCreditCap, and that matches are judged/charged only once. It also discloses the zero-retention refusal and that insights change alert/spike counting.

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

Conciseness3/5

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

It is a single dense, semicolon-chained block covering roughly a dozen optional features, which makes it hard to scan for the one option an agent needs. The opening sentence is well front-loaded and little is pure filler, but the duplication with schema descriptions inflates length without adding much.

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 an 18-parameter scheduling tool with no output schema, the definition covers cost model, scheduling, prerequisites, refusal conditions and billing interactions, which is the important surface area. It is light on what the call returns (created query identifier, initial run outcome) and on how optional features interact when several are enabled at once.

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?

With 89% schema description coverage the schema already documents nearly every parameter, and most of the description's parameter talk restates it (noise categories, sentiment pricing, briefing schedule, platformSearches override). It does add a few cross-parameter rules not in the schema, such as insights suppressing unrelated matches from alerts and spikes, and the alertThreshold cadence constraint.

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?

Opens with a specific verb and resource: 'Save a Boolean query to run on a schedule and keep the posts it matches.' It distinguishes the tool from one-off searching (each run searches live and stores new matches) and from the sibling validator by directing the agent to query_validate_post first.

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

Usage Guidelines4/5

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

Gives concrete pre-call guidance ('Check the query with query_validate_post first'), states default execution behavior ('Runs once straight away unless runNow is false'), and names an exclusion ('Refused for a workspace that keeps no request content'). It does not contrast saved queries with monitors_create or explain when to prefer an ad-hoc query_search_post instead.

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