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

With no annotations, the description carries the full burden. It discloses the output format (artifact_ref and download_endpoint), the one-hour expiry, the 5 MiB limit, and authentication requirements. It also explains export_mode behavior. It does not mention side effects beyond the export (e.g., whether it's read-only), but the confirm_export flag suggests it may trigger an operation, yet the description clarifies it returns a download link, which is transparent enough.

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?

The description is a single dense paragraph that front-loads the core purpose and mode behavior. It includes critical usage details (requirements, security) without excessive verbosity. It is well-structured, though it could be slightly more scannable with bullet points, but it earns a 4 for efficiency.

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 with 9 parameters, no output schema, and no annotations, the description is quite complete. It covers the required parameters, the response artifact, authentication, and attribution. It omits the date format and does not explain 'search', but these are minor gaps given the overall coverage. An agent can successfully invoke the tool based on this description alone.

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 0%, so the description must compensate. It does explain export_mode, attribution, confirm_export, and the scope filter requirement. However, it does not describe the 'search' parameter or the 'group_by' enum values beyond what the schema already lists. Since the schema provides the enums, the description adds some context but leaves several parameters without additional meaning, resulting in a moderate score.

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 clearly states the tool's function: 'Export insights as CSV' and distinguishes the two export modes with specific behavior. It is unambiguous about the resource (insights) and the action (export), and the mode descriptions (grouped vs. daily) differentiate it from other insights tools. The phrase 'Requires date_from, date_to, one scope filter...' further pinpoints its purpose.

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 lists required parameters and the condition confirm_export=true, giving clear 'when to use' instructions. It explains how to consume the download endpoint (GET with tenant Bearer credential) and forbids appending credentials to URLs. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of a perfect 5.

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