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

Annotations already declare idempotentHint=true, destructiveHint=false, openWorldHint=true and readOnlyHint=false; the description adds value beyond them by naming the required credential (ASC_WRITE=1), disclosing that it runs as a resumable bulk job with progress, and explaining the mechanism behind idempotency ('steps already done are skipped'). It stops short of noting rate limits, partial-failure reporting, or what a resumable job returns, so it is strong but not exhaustive.

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?

Three sentences, front-loaded with the core action and scope, then the paid-offer exclusion, then the environment/permission caveat. Dense and largely waste-free, though the parenthetical '(or the ones you list)' is mildly redundant with the territories parameter.

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 7-parameter mutation with no output schema, the description covers the essential agent-facing facts: write permission needed, idempotent/resumable behavior, territory defaults, and the sibling to use instead. The remaining gap is that start_date/end_date semantics and their interaction with the offer window are left entirely to an undocumented 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 coverage is 57%: app, territories, dry_run and subscription carry their own descriptions, and the description's territory scoping largely restates the schema's 'Default: every territory the subscription is available in.' However, start_date and end_date have no description in either place, and the duration enum values are unexplained, so the description does not compensate for the remaining coverage 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?

States a specific verb and resource ('Adds a free-trial introductory offer to a subscription') plus the scope (every territory where it's sold, or listed ones). It is clearly distinguishable from remove_intro_offers and from the generic asc_request sibling it names.

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?

Explicitly routes the agent: free trials go here, paid introductory offers 'aren't covered; use asc_request for those'. It also states the skip condition (territories that already have an introductory offer), so both when-to-use and when-not-to-use are covered.

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

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

Annotations declare destructive/openWorld/non-idempotent, and the description adds substantial context beyond them: the base URL the path resolves against, the ASC_WRITE=1 environment requirement for POST/PATCH/DELETE, and the extra confirm: true gate on DELETE. That is exactly the auth/prerequisite detail annotations cannot express.

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?

Three dense sentences, each carrying distinct information (purpose, endpoint/auth mechanics, sibling preference), with the escape-hatch framing front-loaded and 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 an open-world raw-API tool with no output schema, the description covers the base URL, method/auth gating, delete confirmation, and return type (raw JSON). Pagination (all_pages) is only in the schema, and rate-limit behavior on Apple's API is unmentioned, leaving minor gaps.

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 high (83%), so the baseline is 3, but the description adds real meaning: path is relative to https://api.appstoreconnect.apple.com with a concrete example, and it explains that confirm: true is required for DELETE (linking a parameter to a method).

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 (calls the App Store Connect API directly) and resource (raw API path), explicitly positioning itself as an 'escape hatch' for gaps the workflow tools don't cover. An agent can immediately distinguish it from the ~30 workflow siblings like list_apps or submit_for_review.

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?

Explicitly says when not to use it ('Prefer the workflow tools') and why ('they check state, retry safely and wait for Apple's processing'), and names the alternative. It also gates usage by method: GET works read-only, writes need ASC_WRITE=1.

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

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

Annotations already declare destructive=true, but the description adds genuinely new behavioral context: the dry_run default-true confirmation pattern and the required ASC_WRITE=1 environment flag. These are the exact details an agent needs to avoid an unintended destructive call, and they go beyond what the annotations expose.

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?

Two tightly written sentences with zero filler; the action and scope come first, followed by the destructive/dry-run warning and auth requirement. Every sentence earns its place.

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 destructive mutation with no output schema, the description covers the essential concerns: what it changes, that it is destructive, the dry-run confirmation workflow, and the auth prerequisite. There is no output schema to explain, and nothing critical is missing for correct invocation.

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 100%, so app, dry_run, and platform are already fully documented in the schema (including defaults and the platform enum). The description only reinforces the dry_run default and does not add syntax or format detail beyond the schema, so the baseline 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 states a specific verb (withdraws/cancels) and resource (the app's active review submission), and narrows scope to submissions 'waiting for or in review'. The stated effect ('so the version can be edited again') tells the agent exactly what state change to expect, distinguishing it cleanly from siblings like submit_for_review or prepare_version.

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 clear precondition (an active submission in waiting-for or in-review state) and an explicit two-step invocation flow: call with the default dry_run, show the plan, then re-call with dry_run: false. It also states the ASC_WRITE=1 prerequisite. It does not name alternative tools, so it falls just short of the 5 bar.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false; the description adds genuinely new context on top of that: it requires ASC_WRITE=1, mutates App Store Connect, and concretely explains idempotency ('steps already done are skipped'). Return format is unaddressed, but no output schema exists to cover it.

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?

Purpose is front-loaded in the first sentence and the supporting detail is broken into short, scannable blocks with no filler. The trailing paragraph is slightly fragmentary ('Changes App Store Connect (needs ASC_WRITE=1). Safe to re-run...') but each clause earns its place.

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 an eight-parameter mutation tool with no output schema, the description supplies the key operational facts: auth requirement, idempotency, and the semantic difference between the two group types. Only per-parameter behavior for the optional flags is left entirely to the 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 75% and eight parameters exist, so the schema carries most of the load. The description adds conceptual meaning for the external/internal split and the public-link concept, but says nothing about feedback, all_builds, or public_link_limit, so it does not compensate for the remaining 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?

States a specific verb+resource ('Creates a TestFlight group') and immediately discloses upsert semantics ('or returns the existing one with the same name'), which cleanly separates it from list_beta_groups and invite_testers in the sibling set.

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?

Explains the internal vs external group distinction and what each can contain, giving the agent a clear basis for choosing a mode. It does not name an alternative tool or state when not to use this one, so it stops 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.

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, yet the description still adds material context beyond them: the two-step dry-run confirmation workflow, the ASC_WRITE=1 authorization requirement, and the fact that surviving screenshots retain their relative order. That is exactly the extra behavioral payload the rubric credits.

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?

Two short paragraphs with zero filler: the operation and its addressing modes come first, then the destructive/confirmation protocol. Every sentence carries information an agent needs.

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 7-parameter destructive mutation with no output schema, the definition covers what an agent needs: what is deleted, how targets are addressed, that it is destructive, the required confirmation loop, and the auth gate. Nothing essential 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 description coverage is 100%, so the schema already documents app, locale, version, platform, dry_run, screenshots and display_type. The description adds only the '1-based' indexing detail for positions, which is genuinely absent from the schema, but otherwise restates what is already structured (e.g. the dry_run default). Baseline 3 is the right level.

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 ('Deletes screenshots') plus the two addressing modes (1-based position or ID), and the ordering side effect on remaining items. An agent can distinguish this immediately from replace_screenshot, reorder_screenshots, upload_screenshots and list_screenshots without opening any 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?

Gives a concrete operational protocol: dry_run defaults to true, show the plan to the user, then re-call with dry_run: false, and notes the ASC_WRITE=1 prerequisite. It does not explicitly route between this tool and its nearest siblings (replace_screenshot / reorder_screenshots), so it stops short of full alternative selection guidance.

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

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

Beyond the annotations (idempotentHint/destructiveHint/readOnlyHint), it discloses the required environment flag (ASC_WRITE=1), that it mutates App Store Connect, and the mechanism behind idempotency: every step checks current state first, so already-done steps are skipped on re-run. It also explains the resume behavior when Apple processing exceeds wait_minutes. This is context an agent cannot get from the annotations alone.

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 with the core action, then the operational caveats (auth flag, safe re-run) in a short second paragraph. The first sentence is a long comma-chained list of steps, which is dense but still scannable; nothing is wasted.

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 an 11-parameter mutation with no output schema, the description covers the workflow, auth prerequisite, idempotency, and partial-failure resume path, which is most of what an agent needs. It stops short of describing the shape of the returned plan/result (relevant for dry_run), leaving that to inference.

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 91%, so the schema already documents nearly every parameter; per the rubric the baseline is 3. The description adds only marginal framing (that the export-compliance answer is used "only if the build is waiting on it", and the conditional default for beta review), and does not address the undocumented notes_locale parameter.

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 names a specific verb+resource ("Ships a build to TestFlight testers") and then enumerates the exact sub-steps performed in the call: wait for processing, export compliance, What to Test notes, beta group assignment, beta app review submission. This clearly distinguishes it from siblings like upload_build (which only uploads) and submit_for_review (which only submits).

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 states the conditions under which optional steps fire ("answers export compliance if you say how", "submits it for beta app review when an external group needs it") and explicitly endorses re-running after a timeout or error. It never names a sibling alternative or an explicit when-not-to-use case, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond that: the payload is gzipped TSV, saving is optional, and the response includes row count, columns, totals and leading rows, plus the API key role requirement.

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?

Two sentences, front-loaded with purpose and return behavior, followed by prerequisites. Dense but every clause carries information; only slight cost is the run-on packing of output fields.

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 tool with no output schema, the description covers purpose, return shape, auth and the vendor-number sourcing fallback. Remaining gaps (report_type/frequency interplay, save path semantics) are largely handled by the schema's enums and field descriptions.

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 60%, and the description compensates by disclosing that vendor_number can alternatively come from the ASC_VENDOR_NUMBER environment variable – a fact absent from the schema – and by naming the required key role. It does not explain kind/frequency/report_sub_type semantics, but those carry enums and defaults.

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 (downloads) and resource (sales or finance report), plus the return format (Apple gzipped TSV) and what the tool yields. No sibling tool overlaps with report retrieval, so the agent can route to it unambiguously.

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 explicit prerequisites: the vendor number (with where to find it in App Store Connect) and a key carrying the Finance or Sales role. It does not spell out when-not-to-use or name alternatives, but no sibling tool competes for this task, so the guidance is effectively complete for context.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior. The description adds valuable context by enumerating the categories of data returned, which matters especially because there is no output schema. It still does not describe return format, pagination, or authentication expectations.

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 a single front-loaded sentence that begins with the purpose and then efficiently enumerates the data categories. Every listed item earns its place by clarifying the scope of the overview.

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 read-only aggregate tool with full annotation coverage and a fully documented single parameter, the description gives enough context about what will be returned. It could be slightly more complete by hinting at output structure or how to interpret the states, but no critical information 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?

There is a single optional 'app' parameter with 100% schema description coverage, including the default fallback behavior. The description adds no additional parameter semantics, so the baseline 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?

States a specific purpose: a one-call overview of an app covering versions, builds, TestFlight states, processing uploads, and open submissions. It clearly distinguishes itself as an aggregate status tool, though it does not explicitly name granular siblings like list_apps or list_builds.

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 phrase 'One-call overview' implies the tool should be used when an agent wants a combined snapshot rather than multiple list/get calls. However, there is no explicit when-to-use guidance, no exclusions, and no named alternative to route to for narrower queries.

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

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

Annotations already declare readOnlyHint, idempotentHint true and destructiveHint false, so safety is covered by structured data. The description adds non-obvious behavior: the tool can block for a bounded period (wait_minutes), processing typically takes 5-30 minutes, and a timeout result explains how to resume. It doesn't mention auth/permission scope or result truncation, keeping it short of a 5.

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?

Two sentences, zero filler, with the core purpose and return contents front-loaded before the operational note about wait_minutes. Every clause earns its place.

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?

There is no output schema, and the description usefully compensates by listing what the response contains, which is the key thing an agent needs to decide whether to call it. With 100% schema coverage and read-only annotations, the remaining gap is minor: no guidance on the singular-vs-list choice against list_builds.

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 100% for all five parameters, including defaults (latest build, ASC_APP_ID, IOS), so the schema already carries the semantics. The description's only parameter-related addition is restating the purpose of wait_minutes, which the schema already explains; baseline 3 applies.

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 names a specific verb and resource ('Shows one build in detail') and enumerates the returned facets: processing/TestFlight states, export compliance, beta review, groups, What to Test notes and the attached App Store version. The word 'one' implicitly separates it from list_builds, so an agent can route between them without opening a 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 second sentence gives a real usage cue for the wait_minutes parameter ('wait for Apple to finish processing a fresh upload'), but there is no explicit when-to-use/when-not framing and no alternative named (e.g. list_builds for enumeration, get_app_status for readiness checks). Usage is implied rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuine behavioral value beyond that: it discloses derived data ('character counts against Apple's limits') that the agent cannot infer from the schema, plus the breadth of what is retrieved.

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?

A single front-loaded sentence that leads with the verb and resource before listing contents. It is dense but every element earns its place; slightly long, but no padding or repetition.

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?

With five optional parameters and no output schema, the description usefully compensates by enumerating the return contents. The only minor gap is that it doesn't restate the default version selection (editable/live), though that is fully handled in the 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 100%, so all five parameters (app, full, locale, version, platform) with their defaults and the enum are fully documented structurally. The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

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 ('Shows') and resource ('the App Store listing'), then enumerates the returned fields (name, subtitle, privacy URL, categories, description, keywords, age rating, review contacts). This clearly differentiates it from read siblings like list_apps/get_app_status and from the write-side siblings like update_listing and set_whats_new.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative is named. However, the exhaustive content enumeration implicitly tells an agent this is the tool to fetch the current listing, so usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds that replies and review IDs are returned and that ordering defaults to newest-first, but says nothing about pagination (limit max 200), rate limits, or auth requirements. Useful context, not rich behavioral disclosure.

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?

One sentence, front-loaded with the verb and resource, with the default ordering and the sibling pointer packed in without waste.

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?

With no output schema, the description usefully sketches the return payload (reviews, published replies, review IDs), which is the key thing an agent needs. It omits pagination behavior and how the filters (rating, territory, unanswered) compose, leaving a small gap for a 6-parameter listing tool.

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 50% and the description only touches the sort default ('newest first'), which merely restates the schema's default value. It adds no syntax or meaning for app, limit, rating, territory, or unanswered beyond what the schema already documents, so it neither compensates for the gap nor adds value.

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 ('Lists') plus resource ('App Store customer reviews') and scope ('newest first by default'). It also names what comes back (published replies, review IDs) and cross-references the sibling reply_to_review, so an agent can place it precisely in the review workflow.

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 establishes the default retrieval context ('newest first by default') and routes the agent to reply_to_review for the downstream reply action. There is no alternative review-listing sibling to contrast against and no explicit when-not condition, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is largely covered. The description adds the concrete auth prerequisite ASC_WRITE=1 and the external-vs-internal group constraint, which is useful, but the rerun-safety claim mostly restates idempotentHint and no return/pagination behavior is described.

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-loads the core behavior well, but the rerun-safety idea is stated twice ('Safe to re-run with the same list' and 'Safe to re-run: steps already done are skipped'), which is redundant rather than additive. Structure is otherwise fine but the duplication costs it.

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?

With no output schema and full parameter coverage, the description carries the mutation warning (ASC_WRITE=1), idempotency, and group-type constraints, which is close to complete for a write tool. It could mention return/permission-error behavior but nothing critical for correct invocation 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 description coverage is 100%, so the baseline is 3, and the description adds meaning beyond it by explaining how the 'group' parameter behaves differently for external vs internal groups (email acceptance rules). The 'testers' dedupe/merge behavior ('added to the group instead of failing') also clarifies semantics not stated in the schema.

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 ('Adds testers to a beta group') plus the scope of the operation, which cleanly distinguishes it from siblings like create_beta_group, remove_testers and list_testers. An agent can identify the operation 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?

Gives clear operating context: external groups accept any email while internal groups only accept App Store Connect team users, and reruns are safe. It does not name an explicit alternative tool or an exclusion condition, but the group-type rule plus idempotency note gives strong selection context.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so safety is covered; the description adds the meaningful extra context that results are scoped to the API key's permissions and enumerates the returned fields. It omits pagination/result-count behavior, which is the only notable gap.

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?

Two short sentences with no filler, front-loading what is listed and following with the practical next-step hint. Every clause carries 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?

With no output schema, the description usefully enumerates the return fields and positions the tool as the entry point. For a simple, no-required-param list call this is nearly complete, lacking only pagination or ordering details.

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 100% and the single 'name' filter is fully documented there, so the baseline of 3 applies. The description never mentions that results can be filtered by name, adding no meaning beyond the schema.

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 ('Lists the apps') plus the visibility scope ('this API key can see') and the returned identifiers (IDs, bundle IDs, SKUs), which separates it from the app-specific siblings. It never names a sibling directly, but the scope and payload make the distinction inferable.

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?

'Start here to find an app ID' gives clear entry-point guidance and implies that downstream tools (get_app_status, list_builds) require an app ID discovered here. No explicit when-not or alternatives are named, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real value by enumerating what each returned group carries (internal/external, build access, public link, feedback, tester count, ID), but says nothing about pagination, ordering, or rate limits.

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?

One dense sentence, front-loaded with the operation and resource, then listing the returned fields. Every clause earns its place with 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?

There is no output schema, so the description usefully compensates by telling the agent what fields the listing exposes. Combined with full parameter coverage in the schema, an agent has enough to call it correctly; only pagination/edge behavior is unstated.

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?

With a single optional parameter at 100% schema description coverage, the schema already documents the app identifier and its ASC_APP_ID default. The description adds no semantic detail about the app argument, so the baseline 3 applies.

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+resource ('Lists an app's TestFlight groups') and scopes it to TestFlight groups, which cleanly separates it from list_testers or list_apps. It does not, however, explicitly name or contrast with the sibling create_beta_group, so it stops short of full sibling differentiation.

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 is purely declarative about what is returned; it gives no when-to-use guidance, no prerequisites, and no pointer to alternatives such as create_beta_group for mutation or list_testers for the tester roster. Usage is only inferable from the tool name.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the meaningful behavioral detail that results are the app's most recent builds and include processing/TestFlight state, but it omits the default limit (10), what include_expired does, and whether results are paginated. With annotations carrying safety, this is adequate but not rich.

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?

A single compact sentence with the resource stated first and the payload contents second. Nothing is padded or redundant.

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?

With no output schema, the description partially compensates by listing the returned fields (processing state, TestFlight states, IDs). However, for a five-parameter listing tool it says nothing about default limit, expired-build inclusion, or result ordering, leaving real gaps for correct invocation.

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 60%: app, version and platform are documented in the schema, while limit (default 10, max 50) and include_expired (default false) have no description anywhere. The description adds no parameter-level meaning at all, so the two undocumented parameters remain opaque to the agent.

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 ('Lists an app's most recent builds') and names what the result contains (processing state, TestFlight states, IDs), so the agent knows this is a read-only build listing. It never names a sibling such as get_build for a single build or upload_build for creation, so the differentiation from neighbors is left to inference.

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?

There is no when-to-use/when-not guidance and no mention of alternatives like get_build for a single build. The phrase 'most recent builds' weakly implies a default recency-ordered listing, but nothing tells the agent when this is the right call versus another listing tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful behavioral context not in the annotations: results come back in display order with 1-based positions, plus file names, sizes, states and IDs. This is valuable since there is no output schema, though it says nothing about pagination or result-size limits.

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?

A single well-formed sentence that front-loads the verb and resource, then appends the returned field list. Every clause earns its place; the trailing enumeration is dense but directly useful given the absence of an output schema.

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 read-only list tool whose annotations carry the full safety profile and whose schema is fully documented with defaults, the description is nearly complete: it conveys the scope, grouping, ordering and returned fields. The only gap is the lack of any usage routing or result-volume context, which is minor here.

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 100%, so all five parameters (app, locale, version, platform, display_type) are already documented with defaults and enum values. The description only echoes that results are grouped per localization and display type, adding no syntax or format detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 states a specific verb (Lists) and resource (App Store screenshots) with scope (for a version, per localization and display type), and enumerates the returned fields. It is clearly a read operation, distinguishable from siblings like replace_screenshot, reorder_screenshots and delete_screenshots, though it never names them explicitly.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The only implied usage is that this is the read step before mutating screenshot tools such as reorder_screenshots, which the agent must infer on its own.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered structurally. The description goes beyond that by disclosing the shape and scope of returned data, notably that price is shown in one territory while introductory offers are summarized across territories, which is genuinely useful behavioral context not present in 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?

A single front-loaded sentence with the verb and resource first, followed by a parenthetical enumeration of returned fields. No filler, no restatement of the title, every clause carries 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?

With no output schema, the description must convey return contents, and it does so reasonably well by listing the fields returned. It is slightly incomplete on pagination/result-size behavior and on whether results span a single app or all visible apps, but nothing critical to invoking the tool 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 description coverage is 100%, so both parameters ('app' default resolution and 'territory' ISO code/default) are fully documented in the schema. The description's phrase 'price in one territory' loosely echoes the territory parameter but adds no format or default semantics beyond what the schema already provides, so the baseline of 3 applies.

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 (lists) and resource (subscription groups, their subscriptions, plus one-time in-app purchases), and enumerates the returned fields, so the agent knows exactly what domain this covers. It does not name or differentiate from any sibling (e.g. remove_intro_offers or add_free_trial, which touch the same subscription objects), so it falls short of a 5.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives or when not to use it. Usage is only inferable from the verb 'Lists'. This matches the MID calibration where a read tool with no routing guidance scored 2.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds that results carry email, name, status, invite type and groups, but says nothing about pagination, result limits, or auth requirements.

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?

A single front-loaded sentence with no filler. It is efficient, though it packs the return-field list into the same sentence rather than treating it as a distinct concern.

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 simple read-only list tool with fully documented parameters and annotations covering the safety profile, the description is nearly sufficient. Because there is no output schema, the returned-field enumeration adds real value; only pagination/limit behavior is left unaddressed.

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 100%, so app, email and group are all documented in the schema itself, including the ASC_APP_ID default. The description's mention of app/group scope adds no syntax or format detail beyond what the schema provides, so baseline 3 applies.

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 ('Lists') and resource ('TestFlight testers') with clear scope: for an app or for one group. The verb alone separates it from sibling mutations like invite_testers and remove_testers, though no sibling is named explicitly.

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 phrase 'for an app, or for one group' implies the two usage modes, and the schema notes 'Omit for every tester of the app.' However, there is no explicit when-to-use guidance or named alternative for the group-scoped vs app-scoped case.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, but the description adds real behavioral detail beyond them: metadata is copied from the previous version, an in-progress version may be renamed, and the write flag is required. The one gap is that it doesn't say what the call returns or how the rename branch affects an already-submitted version.

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 with the core behavior, then a separate sentence for auth and idempotency. The parenthetical about Apple copying metadata is high-value and every clause earns its place.

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 7-parameter mutation tool with no output schema, the description covers prerequisites, side effects and re-run safety well. It stops short of describing the result of a successful preparation (e.g. the created/renamed version identifier), which an agent may need to chain into submit_for_review.

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 71%, so most parameters are already documented. The description adds semantics for the build attachment and release type, but says nothing about earliest_release_date, platform defaults, or dry_run beyond what the schema states, so it only marginally exceeds the schema baseline.

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 names a specific verb (prepare) and resource (App Store version) and enumerates the three concrete branches the tool takes: reuse an existing version, rename the currently prepared one, or create a new one. No sibling tool (submit_for_review, get_listing, etc.) overlaps, so the agent can route to it without ambiguity.

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 states the operating prerequisite (changes App Store Connect, needs ASC_WRITE=1) and that re-running is safe, which tells the agent when invocation is allowed. It doesn't explicitly name a sibling alternative or a when-not-to-use case, but no sibling competes for this job, so the guidance is adequate.

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

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

Goes well beyond what annotations declare (destructive/idempotent/openWorld) by disclosing the bulk-job semantics: reports progress, continues past individual failures, stops early when the hourly rate limit runs low, and is safely re-runnable. The dry_run-defaults-to-true workflow and the ASC_WRITE=1 auth requirement are exactly the operational context an agent otherwise couldn't infer.

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 with the verb and scope, then a tight second paragraph on the destructive/dry_run contract. Every clause carries useful weight; the bulk-behavior sentence is dense but justified for a rate-limited batch operation.

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 destructive bulk operation with no output schema, the description supplies the missing pieces: progress/failure/rate-limit behavior, re-runnability, auth prerequisite, and the mandatory dry_run preview flow. Nothing essential to calling it correctly is left unexplained.

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 100%, so every parameter is already documented, including dry_run's default and the territory/offer_mode enums. The description reinforces the dry_run workflow but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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 (deletes) and resource (a subscription's introductory offers), with the scope explicitly qualified (every territory or only some). An agent can distinguish this from the inverse sibling add_free_trial 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?

Usage is strongly implied by the verb and by the dry_run workflow ('Show it to the user, then call again with dry_run: false'), which is clear procedural guidance. However, no explicit when-not condition or named alternative (e.g. add_free_trial as the inverse) is given, so routing is left to inference.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description goes well beyond them: it discloses the dry_run default of true, the mandatory show-the-plan-then-reapply sequence, the ASC_WRITE=1 environment prerequisite, and the non-obvious side effect that removing someone from their last group leaves them listed as a groupless tester.

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?

Two tight paragraphs, front-loaded with the scope distinction and followed by the operational workflow. Every sentence carries information the agent needs; there is 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 destructive mutation with no output schema, the description covers the safety workflow, the auth requirement, the scope semantics, and the surprising residual state. Nothing an agent needs to call this correctly 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 75% and the schema already documents group and dry_run. The description still adds meaning the schema does not: that omitting 'group' removes the tester from every group and revokes build access, and that the app-level removal is distinct from merely leaving them group-less.

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 (removes) and resource (testers) and precisely distinguishes its two operating modes: scoped to one beta group versus app-wide when 'group' is omitted. An agent can tell immediately what this tool does 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?

Gives explicit selection logic for the group parameter (omit it to remove completely) and a clear two-step dry_run workflow with a user-confirmation gate. It does not name a sibling alternative such as invite_testers or list_testers, but the conditions for using this tool are unambiguous.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds real context beyond them: the ASC_WRITE=1 auth requirement and the fact that already-applied steps are skipped on re-run. The 'safe to re-run' line partially restates idempotentHint, which keeps it from a 5.

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 with the core action, then the parameter semantics, then the safety/auth note. Every sentence carries weight and the example is compact. Slightly compressed wording ('after them') costs a little clarity, but nothing is wasted.

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 7-parameter mutation tool with no output schema, the description covers the non-obvious parameter, the required write scope, and re-run safety. It does not describe the return payload of dry_run or a normal run, which is a minor gap given no output schema exists to carry that information.

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 86%, so the baseline is 3, but the description meaningfully explains the one parameter the schema leaves undocumented: 'order' accepts 1-based positions or screenshot IDs, unlisted items retain relative order, and '[4] moves screenshot 4 to the front.' That is genuine semantic value beyond the schema, including the otherwise-unexplained mixed integer/string union.

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 states a specific verb and resource ('Changes the order of a screenshot set'), which clearly separates it from sibling mutators like upload_screenshots, delete_screenshots, and replace_screenshot. It is clear but never explicitly names or contrasts with those siblings, so it stops short of a 5.

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 implied by the ordering semantics and the worked example, so an agent can infer how to call it. However, there is no explicit when-to-use guidance, no prerequisites beyond the write scope, and no routing to alternatives such as replace_screenshot when the goal is substitution rather than reordering.

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

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

Goes well beyond the annotations (destructiveHint, idempotentHint, openWorldHint): it explains the upload-before-delete ordering, the exception when a full set of 10 forces the old image out first, the dry_run default flow, resume semantics, and the ASC_WRITE=1 permission requirement.

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 with the core action, then layered with the ordering nuance, resume behavior, and a clearly separated destructive/dry-run paragraph. The 10-item-set edge case is a bit granular but still earns its place as a real exception.

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 destructive tool with no output schema, it covers permissions, dry-run flow, ordering side effects, and how to recover a partial run. It could say more about what the dry-run plan or final result contains, but nothing an agent needs to call it correctly 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 the baseline is 3, but the description adds real meaning the schema does not: the position-vs-screenshot_id tradeoff ('safer than position when continuing an interrupted run'), the intent of the dry_run default, and where positions come from.

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 ('Replaces one screenshot with a new image, keeping its place') and pins the scope to a single item, which distinguishes it from the bulk siblings upload_screenshots, reorder_screenshots and delete_screenshots without needing to open a 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?

Gives clear operational guidance: identify by 1-based position from list_screenshots or by screenshot_id, run dry_run first and confirm, and re-call after an interrupted run. It does not explicitly name an alternative tool ('to add instead of replace, use upload_screenshots'), so it stops short of a 5.

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

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

Annotations already declare destructiveHint and idempotentHint, but the description goes well beyond them: dry_run defaults to true and returns a plan, a review holds at most one reply, replace deletes the old reply, replies are public, and ASC_WRITE=1 is required. This is exactly the mutation-specific context an agent needs before acting.

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?

Four tight sentences, front-loaded with purpose, then the safety workflow. There is mild redundancy: the dry_run default and the 'call again with false' instruction are repeated almost verbatim in the schema's dry_run description.

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 destructive, 4-parameter mutation tool with no output schema, the description covers the safety protocol, the permission prerequisite, and the one-reply-per-review edge case. Nothing an agent needs in order to invoke it safely 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 only 50% (text and replace have no schema descriptions), and the description compensates well for replace ('deletes the old reply and posts the new one') and the dry_run workflow. It says nothing extra about the text body, though maxLength/minLength are already encoded in the schema.

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 and resource ('Publishes a developer reply to a customer review'), which is unmistakably distinct from the read-side sibling get_reviews. The added semantics (single reply per review, replace behavior) make the operation's scope unambiguous without opening either 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?

It gives explicit when-to-use guidance: use replace: true to change an existing reply, and the dry_run two-step workflow ('Show it to the user, then call again with dry_run: false'). The prerequisite ASC_WRITE=1 is also stated, leaving little to inference.

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

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

Adds real information beyond the annotations: it names the auth prerequisite (ASC_WRITE=1), clarifies partial-update semantics ('Only fields you pass change'), notes the password is never returned, and explains the idempotent behavior ('steps already done are skipped'). This goes past the idempotentHint/destructiveHint hints, though failure behavior is unstated.

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: the first sentence gives purpose, fields, partial-update behavior, and the password note; the second carries the write requirement and idempotency. Tight and well ordered, with only minor redundancy around re-run safety.

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 12-parameter write tool with no output schema, the description covers the key decision-relevant facts: auth requirement, partial updates, and idempotency. It omits any description of the response shape and error handling, which keeps it short of fully complete.

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?

Description names the principal settable fields (contact name, phone, email, demo account, notes), which maps to roughly half the 12 parameters. With only 42% schema coverage, the app/version/platform selection and dry_run semantics are left largely to the schema, so it does not fully compensate for the 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?

States a specific verb and resource ('Sets the App Review information for the version being prepared') and enumerates the fields it controls (contact name/phone/email, demo account, notes). This clearly separates it from other version-config siblings. It stops short of explicitly naming an alternative, so it does not fully meet the 5 bar.

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 implied (App Review prep for the version being prepared) and the re-run safety is noted, but there is no explicit when-to-use vs when-not guidance and no alternatives named among siblings like prepare_version or submit_for_review. Requires inference to place in a workflow.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds real context beyond them: it names the external system mutated (App Store Connect), the required write credential (ASC_WRITE=1), and clarifies that re-runs skip completed steps. Return/result behavior is not described, keeping it out of 5 territory.

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?

Three short sentences, front-loaded with the purpose and target semantics, followed by the mutation target and safety note. Nothing redundant.

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 an 8-parameter write tool with no output schema and 75% schema coverage, the description covers purpose, both target modes, auth requirements, and idempotency. It omits only what a successful result contains and how the text length limit interacts with target selection.

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 75%, and the description supplies the one genuinely undocumented enum meaning: what 'app_store' vs 'testflight' do to text. That adds value beyond the schema, though the interplay of locale/platform/version with each target 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 ('Sets release notes') and immediately disambiguates the two modes: app_store writes the version's What's New, testflight writes a build's What to Test. No sibling tool covers release notes, so the agent can identify the capability 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 target semantics effectively tell the agent which mode to pick for a version vs a build, and it flags the ASC_WRITE=1 prerequisite. It stops short of naming alternatives or stating when not to use it (e.g. versus update_listing), but the context is clear.

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

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

Beyond the destructiveHint/openWorldHint/idempotentHint annotations, it discloses the safe default (dry_run=true returns a plan), the required human confirmation loop, the ASC_WRITE=1 authorization requirement, and the boundaries of what the API can verify (privacy questionnaire, pricing, agreements). This is unusually rich behavioral context.

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-loads the core action, then the check sequence, then the caveats and dry_run workflow. Each sentence carries actionable information, though the 'things the API can't check' list is dense enough to be slightly long.

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 mutating, no-output-schema tool, the description covers the mutation's effect, the returned plan artifact, the safety workflow, and auth prerequisites. Nothing essential for a correct invocation 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 the baseline is 3; the description nonetheless adds meaning by explaining the dry_run contract, the pre-flight check behavior that skip_checks bypasses, and the default 'editable' version semantics. It slightly enriches rather than merely restating the schema.

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 (submits) and resource (the version being prepared, to App Review), and scopes it to the editable version by default. It is clearly distinguishable from siblings like prepare_version (which readies a version) and cancel_review_submission (which reverses this).

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?

Explains the workflow context well: it runs pre-flight checks first and stops on missing items, and lays out the two-step dry_run confirmation. It does not explicitly name alternative tools, but the sequencing guidance is clear enough for an agent to know when to invoke it.

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

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

Adds value beyond annotations by disclosing the ASC_WRITE=1 permission requirement and explaining the safety model ('steps already done are skipped'), which substantiates the idempotentHint. The prerequisite that every question must be answered before any change is accepted is useful behavioral context.

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-loads purpose, then the input format, then the attribute taxonomy, then the completion constraint. It is dense and the long inline enumeration is hard to scan, but nearly every sentence carries necessary information an agent needs to construct valid input.

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 tool with no output schema and a nested free-form parameter, the description covers the operation, auth requirement, idempotency, and a prerequisite well. It is complete enough to call correctly, with only return-value behavior left implicit.

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?

The `answers` parameter is an undocumented free-form object in the schema, and the description compensates fully by enumerating Apple's attribute names and their value domains (the three-level content scale and the true/false yes-no set). This is exactly the compensation needed for a nested, enum-less object.

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: it answers/updates the age rating questionnaire for the app info being prepared. This is clearly distinguishable from siblings like update_listing or set_review_details, which handle different metadata.

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 clear operative context: it must be completed before Apple accepts any change, and instructs the agent to use fill_unanswered and confirm answers with the user. No sibling alternatives are named or excluded, but none are obviously needed for this tool.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), it discloses that only fields passed change and only if they differ, that results are shown as old → new, that localization is auto-created, that edits are gated on editable versions, and that re-runs are safe. This is rich context an agent needs before mutating metadata.

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?

Dense but front-loaded: mutation scope and diff behavior lead, followed by field grouping and constraints. Every sentence carries information, though the field-placement sentence is a little list-heavy.

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 19-param mutation tool with no output schema, it covers auth, idempotency, editability gating, and the old → new return shape. Remaining gaps (exact response structure, per-field format) are minor given the annotations and schema already present.

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?

With schema coverage at 47% across 19 params, the description compensates meaningfully by grouping fields by location (app info vs version) and explaining the version:"live" and default-locale semantics. It doesn't clarify the remaining undocumented params' formats, but most are self-evident fields.

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: 'Updates App Store metadata for one locale.' It scopes the operation (one locale) and effectively distinguishes itself from read-oriented siblings like get_listing and the narrower set_whats_new by covering the full metadata surface.

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 clear conditions for use: only versions being prepared can change, except promotional text on the live version via version:"live". It also notes the write requirement (ASC_WRITE=1). It stops short of naming explicit alternatives, so it falls just below the top tier.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds value beyond them: the ASC_WRITE=1 auth requirement and the concrete idempotency mechanism ('steps already done are skipped'). It also notes Apple processing typically takes 5-30 minutes and that the result explains how to resume, which the annotations do not convey.

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 with the core action and each sentence carries distinct information (method choice, build prerequisite, versioning rule, downstream step, auth/re-run note). It is dense and slightly long, but no sentence is filler, so it stays efficient rather than bloated.

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 tool with 8 params, no output schema and open-world behavior, the description covers prerequisites, auth, idempotency, the 5-30 minute processing wait, and the resume path. Nothing an agent needs to call it correctly 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 description coverage is high (88%), so the baseline is 3, but the description adds real meaning: it clarifies the method enum tradeoff, the .ipa/.pkg file expectation, and the critical constraint that build_number (CFBundleVersion) must be new and higher on every upload. That last point is not derivable from the schema alone.

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 ('Uploads an exported .ipa (or macOS .pkg) to App Store Connect') and distinguishes itself from the sibling distribute_build by naming it as the downstream step. An agent can identify exactly what this tool does and where it sits in the pipeline 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?

Explicitly explains when to use each method ('api' uses Apple's build upload API, no Xcode; 'altool' shells out to xcrun altool on a Mac) and gives prerequisites: build the .ipa first with xcodebuild archive/-exportArchive, and use a new higher build number. It also names the follow-up action (distribute_build), leaving no inference required.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, but the description adds real behavioral context beyond them: old images are deleted only after the new ones are processed (atomicity), MD5-based dedup makes re-runs safe (substantiates idempotency), and it requires ASC_WRITE=1. It also flags the destructive nature and the two-step dry_run confirmation pattern. No contradiction with 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?

Front-loaded with the core action, then behavior, then the safety workflow. Two tight paragraphs with little waste. Minor redundancy: dry_run's default and behavior are restated from the schema, and the destructive sentence partially overlaps the annotation.

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 mutation tool with no output schema, the description covers the essentials: what it does, ordering/atomicity, dedup, auth requirement, and the required dry_run confirmation loop. It leaves some parameters (display_type, wait_minutes, version/platform values) to the well-covered schema, which is acceptable given 90% coverage, but does not describe the plan object returned by dry_run.

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 90%, so the baseline is 3, but the description adds genuine meaning: it explains mode's replace-vs-append semantics (replace makes the set exactly these files in order; append adds at the end) and why re-running is safe (MD5 dedup on the files parameter). This meaningfully complements the enum without restating it.

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+resource+scope: "Uploads images to one screenshot set of the version being prepared." An agent can tell it operates on a whole set rather than a single slot, which helps versus replace_screenshot. However, it never names or contrasts with the closest siblings (replace_screenshot, reorder_screenshots, list_screenshots), so full sibling differentiation is left to inference.

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 concrete workflow guidance: dry_run defaults to true, show the plan to the user, then re-call with dry_run: false, and explains that re-running is safe. It also documents when to use replace vs append. It lacks an explicit "use this instead of replace_screenshot when..." routing, so it stays at clear-context rather than explicit-alternatives.

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