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

Annotations only cover the read-only/idempotent safety profile, but the description goes well beyond: bytes are never streamed through MCP, the workspace key requirement, free-sample boundaries, row/query quota consumption, and the exact failure mode (usage_limit_exceeded with reset time and upgrade URL). This is rich behavioral context an agent could not infer from structured fields.

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?

Dense but front-loaded with the return contract before quota details. Every sentence carries information (method/header, streaming caveat, key, quota, error). Slightly long, but nothing is filler.

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?

There is no output schema, and the description fully explains what the caller receives (request to issue, publish status), the prerequisite, and the limit/error behavior. Nothing needed to invoke and interpret the result correctly 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 coverage is 0%, but the single parameter is self-describing (a table_id, with format/pattern already enforced in schema) and the description supplies an example value. It adds marginal meaning beyond the schema and does not need to compensate further for a one-parameter tool.

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 precise verb+resource: returns the exact URL, HTTP method and header for downloading one table's current immutable Parquet snapshot, plus whether the publisher enabled it. An agent can distinguish this from get_artifact_download and query_table immediately.

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?

Explicitly says 'Prefer this over paging a whole table through query_table,' naming the alternative and the condition that selects it. It also states the prerequisite (mr_use_ workspace key) and that the result explains how to obtain one.

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