propose_change

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

No annotations are provided, so the description carries the full disclosure burden, and it excels at this. It reveals that the statement is actually executed in a transaction and rolled back, that nothing is written, and that the returned id is single-use and expires. These are exactly the behavioral traits an agent needs to understand to use the tool safely.

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 compact and front-loaded, covering purpose, mechanics, follow-up guidance, and constraints in a few tight sentences. No filler or redundant restatement of the tool name exists.

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?

Given the single parameter and the rich behavioral detail provided, the description is complete for selecting and using the tool correctly. It explains the write-preview workflow, the follow-up confirm_change step, and the expiry behavior. An output schema exists to cover return-value details, so nothing critical is missing.

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?

The schema only defines sql as a string, but the description adds critical meaning: it must be a single INSERT, UPDATE, or DELETE statement against an existing table, with a mandatory WHERE clause for UPDATE and DELETE. This goes well beyond the raw schema and fully documents the parameter's constraints.

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 states exactly what the tool does: preview a write without committing it and return a change_id. It distinguishes itself from sibling confirm_change by labeling this as the preview step, and from run_query by focusing on write statements.

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?

It clearly explains when to use the tool: before committing a write, with the preview shown to a human and confirm_change called afterward. It also gives explicit constraints on accepted statements (single INSERT/UPDATE/DELETE, WHERE clause required for UPDATE/DELETE), though it does not enumerate alternatives such as when to prefer run_query.

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