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

Because annotations are absent, the description carries the behavioral disclosure burden. It states that the operation is read-only, restricts statements to SELECT/WITH, and notes that results are paginated via limit/offset. It does not cover error behavior or statement-size limits, but the core behavioral traits are disclosed.

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

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

Two short sentences with no filler: the first front-loads the core purpose and restriction, and the second states the pagination behavior. Every clause adds 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?

For a single-query tool with an output schema, the description covers purpose, allowed SQL, and pagination. The main gap is lack of explicit guidance on parameter edge cases and error behavior, but these are minor given the simple parameter set and existing 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 adds meaning by defining sql_statement as a read-only SELECT/WITH query and explaining that limit/offset control pagination. This is more than the raw schema types provide, though it does not detail edge cases like null limits.

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 and resource: 'Execute a read-only SQL query (SELECT/WITH only).' This clearly distinguishes it from the sibling metadata and setup tools, which are about listing, searching, and managing schemas and 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 scope is explicit: only SELECT/WITH queries are allowed, so the agent knows this tool is for read-only querying, not DDL/DML. It does not explicitly name sibling alternatives like list_tables, but the exclusion of writes provides clear enough context for choosing this tool.

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 behavioral burden. 'Get' implies a read operation, and 'Each comment overrides the column name' adds useful behavioral context, but pagination behavior, limit/offset effects, and output details are not disclosed.

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 front-loaded with the main action. The second sentence adds behavioral context, though 'overrides' is terse and could be more explicit.

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?

An output schema exists, so return-value documentation is not the description's responsibility. However, with no annotations, no usage guidance, and no parameter semantics, the definition is only minimally complete for a tool with four parameters.

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 not mention schema_name, table_name, limit, or offset. With no parameter descriptions in the schema and no compensation in the description, the agent receives no added semantic meaning for the 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 verb ('Get'), resource ('authoritative comments'), and scope ('ALL columns in a table at once'). It distinguishes from the singular get_column_comment sibling by emphasizing the bulk nature, though it does not explicitly name the alternative.

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

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

The phrase 'ALL columns in a table at once' implies this is for bulk retrieval rather than fetching a single column comment, but no explicit when-to-use or when-not-to-use guidance is given. Sibling tools like get_column_comment are not referenced, leaving the agent to infer the tradeoff.

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?

There are no annotations, so the description must carry the burden. It adds the useful trait that the returned comment is authoritative and should be preferred over the column name, but it does not disclose behaviors such as whether a missing comment returns null or throws, or whether permissions are needed. Given the output schema exists, this is acceptable 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 entire description is one front-loaded sentence that earns its place: it states the action, the resource, and the reason to trust the result. No filler 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 simple three-parameter getter with an output schema, the description gives the essential context: the comment is authoritative and business-meaningful. It does not address edge cases like absent comments, but the output schema covers the return shape and the operation is straightforward.

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 needed to compensate, but it only mentions 'column' and never explains schema_name or table_name. The parameter names are self-explanatory, but the definition provides no additional semantic detail about any of the three required 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?

Description opens with 'Get the authoritative comment for a column', a specific verb-resource pairing that clearly states what the tool does. The added note that the comment defines business meaning and calculation logic distinguishes it from generic column metadata and from sibling comment tools like get_table_comment.

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 tells the agent when to rely on this tool: when the authoritative business meaning or calculation logic of a column is needed, and to trust it over the column name. It does not explicitly contrast with get_table_comment or get_all_column_comments, but the column-specific scope and 'trust it' guidance provide clear 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. It discloses that the returned comment is authoritative and should be trusted over the schema name, a genuine behavioral trait beyond the tool name. The verb 'Get' also communicates a read-only operation, though it doesn't address edge cases like missing comments.

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

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

The description is a single, efficient sentence that front-loads the core purpose and then adds a useful distinguishing note. There is no filler, and every phrase 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 simple getter with a single parameter and an output schema, the description provides sufficient business context and behavioral guidance. It doesn't cover error scenarios or absent-comment behavior, but those are likely defined by the output schema and are not critical for a basic retrieval tool.

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

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

