sample_rows

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

Annotations already declare read-only and non-destructive, and the description adds behavioral detail by specifying the operation as 'SELECT * LIMIT n', including default row limit and schema/database resolution (session schema then 'public'). This goes beyond the annotations.

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 compact, front-loaded with a clear summary, then a SQL equivalence, and then a tidy Args list with defaults. 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?

With an output schema present, the description doesn't need to detail return values. It covers the core functionality, defaults, and fallback behavior for a simple sampling tool. It could mention anything about edge cases, but not required for this simplicity.

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%, so the description carries the burden. It explains each parameter: table name, limit with default 10, schema with fallback to session then public, database with session default. This adds meaning beyond the schema's simple titles.

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 'Fetch a handful of rows from a table' and provides the equivalent SQL 'SELECT * FROM schema.table LIMIT n', which precisely defines the action and scope. It distinguishes itself from siblings like run_query and count_rows by focusing on raw data preview.

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 indicates the use case 'to see what the data actually looks like' and provides the SQL equivalent, implying it's a quick sampling tool. However, it does not explicitly state when not to use it or compare it to run_query or distinct_values.

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