get_async_operation_results

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

The description goes far beyond the readOnlyHint/destructiveHint annotations by disclosing three distinct error semantics (404 for missing/expired/wrong-tenant operationId, 425 for non-terminal state, 422 for failed/canceled operations), the response shape equivalence to GetReportResponse, and the fact that the status endpoint does not inline result data. This level of behavioral detail — especially the tenant-scoping and terminal-state nuance — is exceptional.

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 dense with high-value information (error codes, retry guidance, response shape, exclusivity claim), but it runs about 150 words and opens with a boilerplate sentence that doesn't uniquely describe this tool. The error-code enumeration is thorough but could be tightened into a more scannable form. Adequate structure but not clean.

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 only 2 parameters, no output schema, and no enums, this description over-delivers: it covers success shape, all three failure modes, the operational pattern (poll until terminal, then fetch results), and the relationship to the sync endpoint and the polling endpoint. The only missing piece is an explicit pointer to where operationId originates, which is reasonably inferred from 'async report operation' and the sibling async_run tools.

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 exactly 50%: customerContext has a full schema description, while operationId has none. The tool description compensates by giving operationId lifecycle meaning (must reference a succeeded async report operation; invalid/expired operations yield 404 and non-terminal ones yield 425), which helps an agent understand what value to pass. Small gap: it never explicitly says operationId comes from a prior async run call (e.g., async_run_report_by_id or async_run_inline), though this is strongly implied.

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 behavior: returns the result of a succeeded async report operation, with concrete metadata fields (id, reportName, owner, type, createTime, updateTime, urlUI) and the explicit distinction from the sync GetReportResponse. However, the opening sentence "Manage Cloud Analytics reports and get reports data in JSON format" is generic boilerplate that would apply to most sibling report tools, which slightly muddies the focus before the specific behavior is stated.

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?

Provides explicit routing guidance: when the operation has not reached a terminal state (425), the agent is told to poll the operation status endpoint instead and to honor its Retry-After guidance. The closing sentence — "this is the only endpoint that returns it" — tells the agent why this tool must be chosen over the polling endpoint for result data. This is model guidance for when-to-use vs alternatives.

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