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

Annotations already declare the safe read-only, idempotent, non-destructive profile, but the description adds real behavioral context they don't carry: one screenshot preview is included, images may be unavailable, prototype indexes are zero-based while live gallery numbers are one-based, and legacy tests are supported. This is the kind of operational caveat an agent needs before calling.

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 action and its selector are front-loaded in the first sentence, and the remaining sentences are short and information-bearing. It is slightly choppy and 'Legacy tests also supported' partially duplicates the legacy note already in the blockId schema description, but no sentence is pure filler.

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?

Because an output schema exists, return values need not be described, and the description covers the non-obvious gaps: index bases, image availability, legacy support, and where to source IDs. It omits what 'metrics' entails and whether a missing screen or image produces an error versus an empty result, which are minor given the output schema.

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 only 25% (only blockId is documented), so the description carries most of the burden. It explains frameIndex's numbering scheme and where to obtain it, and points to list_test_blocks for block/run IDs, but testId and runId are never explained and the relationship between them is left implicit.

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 and resource ('Read one screen and its metrics') and names the input that selects it ('frameIndex from navigation results'), which cleanly separates it from list-style siblings like list_screen_metrics. It does not explicitly distinguish itself from get_frame_details, so an agent must infer the boundary.

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?

Gives useful sourcing guidance: frameIndex comes from navigation results, and block/run IDs come from list_test_blocks, with omission falling back to documented defaults. No explicit when-not conditions or direct sibling comparisons (e.g., vs. get_frame_details or list_screen_metrics), so it stops just 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.