grok_search (xAI Grok Live Search)

When to use

• Real-time/current-event lookup where you need fresh sources (X + web + news) and citations.
• Social sentiment / “what are people saying on X” for a market or entity.

Don’t use

• When free sources suffice (try gdelt_news first for background headlines).
• When you don’t need citations and want zero cost.

Cost + keys

• Paid. Cost scales mainly with maxResults (~$0.025/source per src/agents/grok.ts).
• Requires XAIAPIKEY or GROKAPIKEY in env.

Parameters

• query (string, required): Be specific. Include the entity + timeframe + what you want extracted.
• sources (array of "web" | "x" | "news", optional): Restrict which channels are searched.
• maxResults (int, optional, 1–50): Higher = more sources/cost; default is 20.

Examples

Tool call (agent / MCP style):

{ "name": "grok_search", "params": { "query": "Polymarket Venezuela election market latest developments", "sources": ["news","web"], "maxResults": 12 } }

HTTP:

curl -sS -X POST http://127.0.0.1:7777/api/tools/execute \
  -H 'Content-Type: application/json' \
  -d '{"name":"grok_search","params":{"query":"what changed in CPI print today","sources":["news"],"maxResults":10}}'

Output

• Returns: { content: string, citations: string[], sourcesUsed: number, model: string }
• Rendered:

- Answer (text) - Citations (table) - Meta (text: model + sourcesUsed)

Notes / extensions

• The underlying Grok client supports richer filters (date range, domain allow/deny, X handle allow/deny, engagement thresholds), but the current grok_search tool only exposes query/sources/maxResults. If you need those filters, extend src/tools/grok-search.ts to pass them through.