datatomcp

Chart

chart

Read-onlyIdempotent

Draw a chart from a query on a dataset: the query runs like aggregate (or query_rows when it has select), then result columns map onto the chart. x is the group_by column for the axis or categories; y lists metric names (or columns); series splits line, area, columns and bar into one series per value. grain (day, week, month, quarter, year) groups a date column in group_by by that period. mode draws columns and bars stacked, grouped or as 100%. variance, bullet and scorecard take two y columns (actual, then plan or target); candlestick takes four (open, high, low, close). Measures defined as lower is better (costs) are coloured the right way round. Write the title as the takeaway ("Asia Pacific grew fastest in 2026"), not a label, and the subtitle as the measure and unit. Returns the SVG and the chart spec. Charts: line, area, columns, bar, donut, treemap, waffle, funnel, pareto, scatter, heatmap, histogram, kpi, table, variance, bullet, waterfall, scorecard, combo, radar, candlestick, gauge, box, dotPlot.

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": {
      "dataset_id": "<dataset_id>",
      "chart": "<chart>"
    },
    "name": "chart"
  }
}

Input Schema

Name	Required	Description
`x`	No
`y`	No
`pie`	No
`mode`	No
`chart`	Yes
`grain`	No	Group date and timestamp columns in group_by by this period (week starts Monday); each group is labelled with the period's first day
`limit`	No
`theme`	No	Leave out for the workspace's brand (or datatomcp light when it has none)
`title`	No
`where`	No
`words`	No	Replace words the chart draws by itself, e.g. { "plan": "Budget" }
`format`	No
`invert`	No	Lower is better for the values drawn (costs, churn)
`select`	No
`series`	No
`metrics`	No
`version`	No	The dataset version from an earlier result's meta (or one listed in describe_dataset's versions). Pass it when you chain calls (distinct_values, then aggregate): the answer stays on that version even if the data was refreshed in between (meta then has stale: true and current_version). If that version is no longer kept, the call fails with source_changed.
`currency`	No
`group_by`	No
`order_by`	No
`subtitle`	No
`highlight`	No
`dataset_id`	Yes	Dataset id from list_datasets, e.g. ds_ab12cd34ef56

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 6, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already establish readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond them by disclosing the return payload ("Returns the SVG and the chart spec") and a non-obvious rendering behaviour (lower-is-better measures are coloured the right way round). It omits rate limits, row limits and failure modes, keeping it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

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

The first sentence is well front-loaded and the mid-section on x/y/series/grain/mode is dense but earns its place. The closing enumeration of all 24 chart types merely restates the chart enum already in the schema, adding length without adding information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 23-parameter tool with no output schema, the description covers the chart-shaping core and states what is returned, which is the minimum an agent needs to call it correctly. Gaps remain around filtering (where), metric definitions, limit/format/currency and ordering, leaving an agent to infer behaviour on a complex tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 26%, so the description carries real burden, and it does explain the highest-value parameters: x, y, series, grain, mode, and the y-arity rules per chart type, plus the title/subtitle writing convention. However, with 23 parameters, many remain unexplained in both places (limit, format, currency, highlight, order_by, where, select, metrics, pie), so it compensates only partially.

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?

Opens with a specific verb and resource ("Draw a chart from a query on a dataset") and immediately positions the tool against siblings by saying the query runs like aggregate, or query_rows when select is present. An agent can tell what this produces (SVG plus chart spec) and how it relates to aggregate/query_rows 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 real routing guidance: which query semantics apply (aggregate vs query_rows), and which chart types require how many y columns (variance/bullet/scorecard take two, candlestick takes four). It does not state when NOT to chart (e.g. use aggregate for raw numbers, create_dashboard to persist), so it falls short of explicit alternatives, but the per-chart-type conditions are genuinely useful.

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

All datatomcp 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.