preview_write

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

Annotations already declare readOnlyHint=true, but the description adds significant behavioral detail: it converts the write to a SELECT, never sends the write, explains how each statement type (UPDATE/DELETE/INSERT) is represented, and clarifies the run=true behavior (executes the preview, read-only, row-capped, returns affected count and first rows). This goes well beyond the annotation and is fully consistent with it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is somewhat long but each sentence carries specific value. The core purpose is front-loaded, followed by detailed breakdowns for each statement type and the run flag. It avoids repetition and is structured clearly with line breaks. It could be slightly trimmed but remains efficient for the complexity it covers.

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

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

The description is thorough for a complex tool that handles three statement types and two flags. It explains the transformation, the read-only nature, the return values (affected-row count and first rows when run=true), and the server's inability to apply writes. It does not cover potential errors or edge cases, but given no output schema, it sufficiently covers what the agent needs to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain 'run' (default false, if true executes preview) and 'changed_only' (hides no-op rows) clearly. It also implicitly defines 'sql' as the write statement. However, it does not explain 'params' (bind parameters) or 'connection' (target connection), which are left to schema defaults. Given the tool's core parameters are covered, a 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: dry-run a write (UPDATE/DELETE/INSERT) by converting it to a read-only SELECT and returning affected row counts. It distinguishes itself from siblings like run_query (which actually executes) and explain_query (which explains plans) by emphasizing that the write is never sent to the database.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly tells when to use it: when you want to preview the effect of a write without applying it. It also explicitly states a limitation ('This server cannot apply the write; hand the reviewed statement to the user to run themselves'), which guides the agent to not attempt actual execution. However, it does not explicitly name alternative tools or exclusions (e.g., use run_query for actual execution), so a clear alternative comparison is missing.

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