preflight__check_subscription

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

Goes well beyond the readOnlyHint/idempotentHint annotations: discloses 20-subscription cap in group mode, read capping with reported truncation, and explicitly frames the semantics of 'ready' as no observed blocking catalog gaps — not an Apple approval prediction. That boundary is unusual and valuable; it stops the agent from overclaiming. No return-shape detail, but output schema exists.

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?

Front-loaded purpose, then parameter guidance, then scope/limits, then a single crisp caveat sentence. Every sentence earns its place; no 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?

For a validation tool with an output schema, the description covers everything an agent needs: what is checked, what 'ready' means, mode selection, caps and truncation, and the read-only guarantee. Nothing material is missing.

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%, so baseline is 3, but the description adds real semantics: the subscription/group mutual exclusion, the accepted identifier forms (product ID, name or ID; reference name or ID), and the per-mode group behavior. These matter for calling correctly and partially duplicate the schema's 'cannot be combined with group'.

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?

Specific verb + resource: 'Check subscription catalog readiness before submitting for review' — a distinct, non-tautological purpose. It scopes exactly what is validated (localizations, group locales, prices, plan availability, review screenshot, review note, required attributes) and distinguishes itself from preflight__check_version and release__submit by targeting subscription readiness.

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?

Explicit precondition ('before submitting for review'), explicit alternative selection rule ('Give the app and either a subscription ... or a group'), and the constraint that group mode covers at most 20 subscriptions and cannot combine with subscription. The agent knows exactly which parameter to supply and when.

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