analytics_report_requests__create

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

Annotations only claim non-read-only, non-idempotent, non-destructive, which is minimal. The description adds genuinely valuable behavioral context: ONE_TIME_SNAPSHOT covers the past 365 days, ONGOING accumulates continuously, and a fresh request has no instances for a day or more. This latency disclosure is exactly the non-obvious trait an agent must know to avoid expecting immediate results. No contradiction with 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?

Three sentences, each earning its place: purpose, mode semantics, and latency expectation. The action is front-loaded, the mode explanation is compact, and no words are wasted.

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 one-parameter create call with nested body and no output schema, the description covers the domain, mode selection, and the key behavioral surprise (the wait). The only gap is that it doesn't mention the response shape — i.e., that a created request resource/ID is returned for follow-up GET/delete calls — which the agent must infer from the POST endpoint pattern.

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 100% (baseline 3), but the description adds real meaning beyond the schema by explaining what each accessType enum value does — ONE_TIME_SNAPSHOT = past 365 days, ONGOING = keeps going as new data arrives — which the schema merely lists. The app relationship is left to schema structure, but the critical decision parameter is semantically enriched.

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?

States a specific verb+resource: 'Ask Apple to start producing analytics for an app', with the endpoint POST /v1/analyticsReportRequests appended. The scope of the data (downloads, sessions, retention, crashes) is explicit. The 'start producing' framing clearly distinguishes this creation action from sibling get/list/delete/reports 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 provides useful invocation context by explaining the two access modes (ONE_TIME_SNAPSHOT vs ONGOING) and the delay before data exists. However, it never explicitly routes the agent between this tool and its alternatives — e.g., that checking status should go to analytics_report_requests__get or that removal is analytics_report_requests__delete. Usage context is clear, but when/when-not guidance is left to inference.

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