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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies a read-only operation but does not explicitly state non-destructiveness, permissions required, or what the response contains. This is a significant gap for a tool with no annotation support.

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 a single, clear sentence with no wasted words. It is front-loaded with the core action and resource, making it easy to scan and understand.

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 tool, the description is minimally adequate, but it lacks details about the return format (e.g., column names, types, constraints). Since there is no output schema, the agent might benefit from knowing what the result looks like. However, the operation is common enough that the description suffices for basic use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides 100% description coverage for all three parameters, so the description adds no additional meaning beyond what the schema already documents. The baseline of 3 is appropriate since the schema handles parameter 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?

The description clearly states the action ('Describe columns') and the resource ('a table on a DBeaver connection'). This is distinct from sibling tools like list_tables (which lists tables) and execute_query (which runs queries), so an agent can easily differentiate it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, nor any context about prerequisites or typical use cases. It simply states what it does without explaining when it is the appropriate choice.

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?

With no annotations, the description carries the full transparency burden. It goes beyond the basic operation by disclosing that execution happens inside a READ ONLY transaction, that multiple SELECTs return every result set, and that SSH tunnels open automatically. These are meaningful behavioral traits not visible in the schema, though it omits error behavior and permission requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two tight sentences with zero filler. It front-loads the core purpose first, then adds the most important behavioral quirks (multiple result sets and SSH tunnel behavior) without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a SQL execution tool with no output schema, the description covers the key operational context: read-only transaction, multi-statement result behavior, and automatic SSH tunneling. Parameter semantics are fully covered by the schema. The only minor gap is not clarifying behavior for non-SELECT statements like EXPLAIN/SHOW in multi-statement scenarios, but overall it is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already fully documents all four parameters. The description adds no parameter-specific meaning beyond what the schema provides, so the baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Run') and resource ('read-only SQL') and clearly states the tool's purpose. It distinguishes itself from sibling tools by explicitly labeling the operation as read-only, which separates it from write_query and run_script. The extra detail about multiple result sets further sharpens the purpose.

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 clearly establishes the intended use case: running read-only SQL queries. This implicitly tells the agent this is not for writes, but it does not explicitly name alternatives like write_query or explain_query or state exclusion conditions. The read-only marker provides strong contextual guidance, though direct sibling routing is absent.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly discloses that analyze executes the statement for real timings and that write operations are refused. This is the most critical safety behavior. It does not mention output format or connection authorization, but the main mutation guard is 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?

Two dense sentences with no wasted words. The core purpose is front-loaded, and the important analyze caveat is stated immediately after. Every clause 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 4-parameter tool with no annotations and no output schema, the description covers the essential purpose and the key side-effect risk. Parameter details are fully handled by the schema. It would benefit from explicitly routing users to execute_query or write_query for actual execution, but the core information needed for safe invocation is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds some semantic weight to analyze by explaining it 'runs it for real timings and is refused on anything that writes,' which extends the schema's 'reads only' note slightly. However, it adds little meaning for name, query, or verbose beyond what the schema already documents.

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 uses a specific verb plus resource: 'Show the Postgres query plan for one statement.' The phrase 'query plan' clearly distinguishes it from siblings like execute_query and write_query, even though no alternative is named.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: this tool is for explaining a single statement, not for general execution. It also provides a concrete usage condition for analyze, including the exclusion 'refused on anything that writes.' It does not explicitly name alternatives, but the behavior-based guidance is strong.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the tool defaults to a dry run and only writes when 'apply: true' is passed, which is a critical safety behavior. It also explains the underlying problem. It does not mention permissions, reversibility, or output format, but the dry-run default is a significant transparency win.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with zero waste. The first sentence states the purpose and trigger condition; the second states the critical safety default. Information is front-loaded and every word 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 4-parameter tool with no output schema and no annotations, the description covers the essential invocation context: what it does, when it is needed, and the dry-run safety default. It does not describe the return value or side effects beyond 'write', but the core knowledge an agent needs to call it correctly is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds no new parameter-level meaning beyond what the schema provides; 'apply: true to write' merely restates the schema's boolean description. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Reset') with a specific resource ('serial/identity sequences') and a precise condition ('fallen behind MAX(column)'). It clearly distinguishes this fix operation from sibling tools like inspect_sequences by framing it as the corrective action for the duplicate-key state left by dumps.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use the tool: when sequences have fallen behind MAX(column), i.e., the duplicate-key state. It also explains the dry-run default and how to switch to write mode. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does add meaningful context by explaining what needs_reset indicates, which is a key output behavior. Yet it does not explicitly state that the operation is read-only or side-effect-free, which an agent would need to assume from 'Compare' rather than be told.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler, front-loading the primary action. It is concise and to the point, though it could arguably be more structured (e.g., separate output semantics), but the efficiency merits a high score.

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?

