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

Goes well past the readOnly/idempotent annotations: it documents the return fields (query_id, state, rows, row_count, truncated, elapsed_ms, result_digest), hard caps (max_rows, wait_seconds), the 16 KiB trimming with rows_omitted, and timeout behavior via query_timed_out. It also flags untrusted_provider_content labelling and instructs treating it as evidence, not instructions.

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?

Front-loaded with purpose and the key check-the-data framing, and nearly every sentence carries operational value. It is a single dense paragraph, though, and repeats several cap placeholders ($DEFAULT_QUERY_ROWS, $MAX_QUERY_ROWS), which slightly blunts scannability.

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 5-param tool with no output schema, the description supplies an inline example, the shape of successful and timed-out responses, result-size constraints, and the safety labelling of returned content. Nothing an agent needs to call it correctly and interpret the result is missing.

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 and largely does: it constrains sql (single statement beginning SELECT/WITH/EXPLAIN/DESCRIBE), explains max_rows and wait_seconds caps, and shows query_id reuse to read the same execution. run_id is only implied, but the semantic additions are substantial.

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?

States a specific verb and resource: runs one read-only SQL statement over the parquet a run sealed, exposed as the run_table relation. It explicitly disambiguates from the sibling query_table by noting 'not the recipe table name', so an agent can tell them apart without opening schemas.

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?

Gives an explicit when-to-use ('THIS IS HOW YOU CHECK THE DATA IS RIGHT after a successful run: count the rows, look at the range, find the nulls') and an alternative route for wide results ('or download the parquet with get_artifact_download'). The timeout-recovery flow (call again with query_id and no sql) further frames correct use.

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