preflight__check_version

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

The readOnlyHint annotation is reinforced and extended by the description's explicit 'Read-only — it changes nothing and does not submit,' which adds the meaningful distinction that this tool will not trigger a submission. It also discloses the behavioral contract: it reports gaps, names the tool that fixes each gap, and inspects multiple areas of app metadata. The description fully describes what the tool does and guarantees beyond the annotation.

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 description is detailed but every sentence earns its place: the lead sentence states the core purpose, the middle enumerates what is verified, and the closing sentences establish behavioral guarantees and output shape. It is slightly longer than strictly necessary — the enumeration of checks could arguably live in the output schema — but the structure is front-loaded and logical.

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 composite preflight tool with an output schema present, the description is complete: it explains what the tool does, how to identify the target app, what criteria are checked, that the result is a gap list with remediation pointers, and that it is side-effect-free. The presence of the output schema relieves the description of explaining return values. Nothing critical is missing for an agent to invoke it correctly.

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 the schema already documents both parameters well. The description adds modest value by restating the app identifier formats ('name, bundle ID or Apple ID'), which matches the schema's app description, and confirms the version parameter's default behavior is schema-documented. With full schema coverage, the baseline of 3 is appropriate.

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 description opens with a specific verb+resource ('Check whether an app version is complete enough to submit') and clearly distinguishes the tool from the many sibling mutation tools, especially release__submit, by framing this as a non-submitting verification. It goes further to enumerate exactly which criteria are checked, so an agent knows precisely what the tool covers without opening the schema.

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 implies the clear usage scenario — run this before submitting a version — and the phrase 'does not submit' implicitly routes the agent away from release__submit. It does not name the sibling alternative explicitly or state when-not-to-use, but the read-only framing and the 'each gap names the tool that fixes it' behavior give sufficient contextual guidance for tool selection.

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