The description explains the core behavior (needs_reset flag) but does not specify the full return format—e.g., whether it returns a list of sequences, columns included, or only problematic ones. Since there is no output schema, the description should be more explicit about the result shape, leaving a gap for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema is fully documented (100% coverage), with each parameter described. The description does not add any extra meaning about the parameters beyond what the schema already provides, so it earns the baseline score for a well-covered schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Compare serial/identity sequences to MAX(column)') with a clear resource and distinguishes it from sibling fix_sequences by its diagnostic nature. The added explanation of needs_reset reinforces the tool's purpose, leaving no ambiguity about what it does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a concrete scenario ('typical after a dump or manual INSERT') that tells an agent when this tool is useful. However, it does not explicitly mention alternatives or when not to use it, such as pointing to fix_sequences for resetting, so it falls short of the top tier.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose that passwords are never returned, which is a useful safety-related trait. However, it does not mention whether the operation is read-only (though obvious), any potential side effects, or response format. For a simple list operation, this is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences with no wasted words. The core purpose is front-loaded, and the password disclosure is a valuable addition. It is appropriately sized for a simple 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 zero-parameter, no-output-schema tool, the description covers the essential information: what is listed and what is explicitly excluded (passwords). It does not mention edge cases like disabled connections or pagination, but these are minor for a list operation. The description is sufficient for an agent 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?

The tool has zero parameters, and the schema coverage is 100% (vacuously). The description does not need to explain parameters since there are none. The baseline for 0-parameter tools is 4, and the description adds no unnecessary parameter details.

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 ('List') and resource ('DBeaver Community connections') and specifies the returned fields (names, hosts, SSH hop). It is clear and unambiguous, though it does not explicitly differentiate from sibling tools like test_connection or list_schemas. The purpose is evident without needing to open the 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?

No guidance is given on when to use this tool versus alternatives. It does not mention prerequisites, typical use cases, or when another tool might be more appropriate. The context is implied but not stated, leaving the agent to infer usage.

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?

With no annotations, the description bears the full burden of behavioral disclosure. It only states what it lists, but does not mention that it is a read-only operation, what precisely qualifies as 'non-system', whether an active connection is required, or what the return format will be. The agent is left to infer these operational details.

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 a single, well-structured sentence that leads with the core action and resource. Every word earns its place; no filler or unnecessary clauses. It is appropriately concise for a tool with one parameter and a straightforward function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema, no annotations), the description is largely sufficient. It states the purpose clearly. However, it could more explicitly note that it returns a list of schema names or that the operation is read-only, which would complete the context for an agent without additional hints.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema fully describes the single parameter 'name' as 'Connection name or id' (100% coverage). The tool description adds nothing beyond this—it does not elaborate on parameter usage, constraints, or typical values. Since schema coverage is complete, a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List') and the resource ('non-system schemas') with a qualifier ('on a DBeaver connection'). This distinguishes it from sibling tools like list_connections (lists connections) and list_tables (lists tables). The purpose is unambiguous and specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when one needs to see available schemas on a connection, but it does not explicitly state when to use this tool over alternatives or mention any exclusions (e.g., 'for system schemas, use X'). The phrase 'non-system schemas' hints at a filtering behavior but provides no guidance on when this is the right choice.

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?

With no annotations, the description carries the full burden. It states a read-only action ('list') which implies non-destructive behavior, but does not disclose return format, whether it includes views or system tables, or any connection prerequisites. The description is not misleading but is sparse on behavioral detail.

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 a single, efficient sentence that immediately states the purpose. No wasted words and no redundancy with the schema. It is optimally front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description should clarify what the tool returns (e.g., a list of table names) and any prerequisites (e.g., an active connection). It only says 'list tables,' which is a minimal definition but leaves some ambiguity about the exact output structure. For a simple list operation, this is adequate but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are already described in the input schema. The description does not add any additional meaning to the parameters beyond what the schema provides, matching the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List tables') and the resource ('in a schema for a DBeaver connection'), which is specific and distinguishes it from sibling tools like list_schemas and describe_table. It fully conveys what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage (when you need to list tables) but does not explicitly mention when not to use it or alternatives like list_schemas or describe_table. No exclusions or alternative routing is provided, so it relies on 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?

