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

Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds critical behavioral context: operations are off by default (MYSQL_LEGACY_ALLOW_DDL=true required), DROP and TRUNCATE are irreversible, and the tool rejects certain statement types. This goes beyond the structured annotations and gives an agent essential safety information.

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, front-loads the core action and constraint, and every sentence contributes necessary information: the exact operation, the enabling flag, irreversibility warnings, exclusions, and sibling routing. No filler or repetition of schema details.

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 tool's destructive nature, the description covers all critical aspects: operation scope, enablement condition, irreversibility, unsupported objects, and alternative tools. There is no output schema, but for a mutation tool, return values are less critical; all necessary invocation details are present.

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 fully covers the single parameter 'sql' with a description, so baseline is 3. The description adds value by reinforcing that exactly one table-level DDL statement is expected and enumerating accepted/rejected forms, which helps the agent construct valid input beyond the schema's generic description.

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 clearly identifies the tool as executing a single table-level DDL statement (CREATE, ALTER, DROP, TRUNCATE, RENAME) in SQL. It explicitly scopes the operation to table-level and lists the accepted statement types, distinguishing it from other tools by naming the purpose and exclusions.

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?

The description provides explicit usage guidance: it states when to use this tool (for table-level DDL), when to use alternatives (row changes via mysql_legacy_insert/update/delete), and an important environmental condition (MYSQL_LEGACY_ALLOW_DDL=true). It also includes exclusions (DROP DATABASE, views, indexes), making routing clear for an agent.

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

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

Beyond the annotations, the description discloses the safety requirement that WHERE cannot be disabled, the feature-flag/authorization condition, and the return value (affectedRows). These details add meaningful behavioral context beyond readOnly/destructive hints.

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, with each sentence earning its place: the core action, safety constraint, feature flag, return value, and truncate alternative. No filler or redundancy.

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 destructive tool with no output schema, the description is complete: it covers behavior, safety, availability, return value, and the relevant alternative. An agent has enough context to invoke it correctly.

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 covers the sql parameter well, so the baseline is 3. The description adds extra semantics by noting the statement must be a single DELETE and that the WHERE clause cannot be disabled, reinforcing safety and usage nuances not fully explicit in the schema.

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 clearly states the tool's specific action: 'Runs exactly one DELETE supplied in sql.' It also adds clarifying constraints like 'WHERE is required and cannot be disabled' and differentiates from mysql_legacy_ddl for TRUNCATE, which distinguishes it from sibling tools.

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 explicitly explains when the tool is available ('Off unless MYSQL_LEGACY_ALLOW_DELETE=true'), imposes a mandatory WHERE clause, and directs users to mysql_legacy_ddl for TRUNCATE instead of a WHERE-less DELETE. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds value beyond that by revealing the specific SQL operation (SHOW FULL COLUMNS), the exact output fields, and clarifying it is not the tool for schema-level or index-level details. This is richer context than a bare annotation baseline.

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?

Three sentences, zero filler. The first sentence front-loads the primary function and output; the next two sentences provide targeted routing to alternatives. Every sentence earns its place.

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 only two required parameters, full schema coverage, and annotations covering safety, the description supplies the missing piece — what the result contains (columns, type, nullability, keys, comments, collation). No output schema exists, so the description reasonably fills that gap. Nothing needed for correct invocation 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?

Schema description coverage is 100% — both database and table have clear descriptions with length constraints. The description merely echoes 'database.table' without adding new semantic details about either parameter, so it stays at the baseline for fully documented schemas.

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 ('Lists columns'), a specific resource ('database.table'), and the underlying mechanism (SHOW FULL COLUMNS), then enumerates the metadata fields returned. It also distinguishes itself from two siblings by name, so an agent can clearly tell it apart.

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 this tool ('Use this for per-column metadata') and names the exact sibling alternatives for other use cases (show_create_table for full CREATE TABLE text, list_indexes for index column order). No inference required.

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

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.

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description doesn't need to repeat those. It adds value by disclosing the default hiding of system databases and the override via parameter or environment variable (MYSQL_LEGACY_HIDE_SYSTEM_DATABASES=false). This is behavioral context beyond the schema. It does not contradict any 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?

The description is two sentences, front-loads the primary action, and includes all essential details (behavior, override, next step, exclusions) with zero waste. Every sentence earns its place.

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 simple list tool with one optional parameter and no output schema, the description is complete: it states the action, the default behavior, the override, what it doesn't do, and the recommended follow-up. Nothing an agent needs to call it correctly 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?

