export audit log

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

The description adds substantial behavior beyond the annotations: row ordering, silent cap at 50000, truncated indicator semantics, empty-not-error behavior, Cache-Control no-store, and exact CSV/JSON shapes. Annotations already declare readOnlyHint=true and idempotentHint=true; the description fully aligns with these, noting the API key scope and read-oriented export behavior. No contradiction.

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 complete and front-loaded with the core export purpose, then format and endpoint details, then notes. It is long but each sentence carries functional value (ordering, truncation, empty set, cache), and the structure keeps the most decision-relevant information near the top. It could be tightened slightly, but for a tool with four parameters and two output formats this is appropriately dense.

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?

Given four optional parameters, full schema coverage, no output schema, and annotations covering safety, the description covers the necessary invocation details: endpoint, auth scope, exact JSON return fields, CSV header and Content-Disposition, truncation indicator, ordering, cap, empty-set behavior, and caching. An agent has enough to select, call, and interpret results without guessing.

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?

Input schema coverage is 100%, so the baseline is 3; the description adds useful behavioral context around parameters: limit is silently capped at 50000 (schema says the same, but description reinforces the default and cap effect), since/until constrain row timestamp, and format's default is csv, matching the schema. It slightly clarifies that the date bounds are inclusive and HTTP 400 on unparseable values, which is already in the schema, but also explains how the format changes the response (JSON vs CSV attachment).

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 names a precise verb (export) and resource (this workspace's audit rows), and details the hash-chain fields (seq, prev_hash, row_hash) that distinguish it from other audit-related tools. It clearly differentiates export_audit_log from siblings such as list_logs/export_logs and the audit tombstone/verification 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?

The description states the tool returns audit rows for verification of hash consistency, says it exports as CSV or JSON, and notes the empty-set behavior when the log store is unavailable. It explains the accepted formats and response details, though it does not explicitly enumerate when to prefer this over sibling tools or when not to use it.

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