OrionBI

Change a Data Set

dataset_update

DestructiveIdempotent

Change a Data Set you own, by name: its SQL (or, for a SaaS source, its JSON source selection), description, refresh schedule, refresh mode, indexed columns or freshness window. Only the fields you pass change; the rest keep their values. A schedule is EITHER refreshIntervalSeconds OR refreshCron — passing one replaces whichever the Data Set had, and passing both as null makes it manual-refresh only. The cached table is not rebuilt by this call: it keeps its last build until the next refresh (an interval schedule fires straight away; a cron waits for its next occurrence; a manual one waits for you). Call dataset_refresh to rebuild it now. A Data Set shared with you can only be changed by its owner.

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>"
    },
    "name": "dataset_update"
  }
}

Input Schema

Name	Required	Description
`sql`	No	New SQL to materialize, or for a SaaS source the JSON source-selection object as text. Omit to keep it.
`name`	Yes	Name of the Data Set to change, from dataset_list
`syncKey`	No	With Sync: the unique key column. null lets it pick. Omit to keep it.
`description`	No	New description. "" clears it. Omit to keep it.
`refreshCron`	No	5-field UTC cron schedule, replacing any interval. null clears it.
`refreshMode`	No	"auto": Sync when the query allows it, else reload every row. "sync": copy only changed rows (PostgreSQL, one table, a unique key and a changed-at timestamp in the result). "full": reload every row. "incremental": append rows past incrementalKey. Setting it again after Sync stopped tries Sync again. Omit to keep it.
`indexColumns`	No	Columns to index on the cached table, replacing the current list. Omit to keep it.
`incrementalKey`	No	The increasing column an incremental refresh reads past. Omit to keep it.
`syncChangedColumn`	No	With Sync: the changed-at timestamp column. null lets it pick. Omit to keep it.
`freshnessWindowSeconds`	No	How long a build stays fresh before a read triggers a lazy refresh. Omit to keep it.
`refreshIntervalSeconds`	No	Refresh every N seconds (minimum 300), replacing any cron. null clears it. Omit both this and refreshCron to keep the current schedule.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 4, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the annotations (mutation, destructive, idempotent), it discloses the partial-update contract ('only the fields you pass change'), the destructive replacement semantics of scheduling and index columns, and the crucial side effect that the cached table is NOT rebuilt and stays stale until a refresh. It also names the authorization constraint, which no structured field conveys.

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?

It is front-loaded with the verb, scope and mutable-field list, then moves to the subtle schedule and cache semantics, and every sentence carries information. It is dense as a continuous paragraph, though — the schedule clause and the cache clause could be split for faster scanning.

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?

Eleven parameters, no output schema, and non-obvious mutation semantics call for a rich description, and this one covers partial updates, schedule replacement, cache staleness, the refresh escape hatch, and ownership limits. Nothing an agent needs before calling is missing.

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 already 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot express: refreshIntervalSeconds and refreshCron are mutually exclusive, one replaces the other, and passing both as null makes the set manual-refresh only. That constraint is the single most likely source of a wrong call and is explained clearly.

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?

It names a specific verb and resource ('Change a Data Set you own, by name') and enumerates exactly what is mutable: SQL / JSON source selection, description, refresh schedule, refresh mode, indexed columns, freshness window. That enumeration separates it from dataset_create and dataset_refresh without needing either schema opened.

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 states the decisive exclusion ('a Data Set shared with you can only be changed by its owner') and routes the agent to the correct alternative: 'Call dataset_refresh to rebuild it now' when the stale cache matters. It also tells the agent to use an interval schedule when an immediate refresh is intended.

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

All OrionBI 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?