Skip to main content
Glama
platypus-db

platypus-db

Official

query_across_databases

Runs one read-only DuckDB SQL statement across tables from multiple database connections by copying each source into a temporary DuckDB instance for cross-database joins, masking sensitive values.

Instructions

Runs one read-only DuckDB statement over tables of several connections: each source (connection, schema, table, optional name) is copied, up to source_rows rows (default 10000, up to 100000) and within that connection's limits, into a DuckDB of this call, where the statement joins them by name. Every connection must be open to agents; the statement runs only on the copies, cannot write to a source and reads no file nor URL. Values of sensitive columns are masked before they are copied (unless the user shows them for that connection): all values of such a column are equal, so do not join on one. A source copied in part is said so. Use DuckDB's SQL. Same result format and limits as run_query.

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

Input Schema

NameRequiredDescriptionDefault
sqlYesOne read-only DuckDB statement over the sources, by their `name`.
formatNo`text` (an aligned table, the default) or `json`.
sourcesYesThe tables to join, up to 8, each from a connection open to agents.
max_rowsNoRows returned at most (default 100, up to 10000).
max_bytesNoBytes of output at most (default 32768, up to 1048576).
source_rowsNoRows copied from each source (default 10000, up to 100000), within the connection's limits. A table with more rows is copied in part, and the answer says so.
timeout_secondsNoSeconds each read and the statement may run before it is cancelled (default 30, up to 300).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.6.2

TDQS

A4.5/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: read-only, statement executes only against local copies, cannot write to a source, reads no file or URL, sensitive columns are masked before copying, per-connection row limits apply, and partial copies are flagged in the answer. Those are exactly the behavioral traits an agent needs before calling.

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?

Front-loaded with the core action and dense with useful constraints; almost every sentence carries information. Some sentences are run-on and awkwardly phrased ("A source copied in part is said so"), which costs a little readability.

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?

For a 7-parameter tool with no output schema, it covers mechanics, safety, masking and limits well, and defers the return shape to run_query ("Same result format and limits as run_query"), which requires the agent to know that sibling. Otherwise nothing essential to calling it correctly is missing.

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, but the description adds real meaning: the 8-source cap, the join-by-name semantics tied to the optional name parameter, source_rows default and its interaction with connection limits, and the warning that masked columns are unsuitable join keys. It is not just restating the schema.

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 action (runs one read-only DuckDB statement) over a specific resource (tables of several connections), and explains the mechanism: each source is copied into a per-call DuckDB and joined by name. That scope statement alone separates it from run_query and compare_schemas.

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?

Names the precondition that every connection must be open to agents and implies the case for this tool (joining tables from multiple connections), plus a caveat about not joining on masked columns. It never explicitly routes the agent elsewhere (e.g. run_query for a single connection), so the when-not half is left to inference.

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