Schema description coverage is 0%, so the description must compensate for the parameter 'schema_name', but it adds little beyond the word 'schema'. It does not clarify formats, case sensitivity, or what identifiers are valid, leaving the parameter largely to inference from its name.

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 resource ('authoritative comment for a schema'), and adds meaningful context by explaining the comment defines the schema's true business purpose. This clearly distinguishes it from siblings like get_table_comment and get_column_comment, which target different objects.

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

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

The description clearly implies this tool is for schema-level comments and even advises trusting it over the schema name, which gives context on when to use it. However, it does not explicitly mention alternatives or exclusion conditions, so it stops short of fully naming when-not-to-use or sibling tools.

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 safety ('does not touch Redshift, does not return any secrets'), time-independence ('Safe to call at any time'), resolution precedence for profiles, and mode-specific behaviors (inline/borrowed/profile). This is far beyond what annotations would typically cover.

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 (~600 words), but every section (purpose, safety, usage, parameter semantics, return fields) adds unique value given the tool's multi-mode behavior. It is front-loaded with the core purpose and safety statement. While not terse, it avoids fluff and remains well-structured with clear field explanations.

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 fully explains each return field, its conditions (e.g., 'present only when has_fields=True'), the meaning of 'borrowed_from_profile', and how 'next_step' is actionable. The output schema likely lists fields, but the description adds the conditional logic and mode semantics that an agent needs to interpret results correctly. Nothing important is missing for a tool of this complexity.

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 shows only a single nullable 'profile' parameter with no description (schema coverage 0%). The description compensates thoroughly by explaining what the parameter overrides, the exact resolution order (env var, pointer file, fallback, literal 'default'), when it has no effect, and how its output differs from the input — including a nuanced explanation of why the returned profile may differ from the passed argument.

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 states a specific verb and resource: 'Read-only check of whether a profile is configured.' It also immediately disambiguates from siblings by noting it does not touch Redshift and is safe to call at any time, clearly separating it from setup_via_dialog and other DB-bound 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 explicitly says 'Use at session start to decide proactively whether to call setup_via_dialog (before triggering any DB tool's not_configured error path), or to verify a setup_via_dialog call succeeded from a fresh angle.' This gives concrete when-to-use guidance and names the alternative tool, leaving no ambiguity about the 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 behavioral disclosure burden. It communicates that the result is authoritative and should be trusted over the table name, which is useful behavioral context. It does not address potential empty comments, error conditions, or permissions, but the output schema covers return structure.

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?

A single, front-loaded sentence that states the operation and adds a meaningful directive ('trust it over the table name'). No filler or repetitive material.

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 two-parameter read tool with an output schema, the description is nearly sufficient. The main missing pieces are explicit parameter semantics and guidance on alternatives, which keeps it from being fully complete for an agent deciding among the comment and search siblings.

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 not explain schema_name or table_name beyond what their property names already imply. Since the description was expected to compensate for the missing schema descriptions, this is a gap even though the parameter names are self-explanatory.

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

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

The description states a specific action and resource ('Get ... comment for a table') and adds meaning by calling the comment 'authoritative' and contrasting it with the table name. It does not explicitly differentiate from sibling comment tools like get_column_comment or get_schema_comment, though the table focus is implied by the name.

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 implies when to use the tool: when you need the actual meaning of a table rather than guessing from its name ('defines what data it actually contains; trust it over the table name'). No explicit exclusions or comparisons to alternatives such as get_all_column_comments or get_schema_comment are provided.

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 disclosure burden. 'List' clearly indicates a read-only operation, and it explains the conditional inclusion of column and parent-table comments. However, it does not mention pagination behavior or any side effects, so the disclosure is adequate but not rich.

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

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

Two sentences with no filler; the main list behavior is front-loaded and the optional comment behaviors are stated compactly. 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 covers the core invocation and the non-obvious comment options, and an output schema exists to define return values. It doesn't position the tool against its siblings or mention how limit/offset apply, which leaves some context gaps for an agent deciding among list_tables/search_columns.

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

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

