Skip to main content
Glama
riveterhq

Riveter MCP Server

Official
by riveterhq
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Build dataset

build_dataset

Create a dataset from supplied rows or generate rows from a prompt, then fill output columns from attributes or a saved enrichment.

Instructions

build dataset

Build a dataset: rows you send or rows Riveter finds. rows (≤ 100 objects keyed by input column name, free) or prompt + count (generated, paid); output columns from attributes or enrichment_id, or, with prompt + count alone, written from the prompt (one typed column per fact it asks for) along with the identity columns; auto_fill: true fills generated rows when they land; budget caps a generation's spend (default 50 + 1.5 per row). Returns the dataset (id, ds_...) and run (the generation run, or null); then enrich with dataset_id alone. estimate_cost: true prices it first. help with datasets.

Example — Rows you have, two columns to fill: { "name": "Targets", "rows": [ { "Company": "Apple", "Website": "apple.com" }, { "Company": "Shopify" } ], "attributes": [ "CEO", "HQ city" ] }

Example — Generate 50 rows on a 100-credit budget, filled when they land, refused above 200 credits: { "prompt": "Specialty coffee roasters in San Francisco", "count": 50, "input_columns": [ "Roaster", "Website" ], "attributes": [ "Founded year" ], "auto_fill": true, "budget": 100, "max_credits": 200 }

Example — The whole dataset from the prompt — identity columns and typed output columns: { "prompt": "Top 50 US fintech startups with their CEO, total funding, and founding year", "count": 50, "auto_fill": true }

Workflow: The response is the dataset and, with prompt + count, a generation run — poll it with get_run, then read the rows with list_dataset_rows (auto_fill: true researches them as they land).

Input Schema

NameRequiredDescriptionDefault
nameNoDisplay name
rowsNoThe rows, keyed by input column name. Up to 100; more with POST /datasets/{id}/rows/import.
countNoHow many rows to generate for prompt. Capped per account.
budgetNoMost credits the build may spend (default 50 + 1.5 per row); charged at kickoff, settled to the agent's spend. A low budget means fewer rows.
promptNoWhat the rows are, for Riveter to find them. Requires count.
auto_fillNoWith count: fill the output columns when the rows land (a second paid run).
attributesNoOutput column names; they become the dataset's own enrichment's columns, typed from their names. Not with enrichment_id. Nothing is filled until POST /enrich (or auto_fill).
max_creditsNoCredit ceiling. Refused with 422 credit_cap_exceeded (nothing charged) when the estimate's maximum exceeds it.
webhook_urlNoPOSTed the list-generation run when it finishes
enrichment_idNoA saved enrichment (enr_...) whose output columns become the dataset's. Not with attributes.
estimate_costNoValidate and price the request without running or charging anything; the 200 response is the credit estimate (EstimateCostResult).
input_columnsNoInput column names (row identity). Optional with rows; with prompt, the identity columns to generate — omitted, they are written from the prompt, and with no attributes / enrichment_id the output columns are too.
fill_webhook_urlNoWith auto_fill: POSTed the fill run when it finishes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.3.5

TDQS

A4.6/5.0
Behavior5/5

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

Annotations declare non-readonly, open-world, non-destructive, but say nothing about cost. The description carries that burden well: `rows` is free, prompt+count is paid, budget is charged at kickoff and settled, `auto_fill` triggers a second paid run, and `max_credits` causes a 422 credit_cap_exceeded with nothing charged. That is exactly the behavioral context annotations cannot express.

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?

Dense but front-loaded: the mode split and the return shape come before the examples, and the three examples each demonstrate a distinct parameter combination rather than repeating prose. The opening line "build dataset" only echoes the name and title and is wasted space in an otherwise efficient definition.

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?

For a 13-parameter tool with no output schema, the description covers the return value (`id`, `ds_...`, and `run` or null), the follow-up calls, and the cost model. An agent has enough to choose a mode, construct a valid request, and know what to do with the response.

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?

With 100% schema coverage the baseline is 3, but the description adds relational meaning the schema does not: the rows/propmt-count mode split, the attributes-vs-enrichment_id exclusivity in practice, and the fact that output columns are written from the prompt when neither is supplied. It also restates budget's default formula, which is already in 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.

Purpose5/5

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

States a specific verb and resource ("Build a dataset") and immediately splits the tool into its two functional modes: rows you send vs rows Riveter finds. That framing distinguishes it from add_dataset_rows, import_dataset_rows, and build_configured_dataset without opening any schema.

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 when-to guidance: use `rows` for data you have, `prompt` + `count` for generation, `estimate_cost: true` to price first, and `help` with `datasets` for more. It also states the post-build workflow (poll `get_run`, read with `list_dataset_rows`). It never explicitly says when to prefer sibling tools like build_dataset_rows or build_configured_dataset, which keeps this below a 5.

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