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

Annotations already declare readOnly=false, destructive=true, idempotent=false, and the description adds genuinely new context beyond them: no undo is possible, prior stats are captured for audit, and a brief read lock is held during sampling. That is meaningful operational disclosure, though it stops short of explaining expected duration or return format.

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?

Front-loaded with the operation and risk tag, followed by three tight behavioral sentences and a compact Args block. Nearly every sentence earns its place; the bracketed tags are slightly redundant with the annotations but cheap.

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 mutating tool with no output schema, the description covers the essentials: irreversibility, lock behavior, audit capture, and a safe preview path. It could say more about cost or expected effect on query planning, but an agent has enough to call 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?

Schema description coverage is 0%, so the description must carry the load and it does: all three parameters are documented with real meaning (table optionally schema-qualified, dry_run previews, target names a config target and defaults when omitted). The only gap is that 'target from config' is not further elaborated.

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 and resource ('ANALYZE TABLE to refresh index statistics') plus a risk/write tag, so the agent knows exactly what operation this is. It does not, however, differentiate itself from the sibling optimize_table, which an agent might confuse with a statistics-refresh operation.

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?

Usage is only implied: the description notes that dry_run=True previews the operation, which tells the agent a safe path exists but not when this tool is preferred over optimize_table or index_stats. No when-not-to-use or alternative routing is given.

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?

The readOnlyHint annotation already establishes the safety profile, and the '[READ]' prefix merely restates it. The description does add value by enumerating the data surfaced (GTID mode, downstream replicas), but it says nothing about privileges required, whether it is safe to poll, or freshness of the replica data.

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 tight lines with the core capability front-loaded. The '[READ]' prefix is mildly redundant with the readOnlyHint annotation, but it costs little.

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 explaining what comes back, and it only gestures at the categories (config, GTID, replicas) without indicating the shape of the response. Adequate to identify the tool, thin for interpreting its output.

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 0% and the single 'target' property has no description in the schema. The description compensates by explaining that it is a 'Target name from config' and that omitting it selects the default, which is exactly the semantics an agent needs.

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 resource and dimensions reported: binary-log configuration, GTID mode, and connected downstream replicas. That is far more informative than a bare 'status' label, though it never explicitly distinguishes itself from the nearby replica_status 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?

There is no guidance on when to reach for this over replica_status, show_status, or show_variables, nor any stated prerequisites. The only usage hint is the parameter note 'omit for the default', which covers invocation but not tool selection.

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?

readOnlyHint=true already declares this a safe read, so the '[READ]' prefix adds nothing new. The description does add the useful behavioral detail that the output compares counters against max_connections, but says nothing about thresholds, cost, or freshness of the counters. Modest added value above 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?

Front-loaded one-line purpose followed by a compact Args block; every sentence earns its place. The '[READ]' tag is slight redundancy against readOnlyHint=true, but the payload is tight.

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-optional-param diagnostic with no output schema, the description tells the agent what is measured and how to address the instance. It is adequate, though it never describes the shape of the returned counters, which an agent may want before deciding to call it.

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 carry the param burden, and it does: 'target: Target name from config; omit for the default' explains both the value source and the default behavior. It stops short of naming an example target or explaining fallback failure, but it is far better than the bare 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?

States a specific verb and resource — connection counters compared against max_connections — plus the motivation (exhaustion early warning). It is clear what the tool inspects, but it does not distinguish itself from near-neighbors like overview, show_status, or show_variables that also surface connection info.

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 parenthetical 'exhaustion early warning' implies the usage context (capacity monitoring), but there is no explicit when-to-use statement and no named alternative for related diagnostics. The agent must infer that this is the right tool versus overview or show_status.

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 carry readOnlyHint=false and destructiveHint=true already, but the description adds meaningful context beyond them: it is reversible via undo, the harness records an undo that drops exactly this index, and dry_run previews. The (table, name) return value contract is disclosed even without an output schema.

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?

Front-loaded with the action and risk tag, then the undo contract, then the alternative mode, then a clean Args list. Slightly long but every section earns its place; no filler sentences.

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 7-param, zero-coverage, no-output-schema write tool, the description covers mode selection, reversibility, preview, and return value well. Minor gap: no explicit statement about failure modes (e.g. duplicate index name) or permission requirements.

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, and it does: it documents every parameter's meaning, mutual exclusivity (definition vs table/columns), auto-generation of name, uniqueness semantics, and the optional target. This is exactly what an undocumented 7-param schema needs.

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+resource ('Create an index') and immediately differentiates from the sibling drop_index by naming it in the undo mechanics. The behavior tags [WRITE][risk=medium] and the reversibility statement let an agent place it precisely among DDL 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?

Explains the two mutually exclusive invocation modes (table/columns vs definition) and when to use each, plus dry_run for preview. Does not explicitly route against alternatives like optimize_table or analyze_table, but the mode selection guidance is clear.

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 destructiveHint=true and readOnlyHint=false, but the description adds genuine value beyond them: the reversibility mechanism is spelled out (the exact definition is rebuilt from SHOW CREATE TABLE to build the undo), and the dry-run preview is surfaced. That is exactly the kind of consequence detail an agent needs before mutating state.

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?

Front-loaded with the risk tag and the reversibility guarantee, followed by an Args block. Every sentence earns its place and there is no repetition of the name or obvious restatement.

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?

No output schema exists, and for a destructive 4-parameter tool the description covers the safety posture, the undo pathway, the preview option, and every argument. Nothing material to calling 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?

