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

With no annotations, the description carries the full behavioral burden. It discloses that the tool is an introspection operation and that views are supported, but it does not mention output shape, errors, or side-effect profile. Adequate but 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 front-load the core action and then summarize the optional overrides. There is no filler, no repetition of the schema, and every part of the description 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?

Invocation details are well covered by the schema and description, and the result is implied as column descriptions. However, without an output schema, the return format is unspecified, and there is no guidance on profile defaulting or when to use pg_query instead.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's mention of table/view and optional overrides aligns with the schema but adds no additional meaning or guidance beyond what the schema already provides.

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?

States a specific action, 'Describe columns', with a clear target, 'a table or view'. This differentiates it from the sibling list/database tools even though no sibling is named explicitly. The scope is unambiguous and not a tautology.

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

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

The description implies usage by mentioning optional schema, database, and profile overrides, but it does not explicitly say when to prefer this tool over pg_query or pg_list_tables. No alternatives, exclusions, or conditions are stated.

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

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

With no annotations, the description carries the behavioral burden. It discloses the active-profile vs one-shot behavior and the optional override, which is helpful. However, it does not describe side effects, error handling, or what happens when no active profile is set; for a list operation this is a moderate gap but not misleading.

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

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

The description is a single, front-loaded sentence that starts with the verb and packs the key scoping detail (active profile vs one-shot) efficiently. There is no filler or redundant text.

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 list tool with one optional parameter and no output schema, the description covers the main usage context: which server and how to select a profile. It does not describe the return format or behavior with no profile set, but these are minor given the low complexity and the absence of an 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 coverage is 100%, so the parameter description in the schema already explains profile values and the sticky session behavior. The tool description restates the idea of a 'one-shot' override and 'active profile server', adding slight contextual nuance but not significant new meaning 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 states a precise verb ('List') and resource ('databases'), scoped to 'the active profile server', with an optional profile override. This is clearly distinct from sibling tools pg_list_schemas and pg_list_tables, so an agent can differentiate without opening 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?

The description gives clear context: it operates on the active profile unless a one-shot profile is supplied. While it does not explicitly mention alternatives or exclusions, the sibling names and the 'databases' resource make when-to-use unambiguous. The profile override guidance is useful for choosing behavior.

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, and the description only states what the tool does (list non-system schemas) without disclosing behavioral traits such as read-only nature, permissions required, connection behavior, or return format. For a tool without annotation support, this is a significant 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?

A single concise sentence that front-loads the core purpose and follows with the optional overrides. Every word earns its place with no redundancy.

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

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

The tool is simple with two optional parameters, but the lack of behavioral details and usage guidance leaves some context missing. No output schema exists, so a bit more explanation about return values or side effects would improve completeness, though the essential function is clear.

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

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

Schema description coverage is 100%, with both parameters (profile, database) already described in the schema. The description adds no new parameter-specific meaning beyond restating the override behavior, so the baseline of 3 applies.

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

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

Description states a specific verb ('List') and resource ('non-system schemas'), clearly distinguishing it from system schemas and sibling tools like pg_list_databases or pg_list_tables. The scope is precise and unambiguous.

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

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

The description mentions optional overrides for database and profile, implying how to customize the listing, but it does not explicitly specify when to use this tool versus alternatives or any exclusion conditions. Usage context is implied rather than stated.

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

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

With no annotations available, the description carries the behavioral disclosure burden. It accurately conveys a read-only listing operation and the default-public-schema behavior, but it does not state the output shape, whether system schemas are included, or any ordering/filtering behavior. This 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?

