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

The annotations already mark the operation as read-only, and the description adds useful behavioral context by explaining that the tool returns per-column type information plus non-obvious column notes and known data caveats. It does not discuss auth, rate limits, or side effects, but the absence of side effects is already conveyed by the readOnlyHint.

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 efficiently cover what the tool returns and when to call itainer. There is no redundant restatement of the tool name or title, and 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 simple, read-only, single-parameter introspection tool, the description is complete: it states the resource, the output, the caveats, and the correct point in the workflow. No critical missing context would prevent an agent from using 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 100%: the only parameter, 'table', is fully documented with a name, type, and example value. The description does not add any extra parameter-level guidance, so the baseline score of 3 is appropriate.

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 resource ('one table'), the kind of information returned (columns with ClickHouse types, notes, data caveats), and distinguishes it from siblings like list_tables by narrowing scope to a single table. It also frames the tool as a pre-SQL inspection step rather than a query execution tool like run_sql.

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 an explicit trigger: 'Call before writing SQL against a table.' This tells the agent when to use it, though it does not explicitly name alternatives or say when not to use it. The intended placement in the workflow is still clear enough to guide selection.

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