async_run_report_by_id

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

Annotations mark this as destructive and non-read-only; the description adds the key side effect that a normal call creates an operation, while dryRun avoids it. It also discloses the immediate 202, Location header, and required Idempotency-Key header—information not present in the annotations. It does not mention downstream result retrieval or potential cost, but it is substantially transparent.

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 compact and front-loaded: the operation is stated in the second sentence, followed by response shape, idempotency requirement, and dryRun behavior. The first 'Manage Cloud Analytics reports and get reports data in JSON format' sentence is somewhat generic and could be trimmed, but the rest earns its place.

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?

It covers the essentials for invoking the tool: required header, dryRun validation, async creation, and the Location header. But because there is no output schema, the description should also point toward polling or result retrieval via the async operation endpoints, and it does not clarify the date/timeRange override parameters. The destructive annotation also makes it worth explaining more about what executing a report entails.

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?

The description adds meaning beyond the bare schema for the central parameters: id is the saved report identifier, Idempotency-Key is a required header, and dryRun validates without creating an operation. However, with schema description coverage at only 14%, the startDate, endDate, and timeRange parameters remain unexplained in both schema and description, leaving a real gap for optional date-range control.

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 concrete operation—submitting an async execution job for a saved report by ID—and states the immediate 202 response with Location header. This distinguishes it from related report tools like get_report_results, async_run_inline, and run_query. The opening sentence is broad, but the specific clauses carry the meaning.

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 gives clear context: use this tool when you need to execute a saved Cloud Analytics report asynchronously, and use dryRun=true to validate without side effects. It also makes the Idempotency-Key prerequisite explicit. It does not name alternative tools or explicitly say when not to use it, so it stops short of full routing guidance.

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