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

No annotations are provided, so the description carries full burden for behavioral disclosure. It does describe the health metrics checked, which is useful, but it does not mention whether the operation is read-only, whether it could be expensive, or any failure/edge-case 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?

The description is brief, front-loaded with the purpose, and then cleanly lists the argument. Every sentence contributes useful information with 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?

This is a simple tool with one optional parameter and an output schema, so the description is largely sufficient for invoking it. It covers the action and the metrics returned, though it lacks explicit usage guidance and behavioral caveats that would make it fully self-contained.

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 explain parameters. It does: connection_name is described as the name of the database connection with its default value. This adds meaningful semantic context beyond the bare schema type and default.

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

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

The description clearly states the tool checks database health and enumerates specific metrics: latency, table count, row count, and largest tables. This distinguishes it from sibling tools like list_tables or query, though it 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?

No guidance is provided on when to use check_health versus siblings such as list_databases, get_table_info, or diagnose_connection. The phrase 'database health' implies a use case, but there is no explicit when-to-use or when-not-to-use guidance.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the output includes status and troubleshooting hints, but does not state whether the operation is read-only, whether it requires credentials, makes network calls, or is safe to run in production. These are significant gaps for a diagnostic 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?

The description is two sentences with no wasted words, front-loading the core purpose before the parameter details. It is compact and directly maps to the schema 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 tool with one optional parameter and an output schema, the description is mostly adequate: it states the purpose and the parameter meaning. However, it omits any usage context or relationship to sibling tools, and the absence of annotations leaves behavioral gaps. Despite the simple interface, these omissions prevent a higher score.

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's 'Args' section is the only source of parameter meaning. It adds 'Name of the database connection' and the default, which is sufficient for the single optional parameter, but this adds little beyond the schema's title and default value.

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

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

The description clearly states the tool diagnoses a database connection and provides 'detailed status and troubleshooting hints,' giving a specific verb and resource. However, it does not differentiate itself from sibling tool check_health, which may also inspect connection health, so it does not earn 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?

There is no explicit guidance on when to use this tool instead of alternatives like check_health or list_databases. The word 'diagnose' implies a troubleshooting context, but no when-to-use, prerequisites, or exclusions are 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly discloses that the tool performs writes and depends on writes being enabled. It does not mention permissions, reversibility, or what happens when writes are disabled, so coverage is moderate rather than complete.

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

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

The description is compact and well structured: a one-sentence purpose, a prerequisite, and a short argument list. It is front-loaded with the most important behavior and contains 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?

Given the tool's simplicity, an output schema, and clear parameter docs, the description is nearly complete. It covers the core write behavior, the writes-enabled prerequisite, and all arguments. Minor gaps like error behavior when writes are disabled or transactional semantics are not addressed, but they are not essential for basic 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%, and the description does provide some meaning for each parameter: sql is the statement, database is the database within the connection, and connection_name has a default. However, most of this is thin restatement of the parameter names and schema defaults, adding limited semantic value beyond what the schema already shows.

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 names the action ('Execute a write SQL statement') and specifies the allowed statement types (INSERT, UPDATE, DELETE). This separates it from the read-oriented sibling tools like query and sample_rows.

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 makes clear the tool is for write SQL and not for reads, which implies the distinction from sibling tools. It also states the key prerequisite that writes must be enabled. It does not explicitly name read alternatives, but the context is sufficient.

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

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

With no annotations, the description carries the full burden of disclosing behavior, yet it only states what the tool does and not its side effects or constraints. It does not disclose whether the query is actually executed, whether the operation is read-only, or how the returned plan is presented. It adds no behavioral context beyond the bare purpose.

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

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

The description is compact: one sentence for the main purpose plus a concise Args list. It front-loads the core purpose, and every line adds relevant information about the tool or its parameters with no 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?