Schema description coverage is 100%, so the parameter is fully documented in the schema. The tool description adds the default behavior (system databases hidden unless include_system_databases=true or env var set) which is not explicitly in the schema, clarifying the parameter's effect in context. This enriches the parameter semantics beyond the schema alone.

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 and resource ('Lists database names via SHOW DATABASES') and explicitly differentiates from siblings by noting it does not list tables or columns. It also points to the next step in the workflow (mysql_legacy_list_tables), making its purpose 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?

The description implies when to use it (when you need database names) and gives a concrete next step ('Then pass a name to mysql_legacy_list_tables'), which is useful guidance. It also clarifies that it does not cover tables/columns, indirectly steering the agent toward alternatives. However, it doesn't explicitly state when not to use it or name alternative tools for other tasks, though the sibling context and the hint are sufficient.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by disclosing the implementation (`SHOW INDEX`) and the specific fields returned (key name, columns, uniqueness, type), which is useful context beyond the annotations. No contradictions with 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 compact sentences convey purpose, implementation, output contents, and routing to alternatives. There is no filler or redundant repetition of schema or annotation info, and the core purpose is 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?

Despite having no output schema, the description compensates by naming the returned fields and explaining the SHOW INDEX basis. It covers the invocation pattern, the read-only nature, and explicitly directs to sibling tools for other introspection needs, making it complete enough for an agent to call correctly.

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%, and both `database` and `table` already have clear schema descriptions with length constraints. The description only restates the 'database.table' pattern and adds no new parameter-level meaning. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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 names the specific verb ('Lists'), the exact resource ('indexes for database.table'), and the implementation method ('SHOW INDEX') with the key output fields. It also distinguishes itself from sibling tools by stating 'Use this for keys' and referencing describe_table/show_create_table for other use cases.

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 explicitly says when to use this tool ('Use this for keys') and names the alternatives with the conditions for choosing them ('For column types use mysql_legacy_describe_table; for full DDL use mysql_legacy_show_create_table'). This gives an agent unambiguous routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context beyond annotations by specifying that it lists both base tables and views, operates on exactly one database, and uses SHOW FULL TABLES. This is meaningful additional transparency.

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 with the core action and mechanism before moving to sibling routing. Every sentence earns its place, and the structure makes it easy for an agent to quickly parse purpose and alternatives.

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 simple read-only list operation with one well-documented parameter, the description covers the operation, scope, mechanism, and related sibling tools. No output schema exists, but the description clearly implies the returned content (base tables and views) through SHOW FULL TABLES. Nothing essential is missing for correct selection and invocation.

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 the schema already fully documents the single required 'database' parameter as a MySQL database name with length constraints. The description mainly repeats 'Pass database' and adds the context that this parameter selects the target database, but does not add substantial semantic detail beyond the schema.

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?

Description states a specific verb and resource: 'Lists base tables and views in one database via SHOW FULL TABLES FROM database.' It clearly distinguishes this tool from siblings like mysql_legacy_list_databases, mysql_legacy_describe_table, and mysql_legacy_show_create_table by naming the exact scope and mechanism.

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?

The description explicitly tells the agent to pass the database parameter and routes related tasks to specific siblings: describe_table for column types, show_create_table for CREATE TABLE text, list_indexes for keys, and list_databases for listing databases first. This is explicit when-to-use guidance with concrete alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint:false, covering the safety profile. The description adds the exact query executed and the return shape {connected, version}, which goes beyond annotations and clarifies expected behavior. It does not describe failure behavior, but for a ping-style tool this is a minor gap.

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 three short sentences, each carrying distinct value: what it executes and returns, when to call it, and what to use for other needs. No redundant or filler wording. Every sentence earns its place.

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 zero-parameter ping tool with complete safety annotations, the description covers purpose, usage timing, return value, and key alternatives. The absence of an output schema is mitigated by the explicit return object. No critical information is missing for correct selection and invocation.

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 tool has zero parameters, so the baseline is 4. The description does not need to explain parameters, and the empty schema already confirms none are required. It also implicitly reinforces that the tool takes no arguments by focusing entirely on the connection check.

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 clearly identifies the tool as a MySQL connection check using a specific SQL statement (SELECT VERSION()) and a defined return object. This distinguishes it from siblings focused on schema, data, or DDL. The verb 'Checks' plus the resource 'MySQL connection' makes the purpose 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?

