download_analytics_report_segment

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

With no annotations, the description carries the behavioral burden. It discloses that the action involves decompression, returns CSV/TSV text, and that the URL must originate from list_analytics_report_segments. It does not mention authentication or error behavior, but the key behavior is transparent enough for a read-only download action.

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?

Three short sentences cover purpose, output format, and usage prerequisite with no wasted words. The most important constraint is front-loaded effectively.

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 single-parameter, no-output-schema tool, the description provides everything an agent needs: operation, decompression, return type, and exact source of valid input. The prerequisite dependency on list_analytics_report_segments makes the tool self-contained in context.

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 100% since segment_url is documented as 'The url field of an analytics report segment.' The description adds extra meaning by calling it a presigned URL and by restricting valid URLs to those returned by list_analytics_report_segments, which helps the agent understand what value to pass.

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 uses a specific verb and resource: 'Download and decompress an analytics report segment from its presigned URL.' It also clearly states the return format (CSV/TSV text), which distinguishes this download action from the sibling list tools.

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?

It explicitly tells the agent to call list_analytics_report_segments first and that only URLs returned by that tool can be downloaded. This is a clear prerequisite and exclusion, making the usage condition unambiguous even without naming alternative download tools.

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