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

With annotations present, the description goes well beyond them: it clarifies that 'applied' means the page is on the screen, not that a tap occurred, describes the onboarding_completed event and the page-state fallback (key onboarding_complete) when event reads are unsupported, and explains operation retention via support.limits.operations_retained and how repeated client_request_id values return the original operation only while it is retained. That is genuinely useful behavioral context an agent could not derive from readOnlyHint=false, idempotentHint=false, and destructiveHint=false.

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 opening clause is well front-loaded, but the body is a dense chain of long sentences with nested qualifications (event history, saved state, retention, replay) that could be split into short labeled statements. Little is truly redundant, but the structure makes the key points hard to scan.

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 mutation-ish display tool with an output schema already present, the description covers the important unknowns: what 'applied' means, the tap-to-event path, the page-state fallback, and replay/retention behavior. Completeness is strong; only the device authorization requirements and the distinction from sibling rendering tools are left thin.

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 description coverage is 0%, so the description must carry the load, and it does for the most consequential parameter: client_request_id is explained in terms of fresh vs. reused pages, inherited saved state, and operation retention/eviction. The device parameter is only obliquely covered ('one authorized screen') and template is effectively fixed by the const in the schema, leaving minor gaps.

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 opening sentence gives a specific verb and resource: shows a reviewed, self-contained template on one authorized screen, with onboarding.v0 named as the first-connection test. It is clear what the tool does, but it never contrasts itself with siblings such as display_show_default or display_render_html, so the agent must infer which screen-rendering tool applies.

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?

Usage is only implied: onboarding.v0 is described as the first-connection test, which hints at the initial-setup scenario, and the DEVICE_CAPABILITY_UNSUPPORTED passage hints at a fallback path. There is no explicit statement of when to choose this over display_show_default or display_render_html, and no stated preconditions beyond 'authorized screen'.

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