With 0% schema description coverage, the description must compensate for the schema, and it does add useful semantics for include_comments and include_parent_comments. It leaves limit, offset, schema_name, and table_name to convention, which is mostly acceptable for obvious names but still leaves the low-coverage burden only partially discharged.

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 and resource ('List columns in a table') and names the returned fields, making the core purpose unmistakable. It doesn't explicitly contrast with search_columns or get_all_column_comments, so it stops short of full sibling 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?

There is no guidance on when to choose this tool over search_columns, get_all_column_comments, or list_tables. The description only says what it does and how to turn on comments, which implies the read/list use case but never states 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?

With no annotations, the description itself provides a cost/behavior note: include_comments defaults to True and is cheap because the schema count is small. It does not disclose pagination behavior or ordering, but for a read-only list operation the main behavioral risk is minimal.

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

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

Two short sentences with the core action front-loaded and no filler. The second sentence earns its place by explaining a default's cost implication.

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 covers return values, but the description is incomplete for an agent deciding between list and search, and it omits pagination parameter semantics. Default no-arg usage is clear, but the full tool surface is not adequately explained.

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 the parameters. It only addresses include_comments (default and cost); limit and offset are left entirely undocumented.

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 says 'List schema names,' which names a specific action and resource. It is not as explicit as naming the sibling search_schemas, but the verb and object make the primary purpose clear.

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 about when to choose list_schemas over search_schemas or list_tables/list_columns. The only contextual note is about include_comments being cheap, which addresses a parameter rather than tool selection.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It clarifies the effect of include_comments and include_parent_comments, which adds value, but it omits other relevant behaviors such as pagination (limit/offset) or error handling (e.g., missing schema). For a read-only listing tool, this level of transparency is adequate 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?

Two concise, front-loaded sentences communicate the primary purpose and the two most nuanced parameters. There is no redundant language or repetition of the title. Every sentence contributes 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 tool with five parameters and zero schema description coverage, the description is incomplete. It fails to mention pagination parameters (limit/offset) or the required schema_name, leaving the agent to infer them from the input schema alone. The existence of an output schema mitigates the need to describe return values, but the missing parameter explanations severely limit contextual 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?

Schema description coverage is 0%, so the description must compensate for all five parameters. It explains include_comments and include_parent_comments but says nothing about limit, offset, or schema_name. schema_name is implied as the required input, but limit and offset remain undocumented. This is a significant gap given the lack of schema-level 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 description states a clear verb and resource: 'List tables in a schema.' It goes beyond the title by specifying the optional comment-inclusion behavior, making the tool's purpose unambiguous. While it doesn't explicitly compare itself to sibling tools like list_columns or search_tables, the wording is distinct enough for an agent to infer that this enumerates tables within a given schema.

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

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

No guidance is given on when to choose this tool over alternatives such as search_tables or list_columns. The description focuses on parameter effects (include_comments) but lacks any context about typical use cases or exclusions. An agent seeing only this would not know whether to pick list_tables or search_tables for a given request.

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 present, so the description carries the full burden. It discloses the search logic (space-separated OR), scoping behavior, and return field when table_name is omitted. However, it does not explicitly state that the operation is read-only or non-destructive, nor does it mention ordering or pagination behavior. The disclosed traits are useful and accurate, but the absence of an explicit read-only statement leaves a minor 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 two sentences, front-loaded with the primary purpose, and packs essential usage guidance without fluff. Every clause adds value, from OR logic to the table_name scoping trade-off. It is a model of efficient, high-info documentation.

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 output schema exists (which likely documents return format), the description covers the main usage patterns and return behavior. However, the missing limit/offset semantics is a notable gap for a schema-wide search that could return many rows. There is also no mention of result ordering or potential size limits, so the agent may not know how to handle large result sets. Overall, it is solid but not fully exhaustive.

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 all parameters. It explains keywords, schema_name (required), and table_name (optional with usage details), but does not mention limit or offset at all. These pagination parameters are left undocumented, forcing the agent to guess their semantics. The explanation covers the core parameters but is incomplete for a 5-parameter tool.

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 ('Search'), a resource ('columns'), and the search scope ('column name and comment'). It clearly distinguishes this from sibling tools like list_columns and search_tables by focusing on keyword-based column search with OR logic. The purpose is unambiguous and actionable.

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 tells when to use table_name (routine drill-down, cheap) versus omitting it (schema-wide, natural for cross-table FK/JOIN reconnaissance). It provides concrete use cases and even notes the return behavior for the schema-wide mode. This is strong guidance that helps the agent choose the right call without extra reasoning.

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 usefully reveals that keywords are space-separated, use OR logic, and match against schema name and comment. It does not mention ordering, case sensitivity, or side effects, though 'search' implies a read-only 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 is a single sentence with no filler. The verb, target, and key behavioral detail (OR logic, searched fields) are front-loaded and directly useful to an agent.

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?

