Data: export

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, and the description adds real side-effect context: streamed page-by-page fetching, writing to a local file or stdout with '-', and the overwrite guard ('won't overwrite an existing file unless forced'). It omits any permission/auth requirements or practical limits, so it is strong but not exhaustive.

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 sentences, front-loaded with the core action and formats, then the caveats. Slightly redundant phrasing of 'streamed page by page' / 'fetching page by page' in the first two sentences, but otherwise every clause carries information.

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 an 8-parameter export tool with no output schema, the description covers formats, filtering, field selection, overwrite behavior, and streaming. The only meaningful gap is the absence of auth/permission or throughput expectations; the destination and result (a file or stdout) are otherwise well explained.

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 baseline is 3, but the description adds meaning not in the schema: one-to-many fields are omitted unless explicitly named in the field list, and format defaults derive from the file extension. These are behavioral rules about the parameters rather than restatements.

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 (export records) plus the output formats (CSV, JSON, JSONL), and explicitly distinguishes itself from the sibling data_list. An agent can identify this as the bulk/paged export tool without opening a 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 an explicit routing rule: 'For one page of records, use data_list,' which is the exact counter-condition for this tool. It also tells the agent the filter syntax matches data_list, so filters can be reused without re-learning.

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