unfour

Overview Schema Source Related Servers Discussions Admin

Execute Database SQL

unfour.db.execute

Executes a single SQL statement on a saved connection for INSERT, UPDATE, DELETE, or DDL repairs to dev/test data, with engine safety checks, dry runs, and confirmation for high-risk writes.

Instructions

Executes one SQL statement against a saved database connection through the Unfour command bus. Use for INSERT/UPDATE/DELETE/DDL when an agent needs to repair dev/test data. Dev allows non-high-risk writes by default; test allows small writes but high-risk SQL requires confirm; prod blocks writes. DELETE/UPDATE without WHERE, DROP, TRUNCATE, ALTER, and multi-row destructive statements require a second call with the returned confirmation_text. Returns affectedRows, statementType, durationMs, and engine safety metadata.

Input Schema

Name	Required	Description	Default
`sql`	Yes
`limit`	No
`dryRun`	No
`schema`	No
`catalog`	No
`confirm`	No
`timeoutMs`	No
`transaction`	No
`workspaceId`	No
`connectionId`	Yes
`confirmationText`	No
`confirmation_text`	No

Output Schema

Name	Required	Description	Default
`ok`	Yes
`rows`	No
`dryRun`	Yes
`safety`	No
`source`	Yes
`columns`	No
`rowCount`	No
`warnings`	No
`truncated`	No
`durationMs`	No
`transaction`	No
`affectedRows`	No
`connectionId`	Yes
`statementType`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.12.0Oct 24, 2026
- addedOutput schema / properties / warnings
```
Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
```
Changed2 schema fields changedv0.6.0Aug 22, 2026
- addedOutput schema / properties / transaction
```
Added value: +{
+  "type": "boolean"
+}
```
- addedOutput schema / properties / truncated
```
Added value: +{
+  "type": "boolean"
+}
```
First observedv0.1.0Aug 20, 2026

TDQS

B3.2/5.0

Behavior2/5

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

The description is unusually rich about behavior: environment-gated write policy, a two-call confirmation flow using the returned confirmation_text, and the specific statement classes that trigger it. However, it directly conflicts with the annotation destructiveHint=false by advertising DROP, TRUNCATE, ALTER, DELETE/UPDATE-without-WHERE and 'multi-row destructive statements' — an agent trusting the annotation would severely underestimate the blast radius.

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?

Dense but front-loaded: what it does, then when to use it, then the environment policy, then the confirmation requirement, then the return shape. Every sentence carries information; the only near-waste is enumerating return fields when an output schema already exists.

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

Completeness3/5

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

For a 12-parameter, open-world write tool the description covers execution policy and the confirmation workflow well, and the output schema relieves it of explaining return values. But with 0% parameter documentation and an annotation that understates destructiveness, an agent still lacks enough to call it safely with the optional flags.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for 12 parameters, so the description carries the full burden and largely fails: only the confirmation_text parameter is explained (via the second-call flow). Nothing clarifies dryRun, limit, timeoutMs, transaction, confirm vs. confirmationText/confirmation_text duplication, or schema/catalog scoping, leaving several ambiguous or overlapping fields undocumented.

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?

States a specific verb and resource ('Executes one SQL statement against a saved database connection') and scopes it with 'Use for INSERT/UPDATE/DELETE/DDL', which implicitly separates it from the read-only sibling unfour.db.query_readonly. It never names that sibling outright, so an agent must infer the boundary rather than read it.

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 real usage context ('when an agent needs to repair dev/test data') and a per-environment policy matrix (dev allows, test gates high-risk SQL behind confirm, prod blocks writes) that tells the agent when the call will succeed. It does not explicitly name the alternative to use for SELECTs, so the read/write routing is only implied.

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

Deploy Server