Riveter MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

Search agent

search_agent

Answer scoped one-off questions through AI-driven web search, scraping, PDF reading, and HTTP requests, returning free-text or schema-structured results.

Instructions

search agent

Ask a question and get an answer. This is meant for quick, relatively scoped one-off questions, like "What is the NAICS code for this company...". For more complex questions, use the enrich/ endpoint.

This uses the same AI + web-tool loop that fills a single agent-mode cell in an enrichment (web search, web scraping, PDF reading, HTTP requests), with no enrichment setup.

The run is processed in the background while this request long-polls up to wait seconds (default 50) — most runs finish in time and return the answer inline in output.result. If the agent is still working when the budget elapses, the response comes back with status: processing and output: null; poll GET /runs/{id}/result (it long-polls too) until the run is terminal.

Pass output_schema (a JSON Schema object) to get output.result back as a structured object matching your schema instead of free text. Unanswerable questions return the string "not found".

Quick example

curl -X POST https://api.riveterhq.com/v1/search_agent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Who is the current CEO of Anthropic, and when did they take the role?"}'

Credit costs

1 credit per call (same as one agent-mode enrichment cell), charged when the agent completes. Failed runs are not charged.

Example — A free-text question: { "prompt": "Who is the current CEO of Anthropic, and when did they take the role?" }

Example — A structured answer via output_schema: { "prompt": "Find the founding year and headquarters city of Anthropic", "output_schema": { "type": "object", "properties": { "founding_year": { "type": "integer" }, "headquarters_city": { "type": "string" } } } }

Input Schema

Name	Required	Description
`wait`	No	Seconds to hold this request waiting for the answer (default and max 50). Pass 0 to return immediately and poll GET /runs/{id}/result instead.
`prompt`	Yes	The question or task for the agent
`run_key`	No	Optional idempotency key (becomes the run id "run_<run_key>")
`max_credits`	No	Credit ceiling. Refused with 422 credit_cap_exceeded (nothing charged) when the estimate's maximum exceeds it.
`estimate_cost`	No	Validate and price the request without running or charging anything; the 200 response is the credit estimate (EstimateCostResult).
`output_schema`	No	Optional JSON Schema object for the answer, e.g. `{"type": "object", "properties": {"ceo_name": {"type": "string"}}}`. When set, `output.result` is an object matching this schema.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.5Oct 29, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Annotations only declare openWorldHint=true and readOnlyHint=false; the description goes far beyond them by disclosing the long-poll behavior (up to `wait` seconds, default 50), the `status: processing` / `output: null` fallback and the polling endpoint to use, the `"not found"` sentinel for unanswerable questions, and credit accounting (1 credit charged on completion, failures not charged). These are exactly the operational facts an agent needs and none are inferable from 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.

Conciseness4/5

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

Content is front-loaded: the one-line purpose, then scope boundary, then the long-poll mechanics, then credits. It is somewhat heavy for a single tool — a curl example plus two JSON examples partially duplicate each other — but each block carries distinct information, so the length is defensible rather than padded.

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?

With no output schema present, the description takes on the return-value burden and discharges it: it specifies `output.result` as free text or a schema-conforming object, the non-terminal `status: processing` state, and the `"not found"` string. Combined with the polling and credit details, an agent can call this correctly and handle every documented outcome.

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 is 3; the description earns above that by explaining the effect of `output_schema` on the return value (structured object in `output.result` instead of free text) and the wait/poll tradeoff, both of which are behavioral rather than mere restatements. `run_key` idempotency and the `max_credits` ceiling are only covered by the schema, so it stops short of a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The body states a specific verb+resource ("Ask a question and get an answer") and explains the underlying mechanism: an AI + web-tool loop doing web search, scraping, PDF reading, and HTTP requests with no enrichment setup. It differentiates itself from the `enrich/` endpoint, but the leading "search agent" line merely restates the title, and it never distinguishes itself from the sibling `quick_search`, which an agent could easily confuse it with.

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?

It gives an explicit usage boundary ("quick, relatively scoped one-off questions") and names the alternative for the other case ("For more complex questions, use the `enrich/` endpoint"). However, no guidance covers when to pick this over the closely related `quick_search` or `scrape` siblings, leaving a real routing ambiguity unresolved.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.