An output schema exists, so return structure is covered elsewhere. The description is adequate for a simple search tool but lacks guidance on when to choose search_schemas over list_schemas, and it leaves limit/offset semantics unspecified. It is minimally viable but not rich.

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 adds important semantics for the required 'keywords' parameter: space-separated terms with OR logic over name and comment. However, it does not explain 'limit' or 'offset,' which are left to inference from their names and defaults.

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

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

The description states a specific verb ('Search'), a specific resource ('schemas'), and a precise scope ('over schema name and comment'). This clearly differentiates it from sibling tools like list_schemas, search_tables, and search_columns.

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 when to use the tool: when you need to find schemas by keyword. However, it does not explicitly contrast it with list_schemas or search_tables/search_columns, nor does it state when not to use it or which alternative to prefer.

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 and discloses useful traits: OR logic for space-separated terms, match fields, schema-scoping behavior, and the breadth/speed tradeoff. It doesn't discuss pagination or other edge behaviors, but an output schema exists and the core behavior is 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?

Two compact sentences front-load the core behavior and then explain the optional scoping parameter. There is no filler, repeated schema content, or extraneous 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 four-parameter search with an output schema, the description covers the search semantics, keyword logic, and scoping options well. It lacks sibling-alternative routing and pagination phrasing, but these are minor given the output schema and self-explanatory limit/offset parameters.

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 add meaning. It does define keywords and schema_name well, but limit and offset receive no explanation beyond their names, which is only partially sufficient for a tool with no parameter 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 description opens with a precise verb-resource pair—'Search tables'—and specifies exactly what is matched: table name and comment using space-separated OR keywords. This makes the operation unambiguous and distinguishes it from sibling tools like search_columns or search_schemas without needing to inspect their schemas.

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

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

It gives concrete guidance on the schema_name parameter: pass it to scope and speed up the search, omit it to cover all user schemas. It does not explicitly name alternative tools or state 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 full behavioral disclosure. It explains that the password never crosses the wire, uses OS-native dialogs, defines outcome statuses, and details write ordering (password first, then config/keychain). It also clarifies that on failure nothing is written, which is crucial for an agent's decision-making.

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 structured with clear sections: trigger, procedure, outcomes, write ordering, and alternative. It front-loads purpose and usage, then adds necessary detail. Every sentence serves a purpose—no fluff. Despite its length, it is efficient and well-organized.

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 (dialog, password handling, keychain, multiple failure modes, headless alternative), the description is thorough. It covers all outcomes, side effects, and prerequisites. The output schema exists, but the description still explains return statuses and failure implications, making it complete for an agent to use correctly.

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

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

Schema coverage is 0%, so the description must compensate. It explains that host/port/user/dbname are collected conversationally and are non-secret, and mentions profile concept. It does not detail each parameter's format or constraints, but the schema already provides types and defaults. The description adds meaningful context beyond the raw schema, though it could be more specific about the profile parameter.

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

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

The description clearly states the tool's purpose: to bootstrap or update a Redshift connection profile. It specifies the exact trigger condition (DB tools returning not_configured) and distinguishes itself from sibling query tools by focusing on setup. It's not a tautology and adds actionable context.

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 explicitly states when to use the tool: when DB tools return not_configured, or to add/re-key a profile. It also gives a clear alternative for headless environments (CLI pair set-fields + set-password). The guidance is direct and leaves no ambiguity about when to use this tool vs alternatives.

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