Sample rows

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description need not restate safety. It adds substantive behavioral detail: secret-looking columns are masked, results are capped by both row count and size, and truncation is reported. This meaningfully exceeds the structured 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?

Three sentences with no fluff. The core action is front-loaded, and each subsequent sentence adds distinct value: masking behavior, cap behavior, and truncation notification. Nothing extraneous is present.

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 3-parameter tool with strong annotations, the description covers the important runtime behaviors: masking, cap limits, and truncation response. It could be slightly more explicit about the exact shape of the returned result (e.g., whether column names/types are included), but overall it is complete enough for correct invocation.

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%, and the schema already documents limit (including default, min, and max), table, and schema. The description adds no parameter-level meaning beyond what the schema provides, so the baseline 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 uses a specific verb and resource: 'Return the first few rows of a table'. This clearly distinguishes sampling data from sibling tools like describe_table (structure) and run_select (arbitrary queries), and the added 'shape of the data' purpose makes intent unmistakable.

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 'so you can see the shape of the data' clause gives a clear implied context, but the description never explicitly states when to use this tool versus alternatives like run_select or describe_table. There is no when-not guidance or named sibling fallback, so the agent has to infer selection criteria.

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