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

TableJSON 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

TableJSON 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.

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.7/5.0

Behavior5/5

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

Beyond the readOnlyHint and idempotentHint annotations, the description explicitly forbids DDL, DML, and file-reading functions, and discloses the runtime availability constraint based on CANVAS_PROVIDER_TYPE. This gives the agent concrete behavioral boundaries that are not fully captured by annotations alone.

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?

The description is three sentences with no filler. It front-loads the core purpose and read-only nature, then provides the prerequisite workflow, supported operations, and environment requirement. Every sentence contributes meaningful information.

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?

The description covers the prerequisite discovery step, the supported SQL operations, the rejection of non-SELECT statements, the dependency on oecd_query_dataset, and the duckdb environment requirement. Combined with the output schema, an agent has enough context to call the tool correctly without missing critical setup or constraints.

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 100%, so the baseline is 3. The description adds value by explaining the relationship between the SQL parameter and table names returned by oecd_dataframe_describe, and by naming the supported query capabilities (aggregation, filtering, GROUP BY, JOIN, window functions) beyond the schema's generic SELECT statement description.

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 description states a specific verb ('Run'), a resource ('OECD observation tables staged on a DataCanvas'), and the operation type ('read-only SQL SELECT'). It differentiates this tool from sibling tools by noting that oecd_dataframe_describe should be called first and that this tool is for querying staged tables, not for fetching or describing datasets.

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?

The description gives clear usage context: call oecd_dataframe_describe first to discover table and column names, then use this tool for aggregation, filtering, GROUP BY, JOIN, and window functions. It also states the environment prerequisite (CANVAS_PROVIDER_TYPE=duckdb). It does not explicitly name alternatives or when-not-to-use scenarios, but the guidance is strong enough for an agent to select it correctly.

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.