Skip to main content
Glama

exchange-rates-mcp-server

by io.github.cyanheads

Fx Dataframe Query

fx_dataframe_query
Read-onlyIdempotent

Run a read-only SQL SELECT against DataCanvas tables staged by fx_get_timeseries. Supports aggregations, GROUP BY, window functions, and JOINs across multiple registered tables. Run fx_dataframe_describe first to discover table names and column schemas. Requires DataCanvas (CANVAS_PROVIDER_TYPE=duckdb) — without it this tool is not listed at all and fx_get_timeseries returns every range inline.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
queryYesRead-only SQL SELECT statement. Reference tables by the names returned by fx_dataframe_describe or the table_name field from fx_get_timeseries. Example: SELECT date, rate FROM fx_usd_eur WHERE date > '2024-01-01' ORDER BY date
canvas_idYesCanvas ID returned by fx_get_timeseries. Re-run fx_get_timeseries to obtain a fresh canvas_id if this one has expired.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
rowsNoResult rows, capped at the canvas row limit (default 10 000). Each key is a column name from the query.
errorNoPresent when the call failed. Absent on success.
canvas_idNoThe canvas ID used — pass to a subsequent fx_dataframe_query or fx_dataframe_describe call.
row_countNoRows returned. Equals the materialized row count; when truncated is true this is the row cap, not the full result size. Narrow the SELECT (add WHERE/LIMIT or aggregate) to see all rows.
truncatedNoTrue when the query produced more rows than the canvas row cap and the result was capped. Refine the query to materialize the complete result.

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the read-only nature is covered. The description adds valuable behavioral context: it notes the dependency on DataCanvas (CANVAS_PROVIDER_TYPE=duckdb) and that without it the tool is not listed, which is a behavioral condition. It also mentions that canvas_id may expire and advises re-running fx_get_timeseries, disclosing a stateful aspect. These go beyond annotations, though it doesn't describe return format or error handling. Given the strong annotation coverage, a 4 is appropriate.

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 two sentences, front-loading the core purpose in the first sentence. The second sentence adds prerequisite and dependency context, followed by a conditional note about behavior. Every clause serves a purpose: capability, usage guidance, and environmental requirement. There is no redundancy or filler, making it highly concise and well-structured.

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?

Given the complexity of a SQL-query tool with joins and aggregations, the description covers the essential context: prerequisite tools (fx_dataframe_describe), data source (fx_get_timeseries), and environmental requirement (DataCanvas). The output schema exists, so return value details are not needed. The description also addresses the freshness of canvas_id, which is critical for correct invocation. For a tool of this complexity, the description is remarkably complete.

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 coverage is 100% for both parameters, with both canvas_id and query having detailed descriptions including an example query. The tool description reinforces these but adds little that is not already in the schema. The main addition is the reference to 'tables staged by fx_get_timeseries' and the note about re-running fx_get_timeseries for a fresh canvas_id, but these are more contextual than parameter-specific. With complete schema descriptions, the baseline of 3 is correct.

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 clearly states the tool's function: 'Run a read-only SQL SELECT against DataCanvas tables staged by fx_get_timeseries.' It specifies the resource (DataCanvas tables), the action (run SQL SELECT), and explicitly distinguishes from siblings by naming fx_get_timeseries and fx_dataframe_describe as partners. The added capabilities (aggregations, GROUP BY, window functions, JOINs) further clarify its specialized role among the sibling tools, such as fx_get_rate or fx_get_rates, which are likely simpler retrieval tools.

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?

The description provides explicit when-to-use guidance: it directs the user to 'Run fx_dataframe_describe first to discover table names and column schemas.' It also states the prerequisite of DataCanvas availability and indicates consequences if not present ('without it this tool is not listed at all'). This effectively tells the agent when the tool is appropriate and what to do before invoking it. It does not explicitly mention alternatives, but the naming of fx_get_timeseries and fx_dataframe_describe in the flow implicitly distinguishes usage.

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

All exchange-rates-mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.6/5.0
Disambiguation5/5

Each tool has a distinct, non-overlapping purpose: conversion, single rate, bulk rates, timeseries, currency listing, and DataFrame inspection/query. The descriptions clearly differentiate between getting a rate vs converting an amount, and between inline vs DataCanvas-stored timeseries.

Naming Consistency5/5

All tools follow a consistent fx_verb_noun pattern (e.g., fx_get_rate, fx_convert_currency, fx_list_currencies). The two dataframe tools also adhere to fx_dataframe_verb, maintaining a uniform convention across the entire set.

Tool Count5/5

Seven tools is well-scoped for an exchange-rate server. Each tool addresses a needed operation (conversion, rates, timeseries, metadata) without redundancy or bloat, and adding DataFrame analysis feels justified for handling large datasets.

Completeness5/5

The surface covers the full lifecycle of exchange-rate queries: listing currencies, fetching single or bulk rates, converting with historical dates, and retrieving timeseries. The optional DataCanvas integration fills the gap for large-range analysis, leaving no obvious dead ends for common use cases.

Resources