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

With no annotations, the description carries the full burden and does well: it discloses pooled-connection behavior, the prerequisite requirement, MSSQL-specific defaults, and a detailed TOON-encoded success/error return contract. It does not cover connection lifecycle, cleanup, or authentication requirements beyond URL details, but the transparency is still substantial.

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 organized and front-loaded, with the purpose and prerequisite stated first, followed by connection methods, MSSQL details, and the return format. The 'Args' section partially repeats earlier prose, but it usefully maps concepts to actual parameter names, so the length is justified.

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 annotations and an uninformative schema, the description covers the connection lifecycle, input methods, mutual exclusivity, error handling, and response fields. The sibling tools are all downstream consumers, and the prerequisite relationship is explicit. No significant missing information prevents an agent from calling this tool correctly.

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

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

The input schema provides only two unannotated optional strings with 0% description coverage, so the description must compensate. It defines connection_name versus sqlalchemy_url, gives example URLs, documents MSSQL query parameters with defaults, and enforces the useful 'exactly one' constraint. This fully compensates for the uninformative schema.

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

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

The description clearly states the tool's function: 'Connect to a database' and 'Establishes a pooled connection' that returns a connection_id. It also positions the tool as 'Required before any other database operations', which differentiates it from the sibling query and inspection tools.

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

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

The description gives a clear when-to-use signal: 'Required before any other database operations.' It also explains the two mutually exclusive connection methods and explicitly says 'Provide exactly one of connection_name or sqlalchemy_url', which is strong usage guidance. It does not name alternative tools or state when not to use the tool, so it stops short of a perfect score.

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 covers blocking of writes, automatic row limiting, truncation of large text and binary data, and the status/error model. This is far beyond a minimal description and gives the agent a realistic picture of side effects and constraints.

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 with a purpose, behavior notes, Args, and Returns sections. Every section earns its place; the detailed return format is useful given the tool's output complexity. No filler or redundant restating of the tool 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?

For a query-execution tool with no annotations and low schema coverage, this description is essentially complete. It covers input semantics, safety behavior, output encoding, statuses, and error/blocked cases. An agent has enough information to call and interpret 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?

Schema description coverage is 0%, so the description must compensate for all three parameters. It does so clearly: connection_id comes from connect_database, query_text is SELECT-only, and row_limit has an explicit range and default. This adds meaningful semantics that the raw schema 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 opens with a specific verb and resource: 'Execute a SQL SELECT query and return results.' It further clarifies scope with 'ad-hoc SELECT queries' and explicitly excludes write operations, making it clearly distinct from the sibling schema/metadata tools.

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

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

It provides clear context: this tool is for ad-hoc SELECT queries against an existing connection, with a prerequisite indicated via 'connection_id: Connection ID from connect_database.' It also states when not to use it by noting write operations are blocked. It does not explicitly name sibling alternatives, but the usage context is clear enough.

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 behavioral burden and handles it thoroughly. It discloses the experimental/heuristic nature, false-positive risk, type-compatibility matching, default PK-candidate restriction, optional SQL INTERSECT overlap computation, Databricks catalog behavior, and complete error conditions. This gives an agent a realistic model of what the tool will and will not do.

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 long but well-structured into Args, Returns, and Error conditions sections. Every paragraph serves a purpose, with the core purpose front-loaded before the experimental caveat and detailed parameter semantics. No filler or redundant restatements of the schema are present.

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 (11 parameters, dialect-sensitive behavior, no annotations, and a bespoke TOON-encoded return format), the description is complete. It covers invocation context, parameter behavior, output shape, error handling, and edge cases such as Databricks catalog threading and empty candidate results. An agent has everything needed to select and call it correctly.

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

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

Schema description coverage is 0%, so the description must fully compensate for the input schema's lack of per-property descriptions. The Args section explains every parameter, including dotted table name resolution, default schema behavior, target filtering options, pk_candidates_only semantics, overlap behavior, limit interpretation, and the dialect-specific catalog rule. This is exactly the compensation needed.

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 and resource: 'Discover potential foreign key relationships for a source column' and then clearly defines the tool as searching for target columns that could be the referenced side of a foreign key. This sharply distinguishes it from siblings like find_pk_candidates or get_column_info even without naming them explicitly.

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

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

