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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: 'Nothing is downloaded', the default/max page size, and the untrusted_provider_content treatment of source-derived values. No return format or pagination edge cases are left unexplained, but the annotations carry most of the safety weight.

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 the resource definition and the core sharding trick, and nearly every sentence carries operational content, including a full inline return shape that substitutes for the missing output schema. It is dense to the point of being a run-on, with a stray fragment ('"table_id": "…"') breaking the flow, which keeps it from a 5.

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 read-only list tool with no output schema, the description supplies the return object shape, the pagination contract, the untrusted-content handling, and the type-comparison caveat for bounds. Nothing an agent needs in order to page, shard, or safely interpret results 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?

With 0% schema description coverage the description must carry all four parameters, and it does: table_id is shown, table_version_id defaults to the live version and is cross-referenced to get_run's table_version_id, limit defaults to 25 with a max of 100, and cursor is described as the next_cursor follow-on. This adds semantics the schema alone cannot convey.

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 ('Lists the parts (parquet files) one table version is made of') and immediately enumerates what a part contains, so an agent knows exactly what comes back. It is clearly distinguishable from siblings like get_table (metadata) and verify_run (byte verification) because it explicitly positions itself as the listing step before verification.

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 concrete when-to-use guidance (sharding a training loader by index % N), how to page (follow next_cursor with cursor), and how to filter (compare a range against each part's bounds for the sort field). It also names an explicit boundary versus an alternative: 'Listing proves nothing about the bytes; verify_run with deep checks them.'

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