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

Discloses read-only nature and pagination via limit/offset, which are key behaviors. With no annotations, this is good disclosure, though it doesn't cover error handling or output format 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?

Two succinct sentences that front-load the purpose and then add a key detail. No redundant words.

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

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

Covers the main aspects of the tool. With an output schema present, the description is sufficiently complete for a 3-parameter tool, though it omits potential constraints like query length.

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?

Adds meaning to sql_statement by specifying allowed query types and to limit/offset by mentioning pagination, supplementing the schema which has 0% description coverage.

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

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

The description clearly states the tool executes read-only SQL queries restricted to SELECT and WITH statements, distinguishing it from sibling tools that provide specific schema/table 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?

Implies when to use (custom read-only SQL queries) and implicitly excludes write queries by specifying SELECT/WITH only, but does not explicitly mention alternatives or when not to use.

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 bears full responsibility for behavioral disclosure. It adds one behavioral trait ('Each comment overrides the column name') but omits key behaviors such as handling empty results, pagination (limit/offset), or whether the tool is read-only. This is insufficient for a safe agent decision.

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 sentence that conveys purpose and a critical behavioral note. It is not overly verbose, but the sentence is slightly packed; consider splitting for readability. Still very 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?

Output schema exists, so return value details are not required, but the description should at least mention that the tool returns a list or map of column comments. It also fails to address the presence of pagination parameters or the fact that it retrieves 'ALL' columns despite having limit/offset. Completeness is adequate but not thorough.

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?

Input schema has 4 parameters with 0% description coverage, and the tool description provides zero explanation for them. It does not clarify what 'schema_name' or 'table_name' represent, nor how 'limit' and 'offset' control pagination. An agent cannot infer correct usage solely from the description.

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 ('Get') and resource ('authoritative comments for ALL columns in a table at once'), clearly distinguishing this tool from siblings like 'get_column_comment' (singular) and 'get_table_comment'. The phrase 'at once' emphasizes batch retrieval.

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 (e.g., 'get_column_comment' for a single column). While the name and description imply it is for retrieving all column comments, there is no direct comparison or indication of prerequisites or exclusions.

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

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

No annotations are provided, so the description bears the full burden. It only says 'get', implying a read operation, but does not disclose any behavioral traits such as what happens if the column does not exist, whether there are side effects, authentication needs, or rate limits. The output schema exists but is not described to compensate.

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 purpose. It feels concise and adds the key nuance about authority. However, it could be structured with separate sentences for behavioral notes without significant length increase, though it is not verbose.

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 presence of an output schema (not detailed), the description lacks return format details and error scenarios. The tool is simple, but with three parameters and no guidance on input formatting, it is partially complete. For an agent, more context on expected input patterns or output structure would be beneficial.

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%, meaning the description adds no value for parameters. The parameter names (schema_name, table_name, column_name) are self-explanatory, but the description does not clarify expected formats, case sensitivity, or any constraints beyond the schema. With no param information, the score is minimal.

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 gets the authoritative comment for a column, specifying that it defines business meaning and calculation logic, and to trust it over the column name. This distinguishes it from sibling tools like get_table_comment (table-level) or get_all_column_comments (all columns), providing a specific verb and resource with scope.

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 (when authoritative business meaning/calculation logic is needed) and tells the agent to trust this over column names. However, it does not explicitly mention when not to use or compare to alternatives like search_columns or get_table_comment, so it lacks full exclusionary 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 must cover behavioral traits. It does not mention whether the tool is read-only, if it requires special permissions, or what happens if the schema doesn't exist. The phrase 'authoritative comment' hints at reliability but lacks specifics.

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 that is front-loaded with the action and purpose. It is concise and avoids redundancy.

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

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

The tool has a single required parameter and an output schema, so the description can be brief. However, it lacks details about the return format or scenarios where the comment might be empty. It is adequate but not comprehensive.

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 0%, meaning the description doesn't explain the parameter 'schema_name'. The parameter is only defined by its name and type, with no additional context in the description.

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 retrieves the authoritative comment for a schema, distinguishing it from sibling tools like get_table_comment and get_column_comment. It emphasizes trusting this over the schema name, which adds 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?

The description implies use when you need the true business purpose of a schema, but does not explicitly state when not to use or provide alternatives. No direct contrast with siblings like list_schemas.

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 provided, so the description fully carries the burden. It states 'read-only', 'does not touch Redshift', 'does not return any secrets', and explains return fields including behavior in inline mode. This is comprehensive and transparent.

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

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

