query

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

Beyond the annotations, it discloses truncation behavior at MYSQL_MAX_ROWS and the different return shape for writes ({rows_affected, last_insert_id}), both of which an agent needs to reason about result handling. The caveat that writes are possible when the server runs with MYSQL_ALLOW_WRITE=true adds context the readOnlyHint annotation cannot express, though it sits in mild tension with a blanket readOnlyHint=true; it does not contradict the annotation for the default configuration. Missing: error behavior and whether multi-statement input is rejected.

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 dense sentences plus a conditional clause; return shape and truncation semantics are front-loaded before the read-only caveat. Nothing is filler and no sentence merely restates 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?

With no output schema, the description carries the burden of describing returns and does so for both read and write paths, including the truncation flag. It falls short only on the `database` parameter and on failure modes, which are meaningful for a tool that executes arbitrary SQL.

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 for two undocumented parameters, and it only partially does. 'One SQL statement' usefully constrains the `sql` parameter's expected shape, but the `database` parameter (default null) is never explained at all — an agent must guess whether it overrides the session's current database.

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 specific verb and resource ('Run one SQL statement'), which is unambiguous and clearly distinct in kind from the schema-introspection siblings list_databases/list_tables/describe_table. It never explicitly names those siblings as alternatives, but the gulf between 'arbitrary SQL' and 'enumerate schema objects' is large enough that an agent will not confuse them.

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 a real constraint ('one SQL statement', read-only unless MYSQL_ALLOW_WRITE=true), which implicitly tells the agent this is the general-purpose path. However, it offers no explicit routing such as 'use describe_table instead of DESCRIBE via SQL', leaving the agent to infer when to prefer the specialized siblings.

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