oecd-mcp-server

Oecd Dataframe Query

oecd_dataframe_query

Read-onlyIdempotent

Run a read-only SQL SELECT against OECD observation tables staged on a DataCanvas by oecd_query_dataset. Call oecd_dataframe_describe first to discover exact table and column names, then use this tool for aggregation, filtering, GROUP BY, JOIN, and window functions. Only available when CANVAS_PROVIDER_TYPE=duckdb is set.

Input Schema

Name	Required	Description	Default
`sql`	Yes	Read-only SELECT statement. Reference tables by the names returned by oecd_dataframe_describe. Only SELECT statements are allowed — DDL, DML, and file-reading functions are rejected.
`canvas_id`	Yes	Canvas ID returned by oecd_query_dataset — exactly 10 characters of letters, digits, hyphens, and underscores. Identifies the DataCanvas session holding the observation tables.

Output Schema

Name	Required	Description
`rows`	No	Result rows from the SQL query (capped at the canvas row limit).
`error`	No	Present when the call failed. Absent on success.
`row_count`	No	Full result count before any row cap.
`column_names`	No	Column names in the result, in order.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 24, 2026

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `canvas_disabled`: DataCanvas is not configured — CANVAS_PROVIDER_TYPE is unset. `canvas_not_found`: The canvas_id has expired or was never created. `table_not_found`: The SQL names a table this canvas does not hold — it expired, was dropped, or the name is wrong. `invalid_sql`: The SQL is not a valid SELECT statement or contains disallowed operations. `sql_execution_error`: The SQL parsed and ran, then failed on the staged observation data — a conversion, an invalid input, or a value out of range. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `canvas_disabled`: DataCanvas is not configured — CANVAS_PROVIDER_TYPE=none. `canvas_not_found`: The canvas_id has expired or was never created. `table_not_found`: The SQL names a table this canvas does not hold — it expired, was dropped, or the name is wrong. `invalid_sql`: The SQL is not a valid SELECT statement or contains disallowed operations. `sql_execution_error`: The SQL parsed and ran, then failed on the staged observation data — a conversion, an invalid input, or a value out of range. Other values are possible when a failure originates below the handler."

Changed4 schema fields changedSep 20, 2026

changedInput schema / properties / canvas_id / description

Previous value: -"Canvas ID returned by oecd_query_dataset. Identifies the DataCanvas session holding the observation tables."New value: +"Canvas ID returned by oecd_query_dataset — exactly 10 characters of letters, digits, hyphens, and underscores. Identifies the DataCanvas session holding the observation tables."

addedInput schema / properties / canvas_id / pattern
```
Added value: +"^[A-Za-z0-9_-]{10}$"
```

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `canvas_disabled`: DataCanvas is not configured — CANVAS_PROVIDER_TYPE is unset. `canvas_not_found`: The canvas_id has expired or was never created. `table_not_found`: The SQL names a table this canvas does not hold — it expired, was dropped, or the name is wrong. `invalid_sql`: The SQL is not a valid SELECT statement or contains disallowed operations. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `canvas_disabled`: DataCanvas is not configured — CANVAS_PROVIDER_TYPE is unset. `canvas_not_found`: The canvas_id has expired or was never created. `table_not_found`: The SQL names a table this canvas does not hold — it expired, was dropped, or the name is wrong. `invalid_sql`: The SQL is not a valid SELECT statement or contains disallowed operations. `sql_execution_error`: The SQL parsed and ran, then failed on the staged observation data — a conversion, an invalid input, or a value out of range. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "canvas_disabled",
-  "canvas_not_found",
-  "table_not_found",
-  "invalid_sql"
-]New value: +[
+  "canvas_disabled",
+  "canvas_not_found",
+  "table_not_found",
+  "invalid_sql",
+  "sql_execution_error"
+]

First observedSep 1, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds real context beyond them: only SELECT is permitted, DDL/DML/file-reading functions are rejected, and the tool exists only under a DuckDB canvas provider. Minor gaps remain (no mention of row limits or cost), so 4 rather than 5.

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

Conciseness5/5

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

Three sentences, each doing distinct work: capability, prerequisite plus use cases, availability constraint. The core action is front-loaded with no filler.

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 full annotation coverage, complete parameter descriptions, and an output schema handling return values, the description supplies everything else an agent needs — prerequisite chain, allowed statement types, and the runtime gate.

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 100%, with both sql and canvas_id already documenting format and provenance, so the schema carries the load. The description only reinforces that sql references names from oecd_dataframe_describe and that canvas_id originates from oecd_query_dataset — useful but largely duplicative.

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 ("Run a read-only SQL SELECT against OECD observation tables") plus the scope it operates on (tables staged on a DataCanvas by oecd_query_dataset). This clearly separates it from the describe/inspect siblings.

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 an explicit prerequisite ordering ("Call oecd_dataframe_describe first") and enumerates the intended workloads (aggregation, filtering, GROUP BY, JOIN, window functions), and names the environment gate CANVAS_PROVIDER_TYPE=duckdb. It does not state when to avoid this tool in favour of a sibling, so it falls short of a full 5.

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

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