mcp-server

Update an existing data spec

update_data_spec

Idempotent

Change an existing data spec's configuration. If no replacement file names are given, this runs synchronously (no upload needed): saves changes and — by default — re-runs AI analysis, returning the final status directly. If a replacement sample/format/target-schema file name IS given, this instead returns presigned upload URL(s); upload the file(s), then call finish_data_spec_update. Only pass the fields you want to change — omitted fields keep their current value.

IMPORTANT — re-analysis is a full regeneration, not a patch. It throws away the spec's existing parser and column mapping and rebuilds BOTH from the spec's stored input set as a whole: the sample file, format file, target-schema file, source tables and additionalPrompt, each read from storage exactly as it was last uploaded. A component you leave out is NOT left untouched in the generated code — it is fed to the AI again alongside the parts you changed. So updating a target schema without re-sending the source sample maps the new target against whatever sample was uploaded when the spec was onboarded, and the result is a complete, plausible-looking, WRONG mapping rather than an error.

Therefore, before changing anything that feeds code generation: call list_data (resource: "specs") to read this spec's stored input set, show the user what each component currently is, and re-send in THIS SAME call every component that is stale or that the user is now describing differently — then pass confirmedCurrentInputs: true. Keeping a stored component is a decision to make deliberately, not a default to fall into by only mentioning the field you were asked about.

Input Schema

Name	Required	Description
`merge`	No	Whether new data should merge/upsert into existing rows rather than append. For sourceType "tables" also changes the generated SQL between MERGE and INSERT.
`specName`	Yes	Name of the existing data spec to update
`computeSize`	No	Compute size for analysis/processing. Omit to keep the current setting.
`description`	No	New description for the spec. Omit to keep the current value.
`runAnalysis`	No	Whether to run analysis and wait for it after saving the changes (default true). Only applies to the synchronous (no-file-change) path.
`workspaceId`	No	Workspace to act on. Defaults to your only workspace if you have exactly one.
`sourceTables`	No	sourceType "tables" specs only: replacement list of source tables the generated query reads from.
`targetOption`	No	Change where transformed data lands. Omit to keep the current setting.
`targetTables`	No	sourceType "file" specs: new list of existing workspace tables to load into. Required when setting targetOption to "existing-tables". sourceType "tables" specs: the query's single target table name — pass a one-element array to rename the target (its schema is re-resolved per the spec's targetOption).
`formatFileName`	No	sourceType "file" specs only. File name of a replacement format spec file. The format spec outranks the sample when deriving field boundaries, so re-send it alongside a replacement sample rather than letting a new sample be parsed by an old spec.
`loadSampleData`	No	Whether re-analysis should also trigger the data-load job (default true). Only used when runAnalysis is true.
`sampleFileName`	No	sourceType "file" specs only. File name of a replacement sample data file. Send this whenever the source data the user is describing differs in any way from the stored sample — the regenerated parser and mapping are built from this file, so a stale one silently mis-maps the new target.
`additionalPrompt`	No	Extra natural-language guidance for the AI schema inference/mapping. Replaces the previously stored value when given (omit to keep it as-is), and is reused on every future re-analysis — keep it to instructions that actually change behavior. Don't restate default platform behavior (e.g. that unmapped target columns are null on insert and preserved on merge match) just to document it; a note only true for one case (like new rows) can read as a standing instruction later and confuse updates.
`targetSchemaFileName`	No	File name of a replacement target schema file. Required when setting targetOption to "target-schema-file". Replacing this re-derives the whole mapping against the stored sample/format files — re-send those here too unless you have confirmed they still represent the source data.
`confirmedCurrentInputs`	No	Required (true) whenever this update changes something that feeds AI code generation and analysis will run. It asserts that you have read the spec's stored input set (list_data, resource: "specs"), checked each component — sample file, format file, target-schema file, source tables, additionalPrompt — against what the user now wants, and re-sent every stale one in this same call. Set it only once that is actually true: re-analysis rebuilds the entire parser and mapping from that set, so one component left at an older version silently contradicts the ones you changed.

Output Schema

