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

With no annotations, the description carries all responsibility for disclosing behavioral traits, but it provides none. It does not mention that connecting may save credentials to OS Keyring, set the operating mode, or establish a session. The schema contains these details, but the description itself adds no behavioral context, leaving the agent unaware of side effects.

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 extremely short, which is concise, but it is under-specified for a tool with 7 parameters and significant behavioral implications. It is not a case of efficient brevity but rather missing critical information. The one-sentence description provides no value beyond the tool's name.

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

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

Despite rich schema details and an output schema, the description is completely inadequate. It fails to mention that connecting may be a prerequisite for other tools, that it could persist credentials, or that different connection modes affect behavior. The description leaves the agent without essential context about the tool's role and effects.

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% coverage with detailed descriptions for all 7 parameters, so the baseline is 3. The description itself adds no param information, but since the schema does the heavy lifting, a 3 is appropriate. It does not compensate for any gaps, but none exist in the schema.

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

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

The description states the tool's action clearly: 'Connect to a database.' It uses a specific verb and resource, making it distinct from sibling tools like disconnect or execute_query. However, it does not differentiate itself further by mentioning what connecting entails, so it lacks the sibling differentiation needed for 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?

No guidance is given on when to use this tool versus alternatives such as reconnect_saved or list_connections. There is no mention of prerequisites, typical scenarios, or exclusion criteria. The description simply states what it does without context, so it fails to help the agent decide when to invoke it.

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 transparency. It explicitly enumerates what the tool returns (column names, data types, constraints, indexes) and the verb 'show' implies a non-destructive read operation. It does not discuss permissions or error behavior, but for a read-only metadata tool, this is adequate.

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

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

The description is three concise sentences with no filler. The purpose is front-loaded, and the additional details about included items and intended usage are directly relevant, making every sentence earn 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 covers the tool's purpose, output contents, and intended usage context. The presence of an output schema and fully described parameters helps complete the picture. Minor gaps like permissions and error conditions are not critical for this simple read-only 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?

Both parameters (connection, table_name) are fully described in the input schema with 100% coverage. The tool description adds no additional parameter semantics beyond what the schema already provides, so a baseline score 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 uses a specific verb ('Show') and clearly defines the resource ('full column definitions, types, constraints, and indexes for a table'). This distinguishes it from sibling tools like list_tables and get_sample_data, which serve different purposes.

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 by stating 'The editor AI reads this to understand the exact schema before generating queries.' This implies when to use the tool, but it does not explicitly name alternatives or exclusion cases, 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.

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, but it only states the action. It does not mention side effects, error behavior, idempotency, or lifecycle implications (e.g., whether ongoing queries are affected).

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 concise sentence with no unnecessary words. It directly states the core 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?

Although the tool is relatively simple and the parameter is well-defined, the description lacks behavioral details such as what happens if the alias is invalid or whether the disconnect is reversible. It is minimally viable but has gaps.

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

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

Schema coverage is 100% for the 'alias' parameter with a clear description. The tool description adds no extra meaning beyond the schema, so the baseline 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 clearly states the action ('Disconnect') and the resource ('database'). This is specific and distinguishes it from sibling tools like connect_database and reconnect_saved.

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 this tool versus alternatives. It does not mention prerequisites, typical scenarios, or contrast with connect_database/reconnect_saved. Usage is only implied by the verb.

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 must disclose behavioral traits on its own. It references a safety pipeline but fails to explain what that entails, such as confirmation requirements, PIN usage, risk tiers, or potential side effects of write operations.

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, front-loaded sentence that directly states the core function. No wasted words 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?