With no annotations, the description carries the full burden. It discloses a meaningful behavioral trait: automatic transaction default when any statement writes. It also communicates the exact-match requirement for connections, but does not mention confirmation for destructive statements, rollback behavior, or return data. This is partial transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences carry high-signal information with no filler. The primary purpose is front-loaded, followed by the prerequisite and a key safety default. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and lack of annotations or output schema, the description covers only the core use case and one safety behavior. It does not mention destructive-operation confirmation, when to prefer this over sibling tools, or what the response looks like. The schema fills in parameter details, but high-level operational context is incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers 100% of parameters with clear descriptions, so the description does not need to compensate. The description adds some context around connection name exactness and transaction defaults, but these are already reflected in schema properties like name and transaction.

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 action ('Run several SQL statements') and resource ('on one connection'), clearly indicating a batch execution tool. It implicitly distinguishes from single-statement siblings like execute_query and write_query, but does not explicitly name 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?

The description provides a prerequisite ('Requires an exact connection name or id') and a default behavior, but gives no guidance on when to use this tool versus execute_query, write_query, or explain_query. No exclusions or alternative routing are mentioned.

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?

No annotations are provided, so the description carries the full burden. It transparently mentions side effects: opening a connection and starting an SSH tunnel if needed. It runs SELECT 1, which is read-only, but the description does not explicitly state that it is non-destructive or that it does not modify data. It also does not cover failure behavior or whether the connection is kept open.

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 a single, compact sentence that conveys the essential behavior without any filler. It is front-loaded with the primary action and includes the conditional tunnel detail. No wasted words.

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 connectivity test, the description is mostly adequate, but it does not specify the return value or success/failure indicators. Since there is no output schema and no annotations, an agent might be unsure whether the tool returns a result or just signals success. It also does not mention error handling or edge cases (e.g., invalid connection name).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema describes the only parameter (name) as 'Connection name or id', which is clear and complete. The tool description adds no additional meaning beyond the schema. Since schema coverage is 100%, a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Open... and run SELECT 1') and a clear resource (DBeaver connection). It is distinct from siblings like list_connections (which lists connections) or execute_query (which runs arbitrary queries). The purpose of testing connectivity is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The usage is implied: it tests a connection by running SELECT 1, and it notes that it starts an SSH tunnel if needed. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or prerequisites. It relies on the context of sibling tools for differentiation.

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?

With no annotations present, the description carries the full burden, and it succeeds. It discloses both the mutating behavior ('record it in known_hosts') and the safety gate ('only when the user confirms that exact fingerprint'). It does not hide the side effect behind the tool's name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the action and followed by the precise use-case trigger. Every phrase earns its place: what it shows, what it records, when recording happens, and when to use the 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 two-parameter tool with full schema coverage and no output schema, the description is complete enough to select and invoke correctly. It names the trigger, the side effect, and the confirmation requirement. Nothing essential is missing for an agent deciding whether and how 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 100%, so the baseline is 3. The tool description adds some framing about fingerprint confirmation, but the confirmFingerprint parameter's behavior is already well documented in the schema. The description does not materially extend what the schema already states.

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 pair: 'Show the SSH host key fingerprint for a tunnelled connection', then states the recording action into known_hosts. This clearly distinguishes it from siblings like test_connection and execute_query by focusing on SSH host trust. The 'Unknown SSH host key' mention further pins down the exact job.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly gives a trigger condition: 'Use this when a tunnel fails with "Unknown SSH host key".' It also communicates the consent condition for the side effect. It does not name when-not-to-use cases or alternative sibling tools, 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?

With no annotations, the description carries the full burden. It discloses transaction wrapping and the exact-connection requirement, which are useful behavioral traits. However, it doesn't mention the confirm parameter's role in destructive statements (though schema covers it) or any side effects/permissions. The transaction info adds value beyond schema, but more could be said about error handling or return behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core purpose. Every clause adds value—purpose, connection requirement, and transaction behavior. No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter tool with no output schema and no annotations, the description covers the essential behavioral context: what it executes, connection requirements, and transaction semantics. It doesn't explain the confirm parameter's necessity for destructive statements (but schema does) and omits return-value details (no output schema). Overall, it's complete enough for an agent 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 coverage is 100%, so the baseline is 3. The description adds meaning by clarifying that 'name' must be an exact match (no partial matching) and that multiple statements in 'query' run on one connection and are wrapped in a transaction. This goes beyond the schema's parameter descriptions, earning a 4.

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 'Run INSERT/UPDATE/DELETE/DDL', which clearly states the verb and resource. It distinguishes itself from siblings like execute_query (likely read-only) by explicitly targeting mutating SQL, so an agent can immediately tell what it does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use it: it requires an exact connection name or id and explains transaction behavior for multiple statements. It doesn't explicitly contrast with execute_query, but the mutating-SQL focus and sibling names imply the division of labor. Lacks an explicit 'use this for writes, execute_query for reads' statement, so not a 5.

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