run_write_query

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

Annotations already declare destructiveHint=true, so the dangerous nature is known; the description adds the meaningful gate that write mode must be enabled. It does not disclose transaction behavior, reversibility, whether DDL is irreversible, or how failures surface — relevant for a destructive tool with only one annotation.

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?

A single front-loaded sentence that earns its place, with the write-mode condition placed where it is immediately visible. The internal '(FR-006)' spec reference is dead weight for an agent.

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?

For a destructive write tool with no output schema, the description covers the enablement gate but omits what is returned (row counts? result rows for DDL?), whether execution is transactional, and how role-scoped writes behave. Adequate but with evident gaps an agent would want closed.

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 100%, so sql, role, and params are already documented in the schema, including that role applies to this write query only. The description adds no parameter-level meaning beyond that; baseline 3 applies.

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?

States a specific verb (Execute) and a precise resource class (INSERT/UPDATE/DELETE/DDL statements), which cleanly separates it from the read-oriented run_query sibling. The '(FR-006)' tag adds nothing but the core statement is unambiguous.

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 gives one real precondition — write mode must be enabled — which is useful gating context. However it never explicitly says 'for SELECT use run_query' nor explains what happens if write mode is off (error? silent rejection?), leaving the agent to infer the alternative.

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