Despite having an output schema and complete parameter schema, the description is too sparse for a tool with risk tiers and confirmation flows. It does not convey how to navigate the pipeline, when certain parameters are required, or what success/failure looks like.

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 six parameters clearly. The description adds minimal contextual value beyond naming the risk-tiered pipeline, which loosely aligns with parameters like 'confirmed' and 'confirmation_phrase' but does not deepen understanding.

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 executes a SQL query, and the mention of a 'risk-tiered safety pipeline' adds useful context. However, it does not explicitly differentiate from sibling tools like preview_query, though the verb 'execute' implies actual execution rather than preview.

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 guidance on when to use this tool versus alternatives. The phrase 'risk-tiered safety pipeline' hints at a specific execution path but there is no mention of preview_query or conditions for safe vs. unsafe 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'return' which implies a read operation, but does not disclose any behavioral traits such as whether the tool is read-only, what constitutes a 'correction', whether there are pagination or ordering guarantees, or any permissions/rate limits. The added note about the editor AI using a resource is more about usage context than the tool's own 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 very concise with two short sentences. The first sentence states the purpose directly, and the second provides useful context about the resource. No unnecessary words or repetition of schema fields. 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 tool is simple (one parameter, no nested objects) and has an output schema present, so the description does not need to explain return values in detail. It provides enough context to understand what the tool does and why one might call it directly. However, the lack of annotations and lack of explanation about what corrections are means it is not fully complete, but it is adequate for a simple read 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?

The schema description coverage is 100%, as the only parameter 'connection' is described as 'Database alias.' The description does not add further meaning beyond the schema, so the baseline of 3 applies. There is no additional semantic detail about the formats or constraints of the alias.

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 function: 'Return all logged corrections for a connection.' It uses a specific verb ('return') and identifies the resource ('corrections') and scope ('for a connection'). This clearly distinguishes it from sibling tools like log_correction (which creates corrections) and get_query_history (which returns query history).

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 context on when to call the tool directly: 'Call this tool directly to inspect them.' It also explains that the editor AI normally accesses this data via a resource, implying the tool is for manual inspection. However, it does not explicitly name alternative tools or state when not to use this tool, so it is clear but not fully explicit about exclusions or 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?

No annotations are provided, so the description must disclose behavioral details. It only says 'return recent query history' without specifying ordering, error behavior, or read-only nature. It doesn't mention prerequisites like an active connection or limits beyond 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?

Two sentences, front-loaded with the main purpose and followed by use-case context. Every word earns its place; no fluff.

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, output schema existence, and clear schema descriptions, the description is nearly complete. It covers purpose and usage scenarios but lacks minor behavioral details like chronological order, which might otherwise be expected.

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%, with both parameters described ('Database alias' and 'Number of recent queries to return (max 50, default 10)'). The description adds no additional semantic detail beyond what the schema already provides, so 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 clearly states 'Return recent query history for a connection' with a specific verb and resource. It distinguishes from siblings by focusing on history retrieval, which no other sibling 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 provides clear context: 'useful for the editor AI to understand what has been executed recently' and gives explicit examples like 'run that again' or 'fix the last query.' It doesn't explicitly name alternatives but the usage 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. It implies a read-only preview, but does not explicitly state that it returns a limited sample (though the schema has a limit parameter), nor does it mention safety, performance, or that data is not modified. The word 'Preview' helps, but details like maximum rows and default behavior are absent.

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

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

Two sentences: the first states the core function, the second explains the typical use case. No extraneous words, no redundancy. Highly 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?

The tool is simple (3 parameters, no nested objects) and has an output schema, so the description does not need to explain return values. The purpose and usage are well covered. Slight gap: it does not mention the row limit default or that it is a sampling operation, but the schema fills in the parameter details.

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?

All three parameters (limit, connection, table_name) are fully covered by the input schema with descriptions. The description adds no additional semantic meaning beyond what the schema already provides. 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 a specific action ('Preview a few rows') and resource ('a table') with an explicit purpose ('understand its data shape'). This distinguishes it from sibling tools like list_tables (metadata only), describe_table (schema), and execute_query (arbitrary queries), making its unique role obvious.

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 for when to use: 'before generating queries' to understand actual values (statuses, date formats). It does not explicitly mention alternatives or when not to use it, but the use case is concrete and actionable.

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 transparency burden. It discloses that the tool returns alias, dialect, permission mode, and connection time, which indicates a read-only operation. It does not mention error conditions or side effects, but for a simple list tool this is adequate.

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, front-loaded with the primary action. 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?

