Skip to main content
Glama

NYSgpt Data Library

Run SQL

query
Read-only

Run one read-only SQL statement (SELECT, WITH, SHOW or DESCRIBE) in the Amazon Athena (Trino) dialect and return up to 1,000 rows with column names and bytes scanned. Qualify every table as database.table. Select only the columns you need and filter on year or state columns where they exist, because each query has a scan limit (1 GB without a key, 10 GB with a paid key). Numeric text columns need try_cast(col AS double). When a daily limit is reached the error message gives the address for a paid key.

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"
  }
}

Input Schema

NameRequiredDescriptionDefault
sqlYesOne SQL statement, for example: SELECT publication_year, count(*) FROM govblock_scholarly.openalex_works GROUP BY 1 ORDER BY 1

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond readOnlyHint/openWorldHint by disclosing the row cap, that bytes scanned is returned, the exact scan ceilings (1 GB free, 10 GB with a paid key), and the error-path remediation for quota exhaustion. These are operational constraints an agent cannot get from the annotations or schema.

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-loads the core action and return shape in the first sentence, then layers constraints and the quota fallback. Dense but each sentence carries actionable information; the scan-limit rationale is slightly repetitive around the quota topic.

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?

For a single-parameter query tool with no output schema, it covers dialect, statement cardinality, row limits, returned fields, cost/scan constraints, type-casting pitfalls, and the quota error path. Nothing material is missing for correct invocation.

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% and the schema already carries an example, so baseline is 3. The description adds real semantic constraints on the sql value: exactly one statement, read-only, Trino dialect, mandatory database.table qualification, and try_cast for numeric text — meaning not expressed in 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 verb and resource ('Run one read-only SQL statement'), names the allowed statement types (SELECT, WITH, SHOW, DESCRIBE), the engine dialect (Athena/Trino), and the return shape (up to 1,000 rows, column names, bytes scanned). This is clearly distinguishable from the sibling metadata tools describe_table/list_databases/list_tables.

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 concrete usage rules: qualify tables as database.table, project only needed columns, filter on year/state to stay under scan limits, and use try_cast for numeric text columns. It also explains what to do when a daily limit is hit. It stops short of explicitly naming sibling tools for schema discovery, so routing guidance is implied rather than stated.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.