The description gives strong contextual guidance: it is experimental, a starting point, not definitive, and explains how to broaden or narrow the search via pk_candidates_only, target_schema, target_tables, and target_table_pattern. However, it never explicitly names sibling tools or states when to choose this tool over get_column_info, find_pk_candidates, or execute_query, so the 'when vs alternatives' guidance is only implied.

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

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses the experimental heuristic nature, potential false positives, inability to detect composite keys, full-table scanning behavior, Databricks catalog threading, and error conditions. This goes well beyond a minimal safety profile.

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 long, but it is well structured into sections (purpose, args, returns, errors) and nearly every sentence adds necessary detail for a tool with five parameters and a structured result. It could be slightly trimmed without losing meaning, hence not a perfect 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?

The description is complete for safe invocation: it documents all parameters, the output schema fields, error conditions, edge cases like empty candidate lists, and dialect-specific behavior. An agent has enough to select and invoke the tool correctly without needing additional sources.

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 every parameter, and it does. It defines connection_id, table_name with dotted-name resolution, schema_name defaults, type_filter defaults and empty-list behavior, and catalog's Databricks-specific semantics. This fully compensates for the schema's lack of narrative 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 opens with a specific verb and resource: 'Identify columns that meet primary key candidacy criteria.' It further clarifies two discovery approaches (constraint-backed and structural), which makes the tool's scope precise and distinct from sibling tools like find_fk_candidates and get_column_info.

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

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

The description gives clear usage context: it is experimental, meant as a starting point for investigation rather than definitive answers, and warns that structural checks may be slow on large tables. It does not explicitly name alternative tools or state when not to use it, so it stops 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.

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 reveals experimental status, approximate counts (HLL on Databricks fast path), type-specific behavior, error conditions, and dialect-specific catalog handling (rejected on non-Databricks). This is exceptionally transparent and goes far beyond a minimal 'get stats' statement.

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 long but well-structured with clear sections (Description, Args, Returns, Error conditions). It front-loads the core purpose and then provides necessary details. No sentence is redundant, but the length is higher than minimal; however, given the parameter count and return format complexity, it earns its length. It is appropriately structured and readable.

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

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

For a 7-parameter tool with no annotations and no formal output schema, the description is remarkably complete. It documents all parameters, return structure with field types and notes, error conditions, and even edge cases like empty column lists. An agent has everything needed to invoke it correctly and interpret results.

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

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

Schema description coverage is 0%, so the description must compensate, and it does thoroughly. Every parameter (connection_id, table_name, schema_name, columns, column_pattern, sample_size, catalog) is explained with defaults, precedence (columns over pattern), dotted-name resolution, and catalog behavior. This adds substantial meaning beyond the raw schema fields.

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 and resource: 'Retrieve per-column statistical profiles for a table.' This clearly distinguishes it from sibling tools like get_table_schema (schema only) and get_sample_data (sample rows). The term 'statistical profiles' is unambiguous, and the experimental caveat adds honest context without obscuring 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 states 'Use as a starting point for investigation, not as definitive answers,' which gives context on when to apply results. However, it does not explicitly contrast this tool with siblings like get_table_schema or get_sample_data. The differentiation is implied by the description but not stated outright, leaving the agent to infer when this is the right choice over 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?