Given the simple nature of the tool and the presence of an output schema, the description fully covers the purpose and return information. There are no gaps that would impede an agent's understanding.

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

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

The tool has zero parameters, so the description has no parameter burden. The empty schema fully covers parameter definitions, and the description adds nothing needed here.

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 lists all currently active database connections, using the specific verb 'List' and resource 'database connections'. This distinguishes it from sibling tools like list_tables or get_query_history.

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 'currently active' provides context for when to use this tool (to see active connections). However, it does not explicitly mention alternatives or when not to use it, so it stops short of full 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 full burden. It discloses the caching behavior ('Schema is served from cache when available'), which is a useful behavioral trait. But it does not explicitly state that the operation is read-only, nor does it mention potential staleness risks or permissions.

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 the first front-loading the main purpose and the second adding usage context and a caching note. Every word earns its place, 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?

Given a single parameter, an output schema, and no annotations, the description covers the purpose, usage context, and a relevant behavioral detail. It does not explicitly mention error conditions or prerequisites beyond the parameter schema, but it is largely complete for a simple list 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?

The schema coverage is 100% because the 'connection' parameter has a clear description ('Database alias from connect_database'). The tool description adds little beyond the schema, so the 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 tool's function with a specific verb and resource: 'List all tables in the connected database with row counts and sizes.' This distinguishes it from sibling tools like describe_table (which focuses on a single table) and profile_table.

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 by stating that the editor AI uses this to understand database structure before generating queries. However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of full exclusion 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 states 'Bollard persists it and exposes it via the bollard://corrections/{alias} MCP Resource' which explains the side effect of logging (persistence and exposure). It also clarifies the learning outcome. It doesn't mention any destructive aspects, but for a logging tool this is sufficient.

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

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

The description is three sentences, each with a clear purpose: the first states the action, the second defines the trigger context, and the third explains the persistence and learning benefit. 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?

The description covers the purpose, trigger, persistence, and resource exposure. The presence of an output schema means return values are already documented. For a simple logging tool, this is complete and leaves no major gaps.

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 context (the purpose of logging corrections) but doesn't add detail about individual parameters beyond what the schema already provides. The schema descriptions are self-explanatory, so no need for the description to compensate.

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 'Log a query correction for future AI context' which clearly identifies the verb (log) and resource (query correction). It further distinguishes itself from siblings by explicitly stating this is for logging corrections when the editor AI generates a wrong query, making it distinct from execute_query or get_corrections.

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 a specific trigger: 'When the editor AI generates a wrong query and the user corrects it, log the correction here.' It also explains the purpose (so AI learns from past mistakes). It doesn't explicitly contrast with get_corrections, but the use case is clear enough to know when to use it.

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 full burden and does so thoroughly. It discloses the dry-run nature, the specific outputs (safety verdict, intent analysis, cost estimate with PostgreSQL-only caveat, auto-LIMIT), and the redirection behavior. This goes beyond what any schema or annotation would 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?

The description is concise and well-structured with a clear purpose line, bullet-point return summary, and two behavior/usage notes. Every sentence adds value—no filler or repetition. The front-loading is ideal: immediately states dry-run, then lists outputs, then gives redirection and usage guidance.

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 a rich safety/intent pipeline, the description covers all essential aspects: what it does, return values (even though output schema exists, the summary helps), the PostgreSQL-specific cost estimate, auto-LIMIT behavior, and the redirect to profile_table. It is complete enough for an AI to select and invoke correctly without additional context.

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% (both sql and connection are described), so baseline is 3. The description does not add additional parameter-level detail beyond the schema's own descriptions. However, it does imply that the sql parameter is transformed (auto-LIMIT) and that connection is a database alias, but these are not parameter-specific enhancements.

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: 'Dry-run a query through the full safety + intent pipeline.' It clearly distinguishes from siblings like execute_query (which actually runs) and profile_table (which is mentioned as a redirect target). The listed return items (safety verdict, intent analysis, EXPLAIN estimate, final SQL) make it 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?