The tool is simple, with two documented parameters and an output schema to cover return values, so the description covers the essentials. However, it omits usage guidance (when to prefer this over execute or query) and behavioral safety (whether it executes the query or modifies state), which an agent needs to select and invoke the tool correctly in the absence of annotations.

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 is the only documentation available. It clearly states that query must be a SELECT or WITH...SELECT statement and defines connection_name as the name of the database connection with a default. This adds meaning the schema alone lacks, though it could be richer by referencing how valid connection names are obtained.

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 ('Explain'), a specific resource ('execution plan'), and a specific input class ('SELECT query'). This clearly distinguishes it from sibling tools like query and execute, which run queries rather than analyze their plans.

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 its use case—when you need to understand a query's execution plan—and confines input to SELECT/WITH...SELECT. However, it offers no explicit guidance on when not to use it, nor does it name alternatives such as using query or execute to actually run the statement.

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 behavioral burden. It does disclose the key limitation that only 'mermaid' is currently supported, and describes the two inputs. However, it does not explicitly state that the operation is read-only, what it requires from the connection, or what the generated diagram contains.

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

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

The description is compact and front-loaded: the first sentence states the tool's purpose, and the Args section briefly defines both parameters. Every sentence adds necessary information with 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-optional-parameter tool with an output schema, the description is nearly complete. It covers purpose, parameter meaning, defaults, and supported format. The only minor gap is that it does not describe how connection_name is used or what happens if the connection is invalid, but the output schema likely covers the return shape.

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 define the parameters, and it does. It explains that connection_name selects the database connection and defaults to 'default', and it explains format with the important constraint that only 'mermaid' is supported. This fully compensates for 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?

The description uses a specific verb ('Generate') and resource ('ER diagram') and names the exact output format ('Mermaid'). This clearly separates it from sibling tools like get_schema or list_tables, which return raw schema information rather than a visual diagram.

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 intended use is implied: call this when you need an ER diagram in Mermaid format. However, it does not explicitly say when to prefer it over alternatives such as get_schema or schema_diff, nor does it state any exclusions or conditions.

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 must carry the behavioral burden; it discloses the return format (CREATE TABLE statements) and scoping via database/connection_name. It does not explicitly state that the operation is read-only/no side effects, nor does it mention edge cases like omitted database behavior. This is acceptable but not thorough.

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 compact sentences plus a simple Args block. The core behavior is front-loaded in the first sentence, and there is no fluff or redundant metadata. 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 low-complexity, read-only tool with an existing output schema, the description is mostly sufficient. However, it leaves ambiguity about what happens when 'database' is omitted (all databases vs. a default) and does not position the tool relative to siblings. These gaps prevent full completeness.

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 has no per-parameter descriptions (0% coverage), so the description's Args section fills the gap. It explains 'database' as a name within the connection and optional, and notes connection_name defaults to 'default'. This adds meaning that the schema structure alone lacks.

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 ('Get') and a precise resource ('full database schema (CREATE TABLE statements for all tables)'). The parenthetical clarifies that it covers all tables, which differentiates it from siblings like get_table_info. The wording makes the tool's purpose unmistakable.

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 explicit when-to-use or alternative routing is provided, despite 12 siblings like get_table_info and schema_diff. The description implies this is the tool for a full schema dump, but it doesn't say when to prefer it over more targeted tools. This leaves the agent to infer usage context.

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; 'Get' makes the read-only nature reasonably clear and enumerates what information is returned. It does not mention error behavior, permissions, cost of row-count computation, or whether information is current, so behavioral transparency is only partial.

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 short and front-loaded with the core purpose before the Args block. The Args repetition is compact though it partly duplicates schema metadata, preventing 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 simple read tool with an output schema, the basics are present: required table, optional database, default connection. However, there is no usage context, no sibling differentiation, and no caveats, so an agent selecting among 13 siblings is under-supported.

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%, but the Args section gives each parameter a one-line meaning, so the description compensates minimally. The comments are largely tautological (table → 'Table name') and add little beyond the schema titles/defaults, but they do clarify that database is optional and connection_name has a default.

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 first sentence names a specific verb ('Get') and resource ('a table') and enumerates concrete output ('columns, types, row count'). However, it does not explicitly distinguish itself from the sibling get_schema, so an agent may need to inspect schemas to see the difference.

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 statement about when to prefer this tool over siblings such as get_schema, list_tables, or sample_rows, and no exclusions or alternatives. The only contextual hints are optional database/connection arguments, which are parameter-level rather than usage 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 provided, the description carries the behavioral disclosure burden. It reveals the return format (JSON), the fields returned (connection names, types, status, masked URLs), and implies a read-only action without external caveats or failure modes. This is adequate for a simple listing 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?

