Skip to main content
Glama

db_query

Run predefined parameterized queries against allow-listed PostgreSQL, MySQL, or Redis database presets and return rows as JSON, with approval and audit controls.

Instructions

Run a NAMED QUERY against a database preset (PostgreSQL, MySQL, or Redis). You supply query_name (must match one declared in the preset) and params (positional). The SQL/command is FIXED at preset definition time — you cannot send arbitrary SQL. Returns rows as JSON. Approval prompt fires per the preset's policy. If the user previously approved a time-boxed window for this preset+action, the call proceeds without a new prompt and is recorded as 'windowed' in the audit log.

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": {
      "preset_name": "<preset_name>",
      "query_name": "<query_name>"
    },
    "name": "db_query"
  }
}

Input Schema

NameRequiredDescriptionDefault
paramsNoPositional parameters; types must match the named query's `param_types`.
query_nameYesMust match one of the preset's declared `queries[].name`.
preset_nameYes

Output Schema

NameRequiredDescriptionDefault
rowsYes
noticeNoSet when mcp-warden withheld the rows (over the size limit).
rows_affectedYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.6.0
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "Set when mcp-warden withheld the rows (over the size limit).",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
  2. First observedv0.1.0

TDQS

A4.1/5.0
Behavior4/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 substantial work: it discloses the approval prompt per preset policy, the time-boxed window behavior that skips re-prompting, and that windowed calls are tagged in the audit log. It does not state whether named queries can be mutating (and thus destructive), which is the main remaining behavioral unknown.

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 its hard constraint, then layered with return format, approval behavior, and the windowed-approval nuance. Every sentence adds information, though the audit-log sentence is slightly dense and could be tightened.

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 3-parameter tool with an output schema, this covers nearly everything an agent needs: constraints, param shape, return type, and approval mechanics. The gap is preset discovery - nothing tells the agent how to learn valid preset_name/query_name values before calling.

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 67%, and the description reinforces query_name's constraint ('must match one declared in the preset') and params' positional nature and type-matching requirement. However, preset_name is left entirely undefined - the description never explains what a preset is, where it comes from, or how presets are scoped, so the one undocumented parameter stays opaque.

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 and resource ('Run a NAMED QUERY against a database preset') and immediately scopes it: only preset-declared queries, no arbitrary SQL. It names the supported backends (PostgreSQL, MySQL, Redis), which distinguishes it from ssh_exec or proxy_http siblings at a glance.

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?

It clearly defines the usage context - supply a query_name that matches the preset and positional params - and explicitly rules out the adjacent capability (arbitrary SQL). What's missing is routing to the sibling that helps you find valid preset/query names; list_presets is never mentioned, so discovery 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.