Name	Required	Description
`error`	No
`files`	No	Present only when replacement file(s) were given — upload these, then call finish_data_spec_update.
`specId`	No
`status`	No
`message`	Yes
`nextStep`	No	The finish_data_spec_update call to make once upload(s) are done. Only present alongside files.
`progress`	No
`specName`	No
`timedOut`	No
`lastJobId`	No
`errorDetails`	No
`statusMessage`	No
`hasTransformationConfig`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 10, 2026

addedInput schema / properties / confirmedCurrentInputs

Added value: +{
+  "description": "Required (true) whenever this update changes something that feeds AI code generation and analysis will run. It asserts that you have read the spec's stored input set (list_data, resource: \"specs\"), checked each component — sample file, format file, target-schema file, source tables, additionalPrompt — against what the user now wants, and re-sent every stale one in this same call. Set it only once that is actually true: re-analysis rebuilds the entire parser and mapping from that set, so one component left at an older version silently contradicts the ones you changed.",
+  "type": "boolean"
+}

changedInput schema / properties / formatFileName / description

Previous value: -"sourceType \"file\" specs only. File name of a replacement format spec file, if replacing it."New value: +"sourceType \"file\" specs only. File name of a replacement format spec file. The format spec outranks the sample when deriving field boundaries, so re-send it alongside a replacement sample rather than letting a new sample be parsed by an old spec."

changedInput schema / properties / sampleFileName / description

Previous value: -"sourceType \"file\" specs only. File name of a replacement sample data file, if replacing it."New value: +"sourceType \"file\" specs only. File name of a replacement sample data file. Send this whenever the source data the user is describing differs in any way from the stored sample — the regenerated parser and mapping are built from this file, so a stale one silently mis-maps the new target."

changedInput schema / properties / targetSchemaFileName / description

Previous value: -"File name of a replacement target schema file. Required when setting targetOption to \"target-schema-file\"."New value: +"File name of a replacement target schema file. Required when setting targetOption to \"target-schema-file\". Replacing this re-derives the whole mapping against the stored sample/format files — re-send those here too unless you have confirmed they still represent the source data."

Changed2 schema fields changedAug 19, 2026

addedInput schema / properties / computeSize / description

Added value: +"Compute size for analysis/processing. Omit to keep the current setting."

addedInput schema / properties / description / description

Added value: +"New description for the spec. Omit to keep the current value."

First observedAug 19, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=false. The description adds far more: re-analysis is a full regeneration that discards existing parser and column mapping, omitted components are still re-fed to the AI rather than left untouched, and a stale input yields a 'complete, plausible-looking, WRONG mapping rather than an error.' This is exactly the kind of non-obvious behavioral warning annotations cannot convey.

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?

The critical distinction (sync vs. upload path) and the regeneration warning are front-loaded, and the length is justified by 15 parameters and non-trivial side effects. However, the re-analysis warning is restated across several sentences ('full regeneration, not a patch' / 'the entire parser and mapping' / 'one component left at an older version silently contradicts'), which is some redundancy.

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?

An output schema exists, so return values need not be described. Given the tool's complexity, the description supplies everything needed to invoke safely: path selection, prerequisite reads, the stale-input hazard, and the confirmation flag's contract.

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 description coverage is already 100%, so the baseline is 3; the description earns an extra point by explaining cross-parameter behavior that the schema states only per-field — that supplying any replacement file name switches to the upload path, that omitted fields keep current values, and how sample/format/target-schema files interact during regeneration.

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?

The opening sentence gives a specific verb+resource ('Change an existing data spec's configuration') and immediately splits the tool into its two distinct execution modes (synchronous save-and-reanalyze vs. presigned-upload). It names the follow-up sibling (finish_data_spec_update), so an agent can tell what this tool does and does not cover without opening the 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?

It explicitly states when each path fires ('If no replacement file names are given... If a replacement sample/format/target-schema file name IS given') and prescribes a concrete prerequisite workflow: call list_data (resource: "specs"), show the user stale components, re-send them in the same call, then pass confirmedCurrentInputs: true. This is explicit when/when-not guidance plus a named alternative tool.

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

All mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?