The description is well-structured with clear sections and bullet points for returns. It is information-dense but not overly verbose. A slight reduction in the return list could improve conciseness, but it remains effective.

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 input and presence of an output schema, the description covers all necessary aspects: safety, use cases, return details, inline vs profile mode distinctions, and actionable hints. It is fully complete for this 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 input schema has one parameter 'profile' with 0% description coverage. The description does not explicitly describe the input parameter; it only mentions 'the queried profile name' in the return section, which implies but does not clearly state that the input specifies which profile to check. The added value is marginal.

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 is a 'read-only check of whether a profile is configured' with specific verb and resource. It distinguishes itself from siblings like 'setup_via_dialog' and 'execute_sql' by noting it does not touch Redshift and is safe to call at any time.

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?

Explicitly provides when to use: at session start to decide proactively whether to call 'setup_via_dialog', or to verify a setup call succeeded. It also advises against hunting for an active profile in inline mode, offering clear context for usage.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It correctly indicates a read operation (get) and adds valuable context about the comment's authoritativeness. There are no contradictory statements, and the simple nature of the tool means no further negative traits need disclosure.

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 words. It front-loads the action and resource, then immediately adds the key semantic nuance. Every part earns its place.

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

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

Given the tool's low complexity (2 simple parameters) and the existence of an output schema, the description is sufficient. It clearly states what the tool returns (authoritative comment) and provides context for its use. No critical information is missing for an agent to invoke 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 should compensate for parameter meaning. Parameter names (schema_name and table_name) are self-explanatory, and the description's mention of 'table' implicitly relates to the table_name parameter. However, no additional semantic detail is provided beyond 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 uses the specific verb 'Get' and identifies the resource as 'the authoritative comment for a table'. It clearly distinguishes the tool from siblings like get_column_comment or list_tables by emphasizing that the comment defines actual data content and should be trusted over the table 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?

