get_async_operation

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

With readOnlyHint=true and destructiveHint=false, annotations already signal safety, but the description adds valuable behavioral detail: Retry-After on non-terminal states, no result payload, RFC 9457 error shape on failure, and 404 semantics for missing/expired/foreign operations. This goes well beyond the annotations.

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 information-dense and mostly front-loads the core behavior, placing the key statement early. However, the opening sentence 'Manage Cloud Analytics reports and get reports data in JSON format' is a generic and somewhat misleading preamble for a status-polling endpoint. That reduces conciseness and clarity.

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 simple status-polling tool with no output schema, the description is highly complete: it covers all relevant statuses, polling guidance, error behavior, 404 conditions, and redirects to the results endpoint. An agent has enough information to invoke the tool correctly and interpret its response.

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 50%: customerContext is documented, but operationId only has a type and required flag. The description adds some behavioral meaning to operationId by explaining it identifies an async operation and can be invalid due to tenant mismatch or expiry. However, it does not tell the agent where operationId comes from or clarify the customerContext usage beyond what the schema already states.

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 specific verb and resource: it returns the current status of an async report operation. It also explicitly distinguishes itself from the results endpoint by stating it does not return result data. The opening sentence about managing Cloud Analytics reports is generic, but the subsequent precision resolves the tool's actual 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 gives explicit usage context: poll async operations using the Retry-After header for pending/running states, and switch to the results endpoint once status is 'succeeded'. It also states what this tool is not for, which is retrieving result data. This clearly routes an agent to the correct sibling tool.

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