ecp_postgres_list_columns

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It clearly states the operation is metadata-only and returns no row data, which is a key behavioral trait. However, it doesn't disclose whether the operation requires specific permissions, whether it fails on non-existent tables, or what the output format looks like. The metadata-only note is useful but the description is otherwise thin.

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 wasted words. It front-loads the action ('List'), the resource ('a table's columns'), and the key constraint ('metadata only, no row data'). Every word earns its place.

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

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

For a simple read-only metadata tool with two parameters and no output schema, the description is mostly adequate. It tells the agent what the tool does and that it doesn't return row data. However, it lacks details about the output structure (e.g., column names, types) and any prerequisites (e.g., table must exist), which an agent might need to interpret the result correctly.

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

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

Schema description coverage is 0%, so the description must compensate for the two parameters (db_name, table_name). The description mentions 'a table's columns' but does not explicitly explain that db_name identifies the database and table_name identifies the table. An agent can infer this from the parameter names, but the description adds no semantic value 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 specific verb ('List') and resource ('a table's columns'), and clarifies it is metadata only, not row data. It doesn't explicitly differentiate from sibling tools like ecp_mysql_list_columns or ecp_mssql_list_columns, but the 'postgres' prefix in the tool name and the metadata-only note provide enough clarity for an agent to understand the core function.

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 context: it is a read-only metadata operation for a Postgres table. However, it does not explicitly state when to use this tool versus alternatives like ecp_postgres_browse_rows (for row data) or ecp_postgres_table_sizes (for size info). The metadata-only note hints at the distinction but doesn't name alternatives or exclusions.

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