fetch_data_to_file

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

With no annotations, the description carries the full burden and discloses three non-obvious behaviors that cannot be inferred from the schema: nothing is 'loaded into memory or context,' output is capped at '25,000 records' without an API key, and the tool returns a path for later analysis. These traits directly affect whether an agent should select this tool and what to expect from it.

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?

Four short passages, each earning its place: primary behavior, when-to-use examples, the API-key cap caveat, and the return value. The most decision-relevant sentence is front-loaded first, and no sentence is redundant with the schema.

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 4-parameter tool with an output schema, the description covers the call-relevant facts: use case, cap condition, auth hint, and return value. Minor gaps remain — no statement about overwriting an existing filename, failure behavior, or whether the returned path is locally accessible to the agent versus only on the server — but nothing essential to invoking it 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 description coverage is 100%, so the baseline of 3 applies; the schema already documents dataset_id, filters, filename, and select. The description adds little per-parameter detail, though it reinforces the 'unrestricted query' semantics of filters and that output lands in the server's download directory.

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?

Opens with a specific action — 'Stream an unrestricted query to a CSV file' — and immediately contrasts it with the reply-returning behavior of the sibling fetch_data. The later phrase 'rather than paging fetch_data hundreds of times' explicitly names the closest alternative, so an agent can tell the tools apart without opening either schema.

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 conditions: 'results too large to read' with realistic examples (whole geography types, long time series, LSOA-level census tables). It names fetch_data as the alternative and even routes to check_auth when the row count 'looks suspiciously round.' The only minor omission is an explicit when-not-to-use for small results, but that is strongly implied by 'instead of into the reply.'

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