Skip to main content
Glama
platypus-db

platypus-db

Official

estimate_change

Preview a single SQL change before execution: see estimated affected rows, query plan, safety checks, and whether it would run or be refused, so you can correct it first.

Instructions

Dry run of a change: returns, without running anything, what the confirmation dialog would show the user for one SQL statement: the rows the database expects to change (estimated_rows) and its plan, the Safety checks that would ask or refuse (safety_checks), and whether the user is asked in the app (asks_the_user) and the change would run (would_run). A statement the connection's access refuses answers outcome=refused with the reason; one that changes nothing answers outcome=not_a_change. A database without plans answers with no estimate and says so. Use it to correct a statement before run_query asks the user.

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

Input Schema

NameRequiredDescriptionDefault
sqlYesOne SQL statement (or command): the change to estimate. It is never run.
connectionYesThe connection's name, as `list_connections` shows it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.6.2

TDQS

A4.6/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 behavioral burden and does so: nothing is executed, the return fields are enumerated, and the outcome variants (refused with reason, not_a_change, no plan available) are spelled out. This is exactly the disclosure a dry-run tool needs.

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?

The key guarantee ('without running anything') is front-loaded and each clause covers a distinct outcome. It is dense and parenthetical-heavy, running as one long paragraph, but no sentence is redundant.

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?

No output schema exists, yet the description effectively documents the return shape and its edge cases, and it explains the safety/confirmation model. An agent has everything needed to call it and interpret the result.

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 meaning: only one statement is estimated, and the connection's access level determines whether the answer is 'refused'. That links both parameters to observable behavior rather than 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 verb and resource ('Dry run of a change') and precisely defines the output: estimated_rows, plan, safety_checks, asks_the_user, would_run. It explicitly contrasts with run_query, so an agent can distinguish it from the sibling without opening either schema.

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 a clear directive: 'Use it to correct a statement before run_query asks the user,' which names the alternative and the selecting condition. It stops short of stating when not to use it (e.g. for statements that are not changes), but the intended workflow is unambiguous.

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