ch_sample_data

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

No annotations are provided, so the description carries the burden of disclosing behavior. It adds that the tool returns up to 100 rows and that omitting database uses the default database, which goes beyond the schema. However, it does not disclose sampling method, determinism, or permission requirements, leaving behavioral transparency partial but not wholly absent.

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 primary purpose in the first sentence. The Args section is compact and avoids fluff, making it easy to scan. Every sentence contributes useful information without redundancy, achieving high information density.

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 and the presence of an output schema, the description is largely complete. It covers purpose, usage context, and parameter semantics. It lacks a brief note on how the sample is selected or a pointer to alternative tools for non-sampling queries, but these are not critical gaps for a simple read-only sampling 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. It adds meaning for 'database' ('If omitted, uses the default database') and 'limit' ('Number of rows to return (1-100, default 10)'), which are not fully expressed in the schema. The 'table' parameter is merely restated as 'Table name,' which adds no semantic value beyond the schema, but overall the description meaningfully enriches parameter understanding.

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 function: 'Get sample rows from a ClickHouse table (up to 100 rows).' It specifies a concrete verb ('Get'), a resource ('ClickHouse table'), and a scope ('sample rows'), which distinguishes it from sibling tools like ch_list_tables, ch_describe_table, and es_sample_data. The purpose is immediately clear 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 provides clear usage context: 'Useful for understanding telemetry data structure before writing queries.' This tells the agent when to invoke this tool, but it does not explicitly state when not to use it or mention alternatives like query_clickhouse for arbitrary querying. Because it gives a clear context without exclusions, it earns a 4 rather than a 5.

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