Explicit when-to-use guidance is provided: 'The editor AI should call this before execute_query for any non-trivial query.' It also explains the automatic redirection to profile_table for bare SELECT * on large tables, giving alternatives and context for when that behavior occurs. This is strong usage scoping.

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 and does well by disclosing that all aggregation is performed in the database via SQL, no rows are transferred to local memory, and the output is a compact Markdown summary with specific token overhead. It does not mention failure modes or performance implications for very large tables, but it provides substantial behavioral detail beyond what the schema offers.

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 well-structured and front-loaded with the primary purpose, followed by a concise bulleted list of included statistics. Every sentence earns its place, and there is no redundant information or excessive length.

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 has only two simple parameters and an output schema exists (though not shown), the description covers the core behavior, execution model, and output format sufficiently. The only minor gap is the unspecified handling of categorical columns with >100 distinct values, but this is likely detailed in the output schema, and the overall description is complete enough for an agent to select and invoke the tool correctly.

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

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

The schema already provides 100% coverage for both parameters, with clear descriptions for 'connection' and 'table_name'. The tool description adds no additional parameter-level detail about format, syntax, or constraints, so a baseline score of 3 is appropriate given the schema's 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 opens with a specific verb+resource ('Generate a statistical profile of a database table') and clearly differentiates from sibling tools by detailing statistical aggregates (row count, nulls, min/max/avg, top-5 distribution) and output format (Markdown summary). This makes the tool's purpose unambiguous even among similar tools like describe_table and get_sample_data.

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 usage context, noting the output is 'suitable for AI context' and emphasizes the low token overhead, which implies when this tool is appropriate. However, it does not explicitly name alternatives or state when not to use this tool, so it lacks explicit exclusions but still conveys strong contextual 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 burden of behavioral disclosure. It states it uses the OS Keyring but does not mention whether the operation is read-only, what happens on failure, or whether authentication is required. Minimal behavioral context beyond the core action.

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-formed sentence that front-loads the main action. No filler or redundant content; every word contributes to the meaning.

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 with one parameter and an output schema, the description captures the core purpose but omits context such as prerequisites (must have a saved connection) and differentiation from connect_database. It is minimally viable but leaves gaps in usage context.

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 alias parameter (100% coverage), and the description does not add additional meaning. The baseline of 3 is appropriate since the schema handles parameter semantics entirely.

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 'Reconnect to a previously saved connection from the OS Keyring' clearly states the verb (reconnect), resource (saved connection), and source (OS Keyring). It distinguishes from siblings like connect_database by emphasizing 'previously saved' and the keyring storage.

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 'previously saved'—meaning it applies to existing saved connections rather than new ones. However, there is no explicit guidance on when to use this over connect_database, nor any 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal that the tool 'force' a refresh and its intended effect (up-to-date schema context), but it omits potential side effects (e.g., whether it invalidates existing cache, requires permissions, or is safe to call frequently). This is moderate transparency but lacks depth.

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 core action in the first sentence and usage context in the second. There is no wasted text, redundancy, or vague phrasing. 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 tool is simple (one parameter) and the description covers its purpose and when to use it. The parameter is documented in the schema, and the output is covered by the output schema. The only missing context is potential caveats or side effects, but for a straightforward cache-refresh operation, this is largely sufficient.

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 only parameter 'connection' is fully described in the input schema as 'Database alias,' giving 100% schema coverage. The tool description does not add any extra semantic detail about the parameter (e.g., format or allowed values). Therefore, the baseline of 3 applies as the schema already carries the necessary meaning.

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 with a specific verb ('Force a schema cache refresh') and identifies the resource ('schema cache for a connection'). It also explains the purpose ('ensure the AI has up-to-date schema context') and distinguishes it from sibling tools like list_tables or describe_table, which merely read schema. The purpose is unambiguous and differentiated.

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 states when to use the tool: 'Call this after CREATE TABLE, ALTER TABLE, or any DDL operation.' This gives clear context for usage. However, it does not mention when not to use it or name alternatives (e.g., refresh might not be needed for read queries), so it falls slightly short of a full 5.

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