The description is a single highly informative sentence. It front-loads the core action and resource, then tucks default and override behavior into the second clause without any 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, low-risk listing tool with fully documented optional parameters, the description covers everything necessary for correct invocation. No output schema exists, but the return value (table/view names) is self-evident from the tool name and description. It is complete enough, though it could theoretically mention whether views are included (it does) and if filters are supported (they aren't).

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

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

Schema coverage is 100%, with all three parameters already described in the input schema. The description adds marginal value by emphasizing the public default and the optional nature of database/profile overrides, but the schema alone mostly suffices. This meets the baseline without going beyond it.

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 the specific verb 'List' and a concrete resource, 'tables/views for a schema', immediately distinguishing this from siblings like pg_list_databases and pg_list_schemas. The default schema and overrides are stated clearly, leaving no ambiguity about the tool's role.

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

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

The description makes the use case clear: call this when you need to enumerate tables/views in a schema, with optional database/profile overrides. It does not explicitly discuss when not to use it or route to alternatives, so it stops short of a 5, but the context is unambiguous.

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 the read-only default, which is useful, but the phrase 'by default' is ambiguous – it implies a possible write mode that no parameter or note explains. Also lacks details on transaction behavior, error handling, or result format, leaving gaps for a data-access tool.

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

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

Three short sentences, front-loaded with the core purpose, and every sentence earns its place. No fluff or repetition of schema details.

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?

Complete for a query tool: parameters are documented, the key behavioral trait (read-only) is noted, and the agent knows not to ask for credentials. Missing return format and error semantics are minor for an ad-hoc query tool, and no output schema exists to fill that 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 covers all parameters at 100%, so baseline is 3. The description adds the sticky-session concept, clarifying how the profile parameter behaves beyond the schema's enumeration. This extra context about profile selection and the default behavior is genuine added value.

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

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

States a specific action (Run SQL) against a defined resource (sticky session profile) with optional overrides. Clearly distinguishes from sibling tools that manage profiles, list metadata, or describe tables – this is the only tool for arbitrary SQL execution.

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?

Provides clear context on using the sticky session profile versus a one-off dev/qa profile, and explicitly instructs the agent not to ask for connection credentials. Does not name sibling tools or state when not to use it, but the profile guidance is actionable and sufficient.

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

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

The description discloses key behavioral aspects: it sets a sticky session profile, loads credentials from environment variables (PG_DEV_*, PG_QA_*), and indicates that later tools reuse the profile automatically. This transparency is sufficient given no annotations are provided.

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

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

The description is concise and well-structured. It flows logically from the core action to trigger phrases, then explains the persistence and credential source, all in a few sentences without unnecessary 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?

The description covers the tool's purpose, when to use it, how it affects subsequent tools, and the source of credentials. It provides enough context for an agent to understand the tool's role and side effects, even without an 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?

The input schema descriptions for both parameters are thorough: the 'profile' parameter lists allowed values and aliases (development, uat), and the 'verify' parameter explains its effect (runs SELECT 1). With 100% schema coverage, each parameter's meaning is 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 clearly states the tool's action: setting the sticky session connection profile to dev, qa, or default. It also provides concrete trigger phrases (pgprofile=dev, use Dev DB, etc.) that make the purpose unmistakable, even without referencing sibling 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 when to call the tool ('Call when the user says pgprofile=dev, pgprofile=qa, use Dev DB, switch to QA, etc.') and explains that later tools reuse this profile automatically, establishing it as a prerequisite for subsequent operations. This gives clear context for when to invoke it.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses that the tool performs a live SELECT 1 health check and that using the profile arg does not change the sticky session. This gives important non-obvious behavior even without an annotation layer.

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 deliver the tool's core action, the state elements, and the key exception about optional profile behavior. No filler, well-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?

For a status tool with two optional parameters fully documented in the schema, the description fully captures what the tool does and the nuance of the optional profile. No output schema exists, but the listed return fields (profile, host, database, write mode, health) give the agent a complete picture of the response.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description additionally clarifies the sticky-session behavior of the profile parameter, adding context beyond the schema's technical format.

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 uses the specific verb 'Show' and lists the exact state being displayed (profile, host, database, write mode, SELECT 1 health check). It clearly distinguishes this from sibling tools like pg_set_profile, which changes the profile, and pg_query, which runs queries.

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 explains the optional profile argument for a one-shot check without altering the sticky session, which implies when to use it. It doesn't explicitly state when not to use it or name alternatives, but the context is clear enough for typical status-check usage.

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