With 0% schema description coverage, the description carries the full parameter burden and does document all four: table ('optionally schema-qualified'), name, dry_run (preview semantics), and target ('from config; omit for the default'). The coverage is complete but terse – no format examples for index or table identifiers.

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+resource ('Drop an index') and immediately qualifies it with a severity tag ([WRITE][risk=high]), so the agent knows the operation class before reading further. It is trivially distinguishable from the create_index sibling and from read-only introspection tools like index_stats.

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 clear operational guidance: a dry_run=True path for rehearsal and the fact that the harness records an undo before the drop. It does not explicitly name an alternative tool or state when-not-to-drop conditions, so it falls short of full when/when-not/alternatives coverage.

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 only declare readOnlyHint=true, and the description usefully adds that the statement is planned rather than executed, clarifying there are no side effects. It stops short of describing plan output size or performance cost, but adds genuine context beyond the 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?

Front-loaded with the core purpose, followed by a concise clarification and compact parameter list. There is minor redundancy between the '[READ]' tag and the readOnlyHint annotation, but no wasted prose.

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 states the return value (a JSON execution plan) and covers both parameters, so an agent has what it needs to call it correctly. Minor gaps remain around target resolution and output volume.

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 carries the full burden, and it does so: sql is defined as 'a single SQL statement to EXPLAIN' and target as a 'target name from config' that defaults when omitted. This compensates for the empty schema descriptions well, though it doesn't clarify target format or valid values.

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 and resource: it returns the JSON execution plan for a given SQL statement using EXPLAIN FORMAT=JSON. The intent is unmistakable, though it doesn't distinguish itself from diagnostic siblings like slow_query_rca or top_queries.

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 line 'The statement is planned, not executed' implies a dry-run/analysis use case, which guides the agent to use it when it wants the plan without side effects. However, it never names when to prefer it over alternatives or states prerequisites, so guidance is only implied.

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, so the safety profile is covered (the [READ] tag merely reinforces it). The description adds genuinely useful behavior: the injected-vs-live data path, and that each recommendation cites its numbers. This goes beyond what the annotations provide, though it omits any note on the shape of the returned ranking.

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?

Front-loaded with the [READ] marker and the one-line purpose before the usage and Args sections. The Args block largely restates the inline prose, adding slight redundancy, but nothing is padded and the ordering is sensible.

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 read-only, no-output-schema tool this covers purpose, data paths, and all three parameters adequately, and hints at the output ('cites its numbers'). It is near-complete; the only minor gap is what the ranked output actually contains and how target selection is configured.

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 carry the burden, and it does: tables (injected rows, omitted means pulled live), limit (count pulled when not injected, default 50), and target (config target name, omit for default). Every parameter gets meaning beyond the bare schema types.

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 and resource ('Rank tables by reclaimable data_free') and the concrete goal ('into OPTIMIZE TABLE candidates'). It also distinguishes itself from the sibling table_fragmentation by positioning that tool as its data source, so an agent can tell the two 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 routes between two modes: pass 'tables' for pure/offline analysis, or omit to pull the worst-fragmented tables live. The relationship to table_fragmentation is named. It does not, however, state when to prefer this over calling table_fragmentation or optimize_table directly, so guidance stops short of full when/when-not coverage.

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?

readOnlyHint=true already declares the safety profile, and the '[READ]' prefix merely restates it. It adds the return-content description (column lists, cardinality) which is useful since there is no output schema, but discloses nothing about auth, cost, or limits.

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?

Front-loaded with the purpose and compact overall. The '[READ]' marker is wasted tokens given readOnlyHint=true, but the size is well matched to a single-parameter tool.

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 one-parameter read-only tool, the description covers what it returns and how to target it. With no output schema it usefully sketches the return shape, leaving only minor gaps around scope or filters.

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 0%, so the description carries the burden, and it does explain the lone parameter: 'Target name from config; omit for the default.' That clarifies the meaning and default behavior beyond the bare string 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?

States the resource clearly ('Per-index column lists and cardinality') and gives a purpose ('selectivity screening'). An agent can distinguish it from sibling index tools like unused_indexes and redundant_indexes, though it never names a sibling explicitly.

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 parenthetical '(selectivity screening)' implies the diagnostic context for using this tool, but there is no explicit when-to-use, when-not, or routing to alternatives such as unused_indexes or redundant_indexes.

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?

Goes well beyond the annotations (which only flag write/destructive/non-idempotent): discloses there is no inverse, that the session survives, that user/host/query are captured for audit, that dry_run previews, and critically that it refuses its own session id even under dry_run. The self-refusal guard is a non-obvious safety behavior an agent must know before invoking.

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?