The description explicitly instructs to 'Call this first after connecting', establishing a clear usage ordering. It also names alternatives for schema access (mysql_legacy_list_tables) and row data (mysql_legacy_select), so an agent knows when not to use this tool. This is ideal routing guidance.

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

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

Beyond the readOnly/idempotent/not-destructive annotations, it discloses result truncation via two environment variables, the read-only transaction wrapping on MySQL 5.6.5+, and the disable flag. These are non-obvious behaviors that materially affect results and are not visible in the schema or 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?

Three dense sentences, each carrying distinct information: operation constraints, behavior/transaction semantics, and sibling routing. No filler or repetition of annotation or schema content.

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 schema, existing annotations, and the absence of an output schema, the description covers what SQL is allowed, how results are bounded, transaction behavior, and when to use sibling tools. An agent has enough to select and invoke this tool safely and correctly.

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 coverage is 100% for the single sql parameter, but the description enriches the parameter semantics by specifying it must be exactly one SELECT, rejecting SELECT INTO and locking reads, and noting MySQL 5.1 compatibility. This goes beyond the schema's one-line description, though the schema already carried the core type and length 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 a specific verb ('Runs') with a precise resource ('exactly one SELECT supplied in sql') and immediately distinguishes itself from siblings by rejecting SELECT INTO and locking reads. It clearly identifies this as the SELECT tool among the mysql_legacy_* siblings.

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 explicit routing: use mysql_legacy_describe_table for columns, mysql_legacy_show_create_table for CREATE TABLE, and insert/update/delete for writes. It also explains exclusions (SELECT INTO/locking reads), so an agent knows exactly when this tool is and is not appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered without needing restatement. The description adds meaningful behavioral context by specifying that it returns the DDL text and a parsed charset. No contradiction exists between description and 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?

The description is three concise, purposeful sentences: core behavior first, usage directive second, alternatives third. Every sentence earns its place and there is no filler or repetition.

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?

This is a simple two-parameter read-only tool with full schema coverage and clear sibling alternatives. There is no output schema, but the description covers what is returned (DDL text plus parsed charset). An agent has everything needed to select and invoke the tool correctly.

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 input schema covers both parameters at 100%: each has a name, type, length constraints, required status, and description. The description adds only the implicit database.table qualification, which is minor. With full schema coverage, baseline 3 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 states the specific verb 'Returns' and the exact resource 'SHOW CREATE TABLE for database.table', plus the 'parsed default charset' as additional output. It also explicitly differentiates the tool from mysql_legacy_describe_table and mysql_legacy_list_indexes, making its purpose 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?

The description gives direct usage guidance: 'Use this for DDL text.' It then names the precise alternatives and their conditions: per-column types/collation go to mysql_legacy_describe_table, and unique/non-unique keys go to mysql_legacy_list_indexes. This fully routes an agent to the correct tool.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, and the description adds substantial context: WHERE is required and cannot be disabled, the tool is off unless MYSQL_LEGACY_ALLOW_UPDATE=true, exactly one statement is executed, and it returns affectedRows and changedRows. No contradiction with 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?

Five short sentences, every one load-bearing: the operation, the mandatory WHERE constraint, the environment flag, return fields, and the appropriate alternative for truncation. Information is front-loaded and there is no filler.

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?

Despite having no output schema, the description names the return fields (affectedRows and changedRows). It also covers safety guards, execution constraints, and the key misuse case. For a one-parameter SQL execution tool, this is complete enough for an agent to invoke it correctly.

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 input schema already fully describes the sql parameter as 'One MySQL UPDATE statement with a WHERE clause,' and schema coverage is 100%. The description restates the one-statement and WHERE requirements but adds no new parameter-level syntax or formatting guidance, so 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?

The description states a specific verb and resource: 'Runs exactly one UPDATE supplied in sql.' It also distinguishes itself from siblings by explicitly saying table emptying should go through TRUNCATE via mysql_legacy_ddl, not this tool.

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 implies when to use it (whenever an UPDATE is needed) and explicitly gives a when-not/alternative: 'To empty a table use TRUNCATE via mysql_legacy_ddl, not a WHERE-less UPDATE.' This is direct decision guidance.

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