The description is two sentences with no fluff. The core purpose is front-loaded, and the output detail follows naturally.

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 listing tool with an output schema, the description fully covers what the agent needs: the action, the resource, and the nature of the returned data. There are no missing prerequisites or configuration details worth including.

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 is empty, so there are no parameter semantics to document. The description appropriately adds no unnecessary parameter detail.

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 ('configured database connections and their status'). It clearly distinguishes itself from sibling tools like list_tables, which target tables rather than connections.

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 makes the use case clear: listing all database connections and their status. It does not explicitly name alternatives or exclusions, but the context is sufficiently clear for an agent to select this tool over table- or query-oriented siblings.

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 of behavioral disclosure. It reveals that 'database' is optional and 'connection_name' defaults to 'default', but it does not clarify what happens when database is omitted, whether it is a read-only operation, or what errors or edge cases may occur. This is a meaningful gap.

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

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

The description is short and front-loaded, with the core action in the first sentence. The Args section is structured, minimal, and every line adds useful information without unnecessary detail.

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 listing tool, the description covers the main purpose and parameters, and an output schema is present so return details are not needed. However, the ambiguity around the optional 'database' parameter and the lack of usage guidance relative to sibling tools leave it slightly incomplete for confident autonomous selection.

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?

Although the input schema has no property descriptions, the tool description provides an Args section that gives meaning to both parameters: 'database' is the name within the connection and optional, and 'connection_name' has a default of 'default'. This compensates well for the low schema 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 all tables') and the resource ('in a database'), making the tool's purpose immediately understandable. It does not explicitly differentiate itself from siblings like search_tables or list_databases, but the scope is specific enough.

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: you use this when you want to list tables in a database. It does not explicitly state when to prefer this tool over search_tables, get_table_info, or list_databases, nor does it mention exclusions. This is adequate but not strong 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 behavioral transparency burden. It clearly discloses that the tool is read-only, restricts to specific statement types, and documents row limiting via max_rows. It does not mention error behavior or enforcement of the read-only constraint, but the core safety-critical behavior is well 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?

The description is front-loaded with the purpose and then followed by a compact, well-organized argument list. Every sentence and line earns its place; there is no fluff or repetition.

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

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

For a four-parameter read-only query tool, the description covers the purpose, allowed SQL types, and parameter semantics, with an output schema handling return-value documentation. The main gap is the lack of explicit guidance on how this tool relates to siblings like execute and explain_query, but the core invocation context is 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 0%, so the description must compensate. It provides meaningful explanations for all four parameters, including that database is optional, max_rows caps the result size, and connection_name selects the connection. The explanations are concise and mostly add value beyond 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?

The description clearly states a specific verb and resource: it executes a read-only SQL query and lists the allowed statement types (SELECT, SHOW, DESCRIBE, EXPLAIN). This distinguishes it from likely write-oriented siblings like execute, though it does not explicitly differentiate itself from explain_query or sample_rows.

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-only qualifier implies when to use this tool, and the allowed SQL statement types provide useful scope. However, it does not explicitly state when not to use it or mention alternatives such as execute for write operations, leaving the routing partly 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?