The description implicitly guides usage by stating to trust the comment over the table name, suggesting use when reliable data content understanding is needed. It does not explicitly list when not to use or contrast with specific alternatives, but the context of sibling tools makes the differentiation apparent.

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 must disclose behavioral traits. It mentions optional comment inclusion but omits what happens if the table does not exist, whether the operation is read-only, or any pagination behavior for limit/offset.

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. It adds detail on optional parameters without verbosity.

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 6 parameters, the description only covers 2 boolean ones. It does not clarify that limit/offset are for pagination, and the output schema (even if present) is not referenced to explain return structure. Sibling list_tables could cause confusion without differentiation.

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%, yet the description only explains include_comments and include_parent_comments with their defaults. Required parameters schema_name and table_name, plus limit and offset, lack any explanation, leaving ambiguity.

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 'List columns (name, type, nullable) in a table', specifying the verb, resource, and key attributes. It distinguishes from siblings like get_column_comment (retrieves a single comment) and search_columns (searches across 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 provides no guidance on when to use this tool versus alternatives like execute_sql, search_columns, or list_tables. It does not mention typical use cases or conditions to avoid.

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 burden. It discloses the cost ('cheap') and default behavior of include_comments. Could add more about permissions or result limits, but sufficient for a simple list 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?

Extremely concise with no wasted words. Two sentences, first captures purpose, second adds valuable default/cost context. Perfectly front-loaded.

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

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

Given an output schema exists, return values are covered. However, incomplete parameter documentation (limit/offset) leaves a gap. The tool is simple, so not critical, but should explain pagination 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 description must compensate. It only addresses 'include_comments' (default, cheap). 'limit' and 'offset' are not mentioned at all, leaving the agent to guess their purpose.

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?

Clearly states 'List schema names', a specific verb and resource. Differentiates from siblings like search_schemas by focusing on listing all names. Also provides nuance about the cost of include_comments.

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?

Implies usage for listing all schema names, and mentions include_comments is cheap, but does not explicitly tell when to use this tool versus search_schemas or list_tables. No when-not-to-use or alternatives mentioned.

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

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

No annotations are provided, so the description must fully disclose behavior. It mentions parameter effects but omits critical aspects such as pagination behavior (limit/offset), error conditions, access requirements, or the structure of the returned data.

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 at two sentences, front-loaded with the core purpose, and contains no redundant 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?

Given the tool's complexity (5 parameters, no annotations, low schema coverage) and the existence of an output schema, the description fails to provide adequate contextual detail about parameter usage, behavior, and prerequisites, leaving significant 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 0%, so the description must explain all parameters. It only covers include_comments and include_parent_comments, leaving schema_name, limit, and offset unexplained, which is insufficient for an agent to use the tool correctly.

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

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

The description clearly states the action ('List tables') and the resource ('in a schema'), which is specific and distinguishes it from sibling tools like list_columns or search_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 provides hints on when to use optional parameters (include_comments, include_parent_comments) but does not specify when to prefer this tool over alternatives like search_tables or list_columns, nor does it give explicit when-not-to-use guidance.

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

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

With no annotations, the description carries the full burden. It discloses search logic (OR, space-separated), return of table_name when omitted, and required params. However, it does not state whether the tool is read-only or describe pagination behavior for limit/offset, which are minor gaps.

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

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

The description is extremely concise, using two sentences to cover purpose, required params, and two usage modes. No redundancy or filler.

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

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

With an output schema present, return values need not be described. The description covers the core parameters (3 of 5) well, but omits limit/offset. Given the complexity of 5 params and 0% schema coverage, the description is mostly complete but has a minor gap.

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 explains keywords, schema_name, and table_name well, but fails to describe limit and offset parameters. Since limit and offset are common but not self-explanatory in context, this leaves a gap.

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 searches columns by keywords (space-separated, OR logic) over name and comment, with a required schema_name and optional table_name. It effectively distinguishes from sibling tools like search_tables and search_schemas by specifying the resource (columns) and the two usage modes.

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 explicit guidance on when to use table_name (routine drill-down) and when to omit it (cross-table FK/JOIN-key reconnaissance). However, it does not mention alternatives like list_columns or execute_sql, leaving some ambiguity for edge cases.

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?

Discloses OR logic and searchable fields (name and comment) but does not mention sorting, case sensitivity, or behavior with no results. Without annotations, more transparency is needed.

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?

Single sentence, no redundancy, directly explains functionality.

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 3 parameters, the description is minimal but covers core behavior. Could mention sorting, defaults, or return format, but output schema likely provides that.

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?

Adds meaning beyond schema: keywords are space-separated, OR logic, applied to name and comment. Limit and offset are not described but are standard. Schema coverage is 0%, so description compensates well.

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 clearly states the tool searches schemas by keywords over name and comment with OR logic. It distinguishes from sibling tools like 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?

No guidance on when to use this tool vs alternatives like list_schemas or search_columns. The description lacks usage context and exclusion criteria.

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 provided, so description carries the burden. It discloses OR logic, scope, and performance implications. However, it does not explicitly state that the operation is read-only or describe pagination behavior for limit/offset.

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, each essential and front-loaded. No wasted words, clear and 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?

With an output schema present, the description does not need to explain return values. However, it omits details on limit and offset, and lacks behavioral notes like pagination. Adequate but with significant 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 0%. The description explains keywords (space-separated, OR logic) and schema_name (scoping), but does not mention limit and offset parameters, leaving half the parameters 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 clearly states 'Search tables by keywords' with specific verb and resource. It distinguishes from sibling tools like search_columns and search_schemas by focusing on tables and mentioning OR logic over table name and 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?

The description provides clear guidance on when to use schema_name (scope to one schema, faster) versus omitting it (broader search). It does not explicitly contrast with alternate sibling tools but the 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?

Thoroughly explains password handling via OS dialog, never crossing MCP wire, and describes all possible outcomes. No annotations are provided, so the description carries the full burden and does so comprehensively.

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?

Description is well-structured with clear sections and front-loaded purpose, though slightly verbose. Every sentence adds value.

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 5 parameters and an output schema, the description covers use case, outcomes, password safety, and alternatives completely. Output schema exists and description briefly explains return shapes.

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%, but description adds context that host/port/user/dbname are conversational and not secret. However, it does not detail each parameter individually; defaults and types are only in 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?

Description clearly states it bootstraps or updates a Redshift connection profile, with specific verb and resource. It distinguishes from siblings by mentioning alternative tools for headless environments.

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?

Explicitly says when to use (when DB tools return not_configured error) and when not (prefer set-fields + set-password in headless environments).

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