Front-loaded with the [WRITE][risk=high] tag and the core action, then behavior, then Args. Every sentence earns its place, though the Args block partly restates facts already implied above (dry_run). Slight redundancy keeps it from a 5.

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, non-idempotent, no-undo mutation with no output schema, the description covers reversibility, side effects, safety guard, and preview mechanism. An agent has everything needed to call it correctly and safely.

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 carries the full burden and does: session_id (sourced from list_sessions), dry_run (preview without cancelling), and target (config name, omit for default). All three parameters are given meaning beyond their bare names and defaults.

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 and resource ('Cancel a session's running statement (KILL QUERY)') and immediately scopes it: only the current statement is aborted, the session stays connected. This differentiates it from the sibling kill_session without the agent needing to open either schema.

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?

Implies the right context via 'the session stays connected; only its current statement is aborted,' which routes an agent away from kill_session when it only wants to abort a query. It also specifies session_id comes 'from list_sessions,' linking to a sibling for discovery. It stops short of explicitly naming kill_session as the alternative and when to prefer it, so not a full 5.

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 destructiveHint=true and idempotentHint=false, yet the description adds substantial context beyond them: the kill is irreversible with no undo offered, the session's user/host/query is captured for the audit trail, and it refuses this tool's own session id (even under dry_run). This is exactly the behavioral disclosure an agent needs for a high-risk write.

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?

Front-loaded with the action and risk tag, then behavior, then a structured Args block. Slightly redundant — 'No safe inverse' and 'a kill cannot be undone, so no undo is offered' restate the same point — but overall efficient.

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 3-param destructive tool with full annotation coverage and no output schema, the description covers irreversibility, audit capture, self-session refusal, and the dry_run preview path. It does not describe the response/error shape, but annotations and the absence of an output schema make that a minor gap.

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 carry the load, and it documents all three parameters: session_id (with its source, list_sessions), dry_run (preview semantics), and target (config name, omit for default). Coverage is complete though the per-parameter notes are terse.

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 and resource — 'Terminate a session (KILL CONNECTION)' — which clearly separates it from kill_query by resource type. It does not name any sibling explicitly, but the verb+resource is unambiguous. Strong but short of the explicit sibling differentiation that earns a 5.

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?

Implied usage is present: the session_id comes 'from list_sessions' and dry_run=True is offered as a preview path. However, there is no explicit guidance on when to use kill_session versus kill_query or other siblings, so the alternative-selection question is left to inference.

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?

The readOnlyHint annotation already establishes the safety profile, and the '[READ]' tag merely restates it. The description does add useful behavioral detail beyond the annotation — the sort order ('largest first') and the fact that sizes are broken into data vs index — but says nothing about limits, pagination, or cost.

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?

Front-loaded with the core purpose in the first clause, and the Args block is brief. The '[READ]' tag and 'Args:' header are slightly redundant given the annotation and schema, but there is no real padding.

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 steps in to describe the return shape (table count plus data/index size) and ordering, which is what an agent needs to consume results. It is complete for a simple read-only list tool, missing only pagination/limit behavior.

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 0%, so the description must carry the parameter burden, and it does: 'target: Target name from config; omit for the default' explains both the meaning and the omission behavior for the single optional param.

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 and resource ('User schemas') plus the returned fields (table count, data/index size) and ordering (largest first). It is clearly distinguishable from size-oriented siblings like table_sizes or list_engines, though it never names an alternative.

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?

Usage is only implied: an agent can infer this enumerates databases, but there is no statement of when to prefer it over table_sizes, overview, or list_engines, and no exclusions or prerequisites.

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, so the '[READ]' prefix adds nothing beyond structured data. The description does add useful behavioral context via the 'SHOW ENGINES' mapping, telling the agent what backend call is made and what information comes back (engines + default), but it says nothing about permissions, connection requirements, or result shape.

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?

Front-loaded with the purpose and backend mapping, followed by a single compact arg note — no filler sentences. The '[READ]' tag is slightly redundant given the annotation, but overall it is tight and appropriately sized for a one-parameter read tool.

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, zero-required-parameter tool with no output schema, the description covers what the tool returns (engines and the default), the optional argument, and its default behavior. Nothing essential to correct invocation is missing; only edge details like error behavior under an unknown target are absent.

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 has to carry the parameter burden, and it largely does: it names 'target', explains it comes from config, and states that omitting it falls back to the default. That is real semantic value beyond the bare `anyOf string|null` schema, though it doesn't say what a target name looks like or how to discover valid values.

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+resource ('Storage engines') plus the discriminating detail 'which is the default', and maps to the underlying command (SHOW ENGINES). No sibling covers engines, so sibling differentiation isn't needed. It stops short of 5 only because the phrasing is terse and could be read as a label rather than a full statement of intent.

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?

Usage is implied — an agent calls this to enumerate storage engines — and the only explicit guidance ('omit for the default') concerns the target parameter rather than when to choose this tool. There is no competing sibling to exclude, so the missing when/when-not framing is a modest gap rather than a serious one.

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?

readOnlyHint=true already covers the safety profile, and the '[READ]' tag merely repeats it. The description does add value by disclosing what it returns (per-command counts) and that it flags sleeping sessions, but it says nothing about limits, row counts, or whether listing is expensive on a busy server.

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?

Short, front-loaded, and organized into a one-line summary plus a flagged behavior and an Args block. No filler sentences; only minor redundancy in the '[READ]' tag duplicating the annotation.

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 and only two optional parameters, the description covers purpose, return content, and both params adequately. Residual gaps are limits/pagination and target resolution, which are minor for a simple read-only listing tool.

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, and it does: include_sleeping is explained with its default (True) and target is explained as a config name to omit for the default. Both parameters are covered, though 'target' syntax/resolution is not spelled out.

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 and resource ('Current sessions (processlist)') plus the return shape ('per-command counts'), which distinguishes it from sibling diagnostics like connection_stats. It does not explicitly name a sibling it replaces, so it stops short of a 5.

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?

Usage is only implied: the parenthetical 'connection-pool leak suspects' hints at a sleep-detection scenario, and the arg notes explain defaults, but there is no statement of when to choose this over connection_stats or long_running_queries.

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 and the '[READ]' tag reinforces it, so the safety profile is covered. The description contributes the ordering behavior ('oldest first'), which is genuinely useful, but says nothing about result limits, truncation, or whether the same transaction can appear across calls — gaps that matter for a monitoring 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?

Front-loaded with the mode tag and the resource, then a compact Args block. Two lines carry the whole definition with no filler, though the Args formatting is slightly verbose for a single optional parameter.

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 no-required-parameter, read-only listing tool with no output schema, the definition tells the agent what is returned (open transactions), in what order, and what the sole parameter means. It lacks detail on returned fields or result-size behavior, which keeps it from a 5.

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 schema only exposes a bare 'target' property with a null default. The description compensates by explaining that it is a target name from config and that omitting it uses the default, which is exactly the semantics an agent needs.

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 and resource (list open InnoDB transactions) plus meaningful scope qualifiers: 'oldest first' and the diagnostic intent 'stuck-transaction hunting'. It does not explicitly name which sibling to use instead, so it stops short of 5.

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 parenthetical '(stuck-transaction hunting)' implies the diagnostic scenario, but no explicit when-to-use/when-not or alternatives are given. An agent could reasonably wonder whether lock_waits, lock_wait_rca, or long_running_queries is the better starting point in the same situation.

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?

The readOnlyHint annotation already establishes a safe read-only profile, so the description adds useful context on top: it discloses that the live pull is 'flavor-branched', that it parses the LATEST DETECTED DEADLOCK section, and that include_deadlock defaults to True. It does not discuss permissions or output shape, but those are largely covered.

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?

Front-loads the core action in the first sentence, then the mode selection, then an Args block. Efficient and well organized, with only minor redundancy between the prose and the Args listing.

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 correctly explains what is produced (wait-for tree, root blocker, deadlock section) and how each input mode behaves. Given the read-only annotation and three optional params, this is essentially complete for correct 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 0%, so the description carries the full parameter burden. It documents all three: 'pairs' with its {blockedId, blockingId, ...} shape and the live-pull fallback, 'include_deadlock' with its default, and 'target' as a config name. This fully compensates for the empty 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?

States specific verbs and resources: builds the InnoDB wait-for tree, names the root blocker, and parses the last deadlock from SHOW ENGINE INNODB STATUS. This clearly distinguishes it from the sibling lock_waits, which surfaces the raw pairs, and the [READ] tag signals the operation class.

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 routes the caller: pass 'pairs' (from lock_waits) for offline analysis, or omit to pull the live graph. It names the sibling that produces the input and gives the condition for each mode, though it stops short of stating when NOT to use this tool versus lock_waits.

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, but the description adds real value beyond that: it discloses the exact data sources (performance_schema.data_lock_waits on MySQL 8.x vs information_schema.innodb_lock_waits on MariaDB) and that behavior is flavor-branched. It does not mention permission requirements or result shape, which keeps it short of a 5.

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?

Front-loaded with a '[READ]' marker and a one-line purpose, followed by the implementation detail and a compact Args block. Every sentence carries information and there is no padding.

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 read tool with no output schema and annotations covering the safety profile, the description covers purpose, data sources, flavor branching, and the sole parameter. The only gap is that, with no output schema, it does not hint at the shape of returned rows.

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 carries the burden and does document 'target' as a config name with a default-when-omitted behavior. That meaning is genuinely absent from the schema. It does not clarify valid target names or matching semantics, so it is not exhaustive.

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 gives a specific verb (reads) and resource (InnoDB wait-for edges, blocked -> blocking session) plus the exact underlying tables. This clearly distinguishes it from generic siblings like list_transactions or overview. It stops short of naming the closely-related sibling lock_wait_rca, so sibling differentiation is implied rather than explicit.

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?

There is no statement of when to use this tool versus alternatives. The overlapping lock_wait_rca sibling in particular is never mentioned, and no exclusions or conditions are given. Usage is only implied by the '[READ]' tag and the subject matter.

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?

readOnlyHint=true already establishes the safety profile, and the '[READ]' tag merely restates it. The description does add ordering behavior ('oldest first'), the semantics of what counts as a match ('active statements running at least min_seconds'), and target defaulting, but says nothing about result limits, pagination, or output columns.

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?

One-line summary followed by a compact two-parameter block; the scoping detail (min_seconds, ordering) is front-loaded. Slight redundancy in restating the default 60 that also appears in the schema, but nothing wasted.

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?

There is no output schema, so the description ideally should hint at the returned columns (session id, query text, elapsed time) or any result cap. Safety is covered by annotations and both params are covered, but the return shape for a listing tool is unspecified.

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 carries the full burden, and it does document both parameters: min_seconds as minimum age in seconds with a default of 60, and target as a config target name omitted for the default. Only weakness is that 'target name from config' doesn't say which config or what valid values exist.

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+resource+scope: active statements running at least min_seconds, returned oldest first. That distinguishes it from aggregated siblings like top_queries or index_stats, but it never names an alternative such as slow_query_rca or list_sessions, so sibling differentiation is left to the agent.

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?

Usage is implied by the scope ('active statements', 'minimum age'), so an agent can infer this is for spotting currently running long queries. However, there is no explicit when-to-use or when-not-to-use guidance and no pointer to slow_query_rca or top_queries for the historical/aggregate case.

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?

Goes well beyond the annotations by disclosing that there is no undo, that prior size/fragmentation stats are captured for the audit trail, the underlying InnoDB ALTER TABLE ... FORCE mapping, brief lock behavior, and the dry_run preview path. This is exactly the behavioral context a mutating tool needs.

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?

Front-loaded with the tag and one-line purpose, then operational caveats, then args. The Args block mostly restates what the schema shows, which slightly dilutes density, but the added notes (config target, schema-qualified example) earn their 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?

No output schema exists, so the description should ideally say what the call returns; it only mentions that prior stats are recorded, not the result shape of the operation. Otherwise the safety, scheduling, and parameter picture is complete for a 3-param mutating tool.

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 carries the full burden and does it: it explains schema-qualified table naming with an example (shop.orders), the preview semantics of dry_run, and that target comes from config and defaults when omitted. All three parameters gain meaning beyond their bare titles.

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 (OPTIMIZE), the resource (TABLE), and the intent (rebuild, reclaim data_free), plus a severity tag. Sibling analysis tools like table_fragmentation and fragmentation_analysis are clearly distinguished from this mutating operation.

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?

Gives real operational context: schedule off-peak for hot tables, use dry_run=True to preview, and it warns there is no undo. It stops short of explicitly naming the sibling analysis tools (e.g. check table_fragmentation first) that would be the natural 'when-to' pre-step, so no explicit alternatives are given.

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, so the safety profile is covered. The description adds genuinely new behavioral context: each section is 'captured defensively so one failing probe does not sink the rest', i.e. partial-failure resilience and best-effort semantics. That is exactly the kind of trait annotations cannot express.

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?

Front-loaded with the one-line purpose, then a readable enumeration, then a compact Args block. Every element earns its place; only the long mid-sentence list is slightly dense.

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?

No output schema exists, so the description must convey return content, and it enumerates the snapshot's sections. Combined with the documented parameter and the defensive-capture note, an agent has enough to invoke it correctly; rate limits or response size are not addressed but are minor here.

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 0%, so the description must carry the parameter. It does: 'target: Target name from config; omit for the default', explaining both what the value is and the default-omission behavior. Full compensation for the single parameter.

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 resource and scope ('one-shot server health snapshot') and then enumerates exactly what it aggregates: version, flavor, uptime, connection headroom, sessions by command, longest query, most fragmented table, replica role. This is clearly distinguishable from the single-purpose siblings like server_version, connection_stats, and long_running_queries.

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 phrase 'one-shot' and the broad aggregation imply it should be used when an agent wants many health facets at once rather than calling individual probe tools, but no alternative is named and no when-not-to-use condition is given. Usage is implied, not explicit.

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?

readOnlyHint=true already tells the agent this is a safe read, and the '[READ]' tag merely repeats that. The description does add genuine behavioral value by defining the detection rule (leading-prefix duplication), which is not derivable from annotations or schema. It stops short of describing the result shape or how many indexes are returned.

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?

Front-loaded one-line purpose followed by a minimal Args block; nothing superfluous. The '[READ]' prefix is slightly redundant against readOnlyHint=true, but the footprint is small and well structured.

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-required-param, single-target read tool with no output schema, the definition covers what is found and how the target is selected. The missing piece is what a returned redundant index record contains, but that gap is minor at this complexity level.

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 bears the burden — and it meets it: it explains that target is a name sourced from config and that omitting it selects the default. That is real added meaning over a bare string-or-null property with default null, though the exact config key or format is not illustrated.

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 resource (indexes) and the precise criterion that makes them redundant: columns forming a leading prefix of another index. That is far more informative than a restated name. It does not explicitly contrast itself with the sibling unused_indexes or index_stats, which keeps it from a 5.

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 never says when to run this versus unused_indexes, index_stats, or fragmentation_analysis — all plausible neighbors in an index-hygiene workflow. The only usage-adjacent text is the 'omit for the default' note on target, which is parameter guidance, not tool selection 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 declare readOnlyHint=true, and the description's '[READ]' tag is consistent with that. It adds real behavioral context beyond the annotation: flavor-branched queries (MySQL 8.x vs MariaDB), normalization of results, and the empty-result case on a primary. That is meaningful disclosure for a read 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?

Front-loads the purpose in the first sentence and uses short paragraphs, with no filler. The args block is slightly redundant with the schema but remains compact.

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 and a 1-param signature, the definition covers the essentials: what it returns, when it is empty, and how flavor differences are handled. It stops short of describing the shape of the replica-status rows, but the content is adequate for correct 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 coverage is 0%, so the description carries the burden, and it does document the single parameter: 'target: Target name from config; omit for the default.' This explains the naming convention and the default behavior, which the bare schema does not.

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 and resource — '[READ] Replica thread state and lag' — and immediately names the underlying SQL (SHOW REPLICA/SLAVE STATUS). An agent knows exactly what data this returns, though it does not explicitly contrast itself with the sibling replication_lag_rca.

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?

Provides a useful applicability condition ('Empty on a primary/standalone server'), which tells the agent when NOT to expect results. However, it never states when to prefer this over replication_lag_rca or binlog_status, leaving the choice among replication siblings to inference.

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, so the safety profile is covered. The description adds genuinely useful behavior beyond that: omitting 'status' triggers a live pull and the result is 'flavor-branched', which an agent needs to know before calling. No auth or rate-limit detail, but the live-vs-offline distinction is the important trait here.

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?

Front-loads the purpose, then the mode selection, then an Args block. The mode explanation is repeated between the second sentence and the 'status:' arg line, which is mild redundancy, but the layout is otherwise tight and scannable.

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 2-param, no-required, read-only tool with no output schema, the description covers what it does, the two invocation modes, and starts to describe the return ('cause + action'). It could say more about the shape of the diagnosis output, but nothing critical 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 0%, so the description must carry the burden, and it does: it explains that 'status' is an injected replica status record (omitted = pulled live) and 'target' comes from config with a default when omitted. Both parameters are meaningfully documented.

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+resource: 'Map replica thread state / lag / error fields to cause + action', with a [READ] tag. This clearly differentiates it as a diagnostic RCA mapper rather than a raw status reader, though it does not explicitly name the sibling (replica_status) it complements.

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?

Explains the two operating modes ('pass status' for offline analysis vs 'omit' for live pull) and points to replica_status as the source of a status record. However, it gives no guidance on when to choose this tool over the other RCA siblings (lock_wait_rca, slow_query_rca) in the same family.

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 flag destructiveHint=true and readOnlyHint=false, but the description goes well beyond them: it names the exact table truncated, states the operation is irreversible, and explicitly says no undo is recorded (important given undo_list/undo_apply exist as siblings). It also surfaces the preview path. That is real behavioral value beyond the structured 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?

Front-loaded with the [WRITE][risk=medium] tag and the core action, then the destructive detail, then the preview hint, then args. Every sentence carries information; 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?

For a two-parameter destructive tool with no output schema, the description covers the action, irreversibility, the absence of undo, and both parameters. It does not describe what a dry_run call returns, which is a minor omission given no output schema exists.

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 carries the burden, and it does explain both parameters: dry_run ('If True, preview without resetting') and target ('Target name from config; omit for the default'). The only gap is that the accepted format/scope of 'target' is not elaborated.

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 gives a specific verb and resource ('Reset statement-digest accumulators') and immediately names the exact underlying object ('Truncates performance_schema.events_statements_summary_by_digest'). This is unambiguous against siblings like undo_list, undo_apply, or top_queries, which operate on adjacent but distinct state.

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 provides actionable context ('Pass dry_run=True to preview') and notes that no undo is recorded, which implicitly tells the agent this tool is not recoverable via the undo_* siblings. It stops short of an explicit when-to-use/when-not statement or naming an alternative, so it is clear but not exhaustive.

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, so the safety profile is covered, and the '[READ]' prefix is largely redundant with it. What the description does add is the shape of the returned information (version, flavor, uptime, read-only state), which is real context given there is no output schema. It says nothing about auth requirements, latency, or whether 'read-only state' means server-wide or session-level.

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?

Very short and front-loaded: the payload is described first, then the single argument. The only waste is the '[READ]' tag, which duplicates the readOnlyHint annotation rather than adding information.

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-required-parameter read tool with no output schema, the description covers both the invocation (target/default behavior) and the expected fields. It does not describe the response format or units for uptime, but for a simple version probe that is a minor omission.

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% — the schema only exposes a nullable string named 'target' with default null. The description compensates by explaining that target is a 'Target name from config' and that omitting it selects the default, which is exactly the missing information an agent needs.

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 resource (server) and enumerates exactly what is reported: version, flavor (mysql/mariadb), uptime, and read-only state. An agent can tell this apart from generic siblings like show_status or show_variables by the specific payload listed. It stops short of explicitly naming which sibling to prefer when only a version string is wanted.

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?

There is no when-to-use or when-not-to-use guidance. The '[READ]' tag hints at a safe diagnostic call, but with siblings such as overview, show_status, show_variables, and list_engines available, the description never says which one to pick or under what condition.

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 destructive=true, idempotent=false, and readOnly=false, but the description adds substantial context: runtime-only persistence behavior, automatic capture of the prior value for undo, the refusal list for lockout-prone globals, and enforcement of refusals under dry_run. This goes well beyond the structured safety 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 front-loaded with the write/risk tag and core action, then proceeds through behavior, constraints, and args. Every section is necessary for a risky mutation tool with this much operational nuance, and the Args block is compact rather than repetitive.

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 complex mutation tool with no output schema, the description covers the critical invocation details: reversibility, runtime-only scope, persistence alternatives, refused globals, dry-run enforcement, and all four parameter roles. Nothing material for correct usage appears to be 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 0%, so the description carries the full burden and does so well: it defines name (with example max_connections), value as a string, dry_run as a preview switch, and target as a config target to omit for the default. All four parameters are documented clearly.

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 and resource: '[WRITE][risk=medium] SET GLOBAL a server variable.' This distinguishes it from read-oriented siblings like show_variables and from undo tools like undo_apply, and the reversible/undo context further clarifies its role.

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 says to pass dry_run=True to preview, warns that the change is runtime-only and must be persisted separately via my.cnf or SET PERSIST, and lists the specific globals it refuses to modify. These are clear when-to-use, alternative-mechanism, and when-not constraints.

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?

The readOnlyHint=true annotation already establishes the safe-read profile, and the description's '[READ]' prefix merely restates it. Nothing beyond the annotation is added: no output volume, no cost, no note on whether counters are cumulative or per-connection.

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 purpose is front-loaded in a single bracketed sentence, followed by a compact Args block with no filler. Every line 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-required-parameter read tool with no output schema, the description covers both parameters and the operation's scope. Nothing essential is missing, though return shape is left to the reader since no output schema exists.

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 carries the burden and largely does: it explains that pattern is an optional substring filter on counter names with concrete examples, and that target names a config target with omission meaning the default. Only the target-name source/format is left slightly vague.

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+resource: reads global status counters via SHOW GLOBAL STATUS. It is distinguishable in practice from siblings like show_variables and table_status, though the description does not explicitly name or contrast those alternatives.

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?

Usage is implied by the read tag and the optional pattern/target parameters rather than stated. There is no explicit guidance on when to reach for this versus show_variables, table_status, or connection_stats.

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?

The readOnlyHint annotation already carries the safety profile and the description merely restates it as [READ] (consistent, not contradictory). It does not disclose anything the annotation doesn't, such as whether target requires configured connection credentials or what format results take.

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 short arg entries with the purpose front-loaded in the first token. No wasted sentences; the examples are the only elaboration and they earn their place given 0% schema coverage.

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-required-parameter read tool with no output schema and no annotations beyond readOnlyHint, the description supplies the purpose and both parameter meanings. It stops short of describing anything about returned values or pagination, but that gap is minor here.

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 carry both parameters — and it does, giving concrete substring examples for pattern ('innodb_buffer', 'max_connections') and explaining that target defaults when omitted. The target definition ('Target name from config') is slightly circular but still communicates the default behavior.

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 (show/read) and resource (global variables), even mapping to the underlying SQL statement (SHOW GLOBAL VARIABLES). The [READ] tag and 'Global' qualifier implicitly separate it from the write-side sibling set_global_variable, though it never names that alternative.

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?

Usage is implied by the description (inspect server global variables) but there is no explicit when-to-use guidance, no mention of when to prefer overview, show_status, or server_version instead, and no preconditions. Adequate but leaves routing to the 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?

Annotations only carry readOnlyHint=true, so the description carries most of the burden and does add context: it marks the tool [READ], discloses the live-vs-injected execution mode and its data source (performance_schema), and enumerates the metrics it derives. It does not warn about the cost/impact of the live pull or describe output shape, so it is strong but not exhaustive.

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?

Front-loaded with the purpose, then mechanics, then an Args block — a sensible ordering. Slightly redundant: the injected-vs-live behavior is stated once in the prose and again for the statements parameter, costing a bit of space without adding information.

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?

There is no output schema, but the description explains the return content (cited causes plus concrete actions) and the analytical signals used, which is enough for an agent to know what it will get. A brief note on result size or cost of the live path would close the remaining gap.

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 and largely does: Statements (injected digest rows, format tied to top_queries), explain_sql (plan access types feed the RCA), limit (only applies when not injected, default 20), target (config target name, omit for default). 'Target name from config' is the weakest entry but still actionable.

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 and resource ('RCA for the worst statement digest, with cause + action') and immediately scopes it: picks the digest with the greatest total time and maps specific numeric signals to causes. This is clearly distinguishable from siblings like top_queries (which lists), explain_query (which returns a plan), and lock_wait_rca (a different RCA domain).

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?

Gives an explicit branching rule: pass 'statements' for pure/offline analysis, or omit to pull the top digests live from performance_schema, and names top_queries as the source format. It does not explicitly state when a sibling (e.g. lock_wait_rca or explain_query) is the better choice, so it stops short of full alternative 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 declare readOnlyHint=true, and the description's "[READ]" tag is consistent with that rather than contradicting it. Beyond the annotation it adds genuine behavior: the returned envelope shape and, importantly, the truncation contract — that "truncated: true" means re-run with a higher limit instead of trusting the output. That is meaningful operational context the annotations do not carry.

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?

Front-loaded with the read tag and the core metric before the Args/Returns blocks, and the truncation warning is attached to the value it qualifies. Slightly more prose than strictly needed around the envelope, but every sentence serves a purpose.

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 correctly supplies the return envelope and truncation semantics, and both input params are documented. The one missing piece for a 2-param read tool with a confusing sibling (fragmentation_analysis) is any routing guidance between them.

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 carries the full burden and does so for both parameters: limit is "Number of tables to inspect (default 50)" and target is "Target name from config; omit for the default." This matches the schema defaults and explains intent, though "target" remains slightly under-defined (what a target represents is not spelled out).

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 metric returned ("data_free per table"), the ordering ("worst first"), and the practical relevance ("space OPTIMIZE TABLE could reclaim"). That is more specific than a bare resource name, but it never distinguishes itself from the near-identical sibling fragmentation_analysis, so an agent still has to guess which of the two to pick.

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?

Usage is only implied: mentioning that OPTIMIZE TABLE could reclaim the reported space hints that this is a pre-check before optimizing, but there is no explicit when-to-use statement or exclusion versus fragmentation_analysis or optimize_table. The agent must infer the workflow.

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 only declare readOnlyHint=true, so the description carries the rest: it discloses the return envelope (tables/returned/limit/truncated) and, importantly, the truncation semantic with a corrective action. It does not cover query cost or ordering guarantees beyond 'largest first', leaving a small 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?

Front-loaded one-line summary followed by Args and Returns sections; every sentence carries information, including the truncation caveat. Minor redundancy between the '[READ]' tag and readOnlyHint, and the envelope spelled inline is slightly dense.

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 compensates by documenting the return envelope and truncation behavior, and covers both parameters. It stops short of explaining what 'target' config values are valid or any auth/cost considerations an agent might need.

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 supply all parameter meaning, and it does: limit is 'number of tables, largest first (default 20)' and target is 'target name from config; omit for the default'. The 'target name from config' phrasing stays vague about what a valid target resolves to, which keeps it short of a 5.

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 resource and metric - 'Largest tables by data + index size' - with a clear read verb marker. This distinguishes it cleanly from neighbors such as table_fragmentation, table_status, and index_stats without needing to open any schema.

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 useful in-tool guidance ('omit for the default', 're-run with a higher limit' when truncated) but never states when to choose this over siblings like table_fragmentation or table_status. Usage is implied by the resource name rather than spelled out against 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?

Adds value beyond the readOnlyHint annotation by disclosing that it flags non-InnoDB tables lacking row-level locking and crash recovery, and by explaining truncation/pagination semantics. This is genuine behavioral context, though it omits any mention of cost or scope of the scan.

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?

Front-loads the purpose, then args and return shape in clearly labeled blocks. Slightly verbose in the envelope explanation but every sentence adds actionable information.

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 supplies the return envelope and an explicit truncation contract (re-run with a higher limit). An agent has everything needed to call and interpret this 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?

Schema description coverage is 0%, so the description carries the load: it explains limit (count of tables, matching the default 50) and target (config target name, omit for default). This meaningfully compensates for the undocumented schema parameters, though it doesn't give bounds or cost implications.

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 read operation and enumerates the exact resource (per-table engine, row format, row estimate, last update time), which clearly separates it from siblings like table_sizes or table_fragmentation. It does not name those siblings explicitly, so differentiation is implicit rather than stated.

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 '[READ]' marker and the non-InnoDB flagging imply a diagnostic/inspection use case, but there is no explicit guidance on when to choose this over table_sizes, table_fragmentation, or list_engines. Usage is inferred rather than stated.

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 cover only readOnlyHint, so the description does real work: it discloses the result envelope shape, the meaning of the 'truncated' flag, and the correct recovery action (re-run with a higher limit). That is genuine behavioral context beyond the annotations, with the only gap being no mention of permissions or cost.

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?

Front-loaded with a [READ] tag, then Args, then Returns — clean and scannable with no filler. Slightly longer than strictly necessary, but every section (especially Returns, since there is no output schema) 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 no output schema, the description correctly supplies the return shape and truncation semantics, and it fully documents all three parameters. The remaining gap is the undefined 'whitelisted metric' concept and no note on error behavior or target naming.

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% and contains no enum for order_by, so the description carries the full burden — it enumerates all six valid order_by values, gives the limit range (1..200) and default (20), and explains that target comes from config and defaults when omitted.

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+resource: top statement digests from performance_schema, ranked by a metric. This is distinguishable from read-only diagnostic siblings, though it never names or contrasts the closest alternatives (slow_query_rca, long_running_queries), so a 4 rather than 5.

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?

Usage is implied by the metric-selection framing, and the description does give operational guidance for the truncated case. However it never says when to reach for this tool versus slow_query_rca or long_running_queries, and 'whitelisted metric' is left undefined, so it stays at minimum-viable rather than explicit.

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 destructiveHint=true and idempotentHint=false, but the description adds substantial context: the inverse runs through its own governed tool with its own risk tier and audit row, a token can only be applied once (reinforcing non-idempotency), and dry_run previews without executing. These are behavioral facts beyond the annotation flags.

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 risk tag and core behavior are front-loaded, and the prose is tight. The Args block partly restates dry_run and target already covered above, a minor redundancy, but each section remains short and readable.

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?

There is no output schema and no annotation coverage of audit/authorization semantics, yet the description covers the mutation, the single-use constraint, the preview path, and where the audit record lands. What dry_run actually returns is described at a high level; enough for correct 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 0%, so the description carries the full parameter burden and largely succeeds: undo_id is tied to its source, dry_run is defined as a non-executing preview, and target is explained as a pass-through to the inverse tool. The only gap is that 'target' itself is never defined (table? session?).

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: it applies a recorded undo by dispatching the inverse tool. It clearly distinguishes itself from the sibling undo_list, which is named as the source of the undo_id, so an agent can tell the two apart without opening either schema.

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 clear context for use: obtain undo_id from undo_list (or an _undo_id in a write result), and it explains the dry_run=True preview path. It does not state explicit when-not conditions or alternatives beyond undo_list, so it falls just short of the top band.

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 only supply readOnlyHint=true; the description goes well beyond that by disclosing the return shape, that truncation is *measured* via an extra-row fetch, and that effectVerified=false means the reversed change is only PROBABLE, with a caution to check live state and not over-report. This is meaningful operational context the annotations cannot carry.

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?

Front-loaded with purpose and the sibling handoff, then structured paragraphs for return value and the effectVerified caveat. Every sentence carries information, though the emphasis on truncation being 'measured, not guessed from a length coincidence' is slightly verbose for the value it adds.

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 present, the description supplies the return JSON shape, the meaning of every field an agent must act on (returned, limit, truncated, effectVerified), and the follow-up behavior for truncation. Nothing needed to call or interpret 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 0% and no param has an enum, so the description must compensate, and it does fully: limit is documented as default 50 / capped at 500, and target is documented as ignored with the reason (host-local undo state, kept for CLI uniformity).

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 and resource ('List recorded, not-yet-applied undo tokens') plus ordering ('most recent first'). The [READ] tag and the reference to undo_apply make it clearly distinguishable from the sibling that actually applies tokens.

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 routes the agent: 'Use the undoId with undo_apply.' and tells it to re-run with a higher limit when truncated rather than reporting a partial list as complete. It lacks an explicit 'when not to use this' condition, so it falls just short of a 5.

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, and the description adds genuinely useful behavior beyond that: the source table and the fact that counters reset on server restart, which materially affects how results should be interpreted. It stops short of describing return format or scale of output.

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?

Front-loads the [READ] tag and the core result in the first clause, then adds only the caveat and the one argument note. No filler sentences.

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 one-optional-parameter read tool with no output schema, the description covers purpose, data source, interpretation caveat, and the argument. Only a note on output shape or expected result volume is absent, which is minor here.

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 0% and the single parameter has no description in the schema, so the description carries the burden. It explains that 'target' is a name from config and that omitting it selects the default, which is exactly the missing semantics.

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 resource and filter: 'Secondary indexes with zero I/O events since restart (drop candidates)', plus the exact underlying table. This clearly separates it from siblings like redundant_indexes and index_stats, which an agent can distinguish without opening any schema.

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?

Identifies the intent (finding drop candidates) and gives a real usage caveat: counters reset on restart, so confirm over a full business cycle. It doesn't explicitly name alternatives (e.g., redundant_indexes) or state when not to use it, so it falls short of a 5.

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