mysql_legacy_insert

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

Annotations already mark destructiveHint=true and readOnlyHint=false, and the description reinforces this by noting that 'INSERT ... ON DUPLICATE KEY UPDATE is accepted and can overwrite existing rows.' It also discloses the return values (insertId and affectedRows) and the exact one-statement limit. Everything the agent needs to know about side effects and behavior is covered without contradicting the annotations.

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?

Two sentences. The first states the core function and the flag, the second covers return values, the destructive edge case, and routing to siblings. No filler, every sentence earns its place, and the most important constraints are front-loaded.

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 single-parameter tool with no output schema, the description provides all necessary context: the exact operation, the environment flag, return values, the destructive case, and which sibling to use for other operations. An agent can safely call this tool without needing to inspect anything else.

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 already gives 100% coverage for the single sql parameter ('One MySQL INSERT statement.'). The description adds context beyond that: it clarifies the statement must be exactly one INSERT, mentions the special ON DUPLICATE KEY UPDATE variant, and points out the flag requirement. This goes beyond the schema's minimal description, so a 4 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 opens with a precise verb–resource pair: 'Runs exactly one INSERT supplied in sql.' It clearly distinguishes this tool from siblings by naming the alternatives for UPDATE/DELETE/DDL and specifying the exact scope (one INSERT). The 'exactly one' qualifier and the ON DUPLICATE KEY UPDATE clause add specificity beyond a generic 'insert' description.

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?

Explicitly states when to use it: 'For UPDATE/DELETE/DDL use mysql_legacy_update, mysql_legacy_delete, or mysql_legacy_ddl.' Also discloses a prerequisite/guardrail: 'Off unless MYSQL_LEGACY_ALLOW_INSERT=true', which tells the agent a required environment condition. Both pieces are direct and leave no ambiguity about routing.

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