Skip to main content
Glama
bcb-mcp
by msperlin

Query Cache

query_cache
Read-only

Run read-only DuckDB SQL over cached Brazilian Central Bank SGS time series to filter, aggregate, and analyze local parquet data without fetching fresh observations.

Instructions

Run read-only SQL across every cached series (DuckDB over parquet files).

Example: SELECT series_name, avg(value) FROM cached_series WHERE ref_date >= DATE '2020-01-01' GROUP BY 1 ORDER BY 2 DESC.

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": {
      "sql": "<sql>"
    },
    "name": "query_cache"
  }
}

Input Schema

NameRequiredDescriptionDefault
sqlYesRead-only DuckDB SQL over the local parquet cache. Available views: cached_series(ref_date, value, series_id, series_name, unit, frequency, source, fetched_at), cached_queries (same columns), series_metadata(series_id, series_name, coverage, rows, updated_at).
limitNoMaximum rows returned (1..100000).

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile and local-execution nature are covered. The description reinforces read-only access and names the DuckDB-over-parquet substrate, but adds nothing about scan cost, timeouts, or what happens when the limit truncates results — the behaviors an agent most needs to know for a free-form query tool.

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?

Two sentences, purpose front-loaded before the example, with no filler. The example is somewhat long and oddly wrapped mid-clause, but it earns its space by showing the actual query dialect.

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

Completeness4/5

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

An output schema exists and annotations carry the read-only contract, so the description does not need to explain return values. What remains missing is only the routing guidance against the structured siblings; for a two-parameter read-only query tool, the definition is otherwise sufficient to invoke correctly.

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%, and the schema itself enumerates the three views and their columns, so the baseline is 3. The example query does add a little practical syntax guidance (date literal casting, aliasing the aggregate, GROUP BY ordinal), but it demonstrates only one pattern and does not explain the limit parameter's interaction with the SQL.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: run read-only SQL over the cached series, executed by DuckDB on parquet files. That is clearly not what the structured siblings (get_series, list_series, search_series) do, so an agent can tell them apart, though the description never names an alternative to sharpen the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: the worked SELECT ... GROUP BY example signals that this tool is for ad-hoc aggregation and analysis that the fixed-shape tools cannot express. There is no explicit when-to-use/when-not or routing advice (e.g., prefer get_series for a single known series), so the agent must infer the boundary.

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