With no annotations provided, the description carries the full burden of behavioral disclosure and does so thoroughly. It discloses truncation of large text and binary data, sampling-method semantics, default behaviors, rejection of catalog on non-Databricks dialects, and a detailed error/success response envelope. This goes well beyond a minimal operation summary.

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 a one-sentence summary followed by logically grouped Args and Returns sections. Every sentence earns its place: parameter details, defaults, edge-case behavior, and return metadata are all useful to an agent. It is long because the tool is complex, not because of 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 7 parameters, no annotations, zero schema-level descriptions, and no sibling differentiation in metadata, the description is complete enough to invoke the tool correctly. It covers parameter semantics, defaults, output format, success/error fields, and dialect-specific rejection. No critical operational detail appears to be missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it fully does. Every parameter gets meaningful explanation: connection_id source, dotted table_name resolution, schema default behavior, sample_size range and default, each sampling_method value, optional columns, and catalog restrictions. This adds significant semantic value beyond the bare input 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 opens with a specific verb and resource: 'Retrieve sample data from a table' and expands with 'representative sample rows' plus sampling-strategy details. This clearly distinguishes the tool from siblings like get_table_schema, list_tables, and execute_query, since it is explicitly about sampled row data rather than metadata or arbitrary query results.

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 strong context about how sampling strategies work and defaults, so an agent can choose among top, tablesample, and modulo. However, it never explicitly says when to use this tool instead of execute_query or get_table_schema, nor does it state exclusions or alternatives. The intended usage is implied by the 'sample' framing rather than stated as 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 behavioral disclosure burden and satisfies it: it reveals that the result is a TOON-encoded string with success/error status, explains catalog rejection on non-Databricks dialects, documents default behaviors for schema_name and include flags, and specifies which fields appear conditionally. This goes far beyond what the input schema provides.

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 a one-sentence summary followed by a well-organized Args/Returns layout. The return schema block is lengthy, but it is justified by the output's complexity and the lack of a separately visible structured output schema. No filler or redundant wording is present.

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 definition covers all six parameters, required vs optional, defaults, error handling, return formatting, and dialect-specific behavior. An agent has all necessary information to call the tool and interpret the result without consulting additional sources.

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 Args section must carry all parameter meaning, and it does. It explains dotted table_name resolution against the dialect, schema_name defaulting behavior, catalog override semantics, the non-Databricks rejection, and the boolean flag defaults. Every parameter gains material context beyond its bare schema definition.

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 starts with a specific verb-resource statement: 'Get detailed schema for a specific table.' It enumerates the exact metadata returned (columns, data types, constraints, indexes, foreign keys), making the tool's purpose unambiguous and distinct from siblings like get_column_info or list_tables.

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: whenever detailed table schema is needed. It does not explicitly name alternatives or exclusions, but the context is strong enough for an agent to route correctly. The catalog parameter's dialect restriction also supplies a concrete usage constraint.

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 discloses the exact return format (TOON-encoded string with status, total_schemas, schemas list, error_message), error conditions (invalid connection_id), and dialect-specific behavior (catalog override, rejection on non-Databricks). This is exceptionally transparent about what the tool does and what the agent can expect, going beyond basic operation 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 well-structured with clear sections (Args, Returns, Error conditions). It leads with the core purpose, then details parameters and return format. Every sentence adds necessary information; there is no fluff. The length is appropriate for the tool's complexity, and the format aids scanning.

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 moderate complexity (2 parameters, dialect-specific behavior, structured output), the description is complete. It covers purpose, parameter semantics, return format, error handling, and even the sorting and filtering behavior. An agent has everything needed to invoke the tool correctly and interpret results, even without relying on the output schema.

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 does so thoroughly: connection_id is explained as coming from connect_database, and catalog is fully described with its Databricks-specific override behavior and the error raised on non-Databricks dialects. This adds substantial meaning beyond the schema's type-only definitions, making parameter usage clear.

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'), resource ('all schemas'), and scope ('in the connected database'). It also adds distinguishing details: returns table/view counts, sorted by table count descending, excludes system schemas. This clearly separates it from siblings like list_tables (which lists tables) and get_table_schema (which targets a specific 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: it requires a connection_id from connect_database and explains the optional catalog parameter with dialect-specific behavior. It implies this is the tool for schema discovery, but it does not explicitly name alternatives or state when not to use it. No exclusions beyond system schemas are mentioned, and no sibling alternatives are referenced, so it stops short of explicit when/when-not 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 and discloses substantial behavior: it uses SQL Server DMVs, supports filtering and pagination, includes an access_denied flag, and notes that catalog is rejected on non-Databricks dialects. It also details the return structure and error handling, covering expectations beyond the basic operation.

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 opens with a one-line summary, follows with a brief capability paragraph, and then uses a structured Args/Returns layout. Each sentence, including the detailed return block, earns its place given the tool's 11 parameters and complex output.

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 11 parameters, no annotations, and a complex return payload, the description covers all parameters, defaults, filters, pagination, output modes, error cases, and dialect-specific behavior. The only missing piece would be a note on how to establish a connection, but it correctly references connect_database.

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 supplies per-parameter semantics: source of connection_id, empty-list behavior for schema_filter, SQL LIKE syntax for name_pattern, allowed values and defaults for sort_by/sort_order, range for limit, type choices for object_type, and mode semantics for output_mode. This fully compensates for the schema's lack of descriptions.

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 opening sentence states a specific action ('List tables'), a target resource ('tables in specified schema(s)'), and the delivered information ('row counts and metadata'). The supported filters and mention of views make it clear this is a metadata listing tool, distinct from siblings like list_schemas or get_table_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?

The description communicates its purpose and prerequisite (connection_id from connect_database) but does not explicitly name any sibling tool or state conditions for when to choose an alternative. The mention of SQL Server DMVs gives context but no exclusions, so an agent must infer when to use this vs. other schema inspection tools.

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