Create a screenshot set

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

Beyond annotations (readOnlyHint=false, destructiveHint=false) the description discloses the full cost model: 1 credit per image as screens × devices, +1 per feature graphic, all-or-nothing charging with the INSUFFICIENT_CREDITS error code, refunds on failure, and free dryRun quotes. It also discloses the 50-image cap, the test-key behavior that never spends credits, and that screens with { path } are uploaded first even in dryRun — none of which is inferable from 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?

It is front-loaded with the core action in sentence one, then layered into when-to-use, cost, and limits. There is minor redundancy: dryRun as a cost preview appears in both the 'When to use' paragraph and the credits paragraph, which could be merged without losing information.

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 10-parameter nested tool with an output schema, the description covers the high-risk essentials: cost, caps, dryRun, upload semantics, and the async job follow-up. It leaves orientation and projectId unexplained, and does not note that waitSeconds should be kept below ~50s (the schema carries that), so it is strong but not airtight.

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 40%, and the description compensates well by explaining that screens accept either { uploadId } or { path }, that each has exactly one caption, that omitting devices yields the store's required sizes, and that the feature graphic is Google Play only. It adds nothing on orientation, projectId, waitSeconds or idempotencyKey, though the schema itself documents the latter two, leaving a modest gap.

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 states a specific verb+resource with scope: 'Makes a whole store listing in one job' covering 1-10 screens across devices on one or both stores. The batch framing implicitly distinguishes it from single-image siblings like generate_screenshot and upload_screenshot, but no sibling is named outright, so differentiation is inferred rather than explicit.

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?

It gives a direct 'When to use' clause (produce or refresh App Store / Google Play screenshots) and then prescribes the exact workflow: call first with dryRun: true on a live key, then get_job_status, then download_results with layout 'fastlane' for fastlane projects. That is explicit when-to-use plus named alternatives and follow-up tools, which is exactly the top bar.

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