No annotations are provided, so the description bears the full burden of disclosing behavior. It clearly states it returns a sample of rows and mentions the limit behavior with default and max values. However, it doesn't disclose whether the sample is random, ordered, or arbitrary, nor does it mention the read-only nature or any side effects. This is adequate but not fully transparent.

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

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

The description is compact and front-loaded with a one-sentence purpose statement followed by a clear parameter list. Some redundancy exists because default values are repeated from the schema, but the list is short and the added max constraint on limit justifies its presence. It is structured and easy to scan.

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 sampling tool with an output schema, the description covers the core invocation details: table name, limit, database, and connection. Missing elements include when to use this over query/execute and what 'sample' means precisely. It is functional but leaves some behavioral and selection context 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?

The input schema has no property descriptions, but the description compensates by documenting all four parameters. It adds useful meaning beyond the schema: limit has a max of 20, database is optional and scoped 'within the connection,' and connection_name defaults to 'default.' This gives the agent enough semantic detail to use the parameters correctly.

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: 'Get a sample of rows from a table to understand its data.' This clearly communicates what the tool does and implies an exploratory data-preview use case. It doesn't explicitly contrast with sibling tools like query or execute, but the name and 'sample' wording distinguish it well enough for most agents.

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 little guidance on when to use this tool versus alternatives. The phrase 'to understand its data' implies exploration, but there is no explicit mention of when not to use it or when to prefer query, execute, or get_table_info instead. Given several sibling tools that also interact with table data, the lack of routing guidance is a notable gap.

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 behavioral burden. It discloses the core non-mutating comparison behavior and the table_name scoping ('If empty, diff all tables'), which is helpful. However, it does not state whether the operation is strictly read-only, what happens if connections are invalid, or how many schema objects are processed, leaving some transparency gaps.

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 appropriately short and front-loaded. The first sentence states the purpose, and the Args block efficiently covers each parameter without redundancy. 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?

The description is adequate for a straightforward diff tool: it names the two required connections and the optional table filter. An output schema exists, so return values need not be described here, but the description leaves unspecified what elements of the schema are compared and any prerequisites for connections, which an agent might need to know for correct usage.

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 compensates by explaining all three parameters. Source and target are described as connection names, and table_name receives additional semantics with the empty-means-all behavior. This goes beyond the bare schema titles, though it offers no examples or allowed 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?

The description begins with a clear verb and resource: 'Compare schemas between two database connections.' This distinguishes it from sibling tools like get_schema or list_tables, which operate on a single connection, so the tool's specific role is immediately evident.

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: use this when you need to compare schemas across two connections, with an optional table filter. It does not explicitly name alternatives or exclusion conditions, but the purpose statement is enough to infer when it is appropriate.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that tables or columns are searched by keyword, but does not disclose whether the search is case-insensitive, whether it uses partial matching, whether it returns both tables and columns, or what the default database scope is. No read-only confirmation or side-effect information is given.

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 concise and well-structured. The one-sentence purpose is front-loaded, followed by a clean Args block with no redundant prose or filler. Every sentence contributes useful 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?

The output schema exists, so return-value details are not required. Parameter semantics are reasonably complete and the tool is conceptually simple. However, the lack of behavioral detail and absence of usage guidance leave meaningful gaps, especially given the large sibling set with overlapping database-introspection functionality.

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 has 0% description coverage, but the description compensates with a structured Args section defining each parameter: keyword, database, and connection_name. It adds meaningful context about what each parameter is for, optionality, and the default connection name. While not deeply detailed, it covers all parameters.

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

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

The description clearly states the tool's purpose: 'Search for tables or columns matching a keyword.' This uses a specific verb and resource, and is easily understood. However, it does not explicitly distinguish itself from sibling tools like list_tables or get_schema, so it stops short of full differentiation.

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 such as list_tables, get_schema, or query. It does not mention exclusions, prerequisites, or scenarios where a sibling tool would be more appropriate. The usage context is only implied by the tool name and first sentence.

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