Build a download link

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it states that nothing is fetched or rate-limited, meaning the tool only constructs a URL and does not perform a download. This prevents an agent from expecting data to be returned directly. It could mention that the URL may expire or require authentication, but the existing disclosure is strong.

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?

Two sentences with no filler. The core purpose is front-loaded, and the key behavioral caveat ('Nothing is fetched or rate-limited here') is included without redundancy. Every sentence earns its place.

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 tool that generates a URL, the description covers the essential context: what it returns, when to use it, and what to do with the result. The schema provides parameter details, and annotations cover safety. A minor gap is that the description doesn't mention whether the URL is temporary or requires authentication, but given the tool's simplicity and the existing schema/annotations, it is largely complete.

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 63%, so the schema documents most parameters. The description adds context that the URL returns the whole result in a format, which maps to the 'format' parameter, but it doesn't explain the meaning of 'dataset', 'start', 'end', 'filter', 'columns', 'sort', or 'limit' beyond what the schema already provides. The description doesn't compensate for the undocumented parameters (e.g., 'sort' has no schema description), but the schema covers the majority.

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 states a specific verb ('download'), resource ('URL'), and purpose ('returns the whole result as CSV, JSON or Excel'), and distinguishes it from conversation-passing by noting it's for extracts too large to pass through a conversation. It clearly differentiates from siblings like query_dataset by emphasizing it produces a URL rather than returning data inline.

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 explicitly says when to use it ('for extracts too large to pass through a conversation') and what to do with the result ('give the URL to the user or to a shell'). It also clarifies what it is not ('Nothing is fetched or rate-limited here'), which helps an agent avoid calling it when actual data retrieval is needed.

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