db_write

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses refusal-by-default, the write-grant plus deployment-enabled precondition, the ban on DDL and multi-statement input, the exact return shape, and the governance-plane side effect. This is exceptionally transparent for a mutation tool.

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: the operation is stated first, followed by crucial governance constraints and return information. Every sentence earns its place; there is no filler or redundant restatement of the tool name.

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 one parameter, no output schema, and no annotations, the description covers prerequisites, allowed and forbidden input forms, return fields, and side effects. It does not define possible values of target or refusal, and it offers no example, but an agent can invoke the tool correctly with the information provided.

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 has only one required parameter, sql, with 0% description coverage, so the description must compensate. It does by constraining sql to a single INSERT/UPDATE/DELETE and explicitly banning DDL and multi-statement input. It could add formatting or examples, but the one-parameter surface is small and the key semantic constraints are clear.

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 a specific verb ('Execute') and resource ('a single INSERT/UPDATE/DELETE'), and it explicitly distinguishes db_write from db_read by noting that read/write is governed separately. This clearly identifies the tool as the DML write counterpart and separates it from siblings without opening schemas.

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 names db_read as the read-side alternative and gives clear exclusions: DDL and multi-statement input are never executed, so db_write is for single DML statements only. It does not explicitly say 'use db_write for writes and db_read for reads,' and it does not mention get_schema, but the intended usage is strongly implied.

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