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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the description owes little on safety. It adds nothing: it doesn't say whether re-adding an already-assigned build fails or duplicates (relevant given idempotentHint=false), nor what eligibility checks the build must pass.

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 front-loaded sentence with no filler, well suited to a two-parameter tool. It is lean to the point of under-specification, 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 simple two-param mutation whose annotations cover safety, the description is minimally sufficient to select and call the tool. Missing are the non-idempotent re-assignment behavior and any preconditions, which matter given the diverse sibling set.

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 both parameters (betaGroupId, buildId) are documented in the schema. The description adds no format or sourcing hints beyond naming the resources, 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?

Names a specific verb and resource combination (assign a build to a TestFlight beta group), which an agent can distinguish from siblings like add_testers_to_beta_group and create_beta_group by the resource being attached. It is clear but doesn't explicitly contrast with those siblings.

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?

No guidance on when to use this versus add_testers_to_beta_group or other group tools, and no stated prerequisites (build must be processed/export-compliant, group must already exist). The agent must infer the whole usage 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?

The note that 'Adding may send invitations' adds genuine value beyond the annotations, explaining the open-world side effect consistent with openWorldHint=true and destructiveHint=true. However, it does not say how duplicates are handled (idempotentHint=false suggests repeat adds may fail or duplicate) or that removal requires a different tool.

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, front-loaded with the action and followed by the side-effect warning. 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 two-param mutation whose annotations already declare destructive and non-idempotent behavior, the description covers the essential side effect but leaves duplicate-handling and result expectations unexplained. Adequate, not 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?

Schema description coverage is 0% and neither betaGroupId nor betaTesterIds has any schema documentation. The description conveys only that the IDs refer to an existing group and existing testers; it gives no detail on batch limits, ID format, or what happens when a tester is already in the group.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Add existing TestFlight testers to a group'), and the word 'existing' plus 'testers' differentiates it from add_build_to_beta_group and create_beta_tester. It does not explicitly name those siblings, but the resource added is unambiguous.

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?

'Add existing TestFlight testers' implies testers must already exist (create_beta_tester) and that the group must exist first, but this is inference rather than stated guidance. No explicit when-to-use vs. add_build_to_beta_group or remove_testers_from_beta_group.

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 this as a non-idempotent, open-world, destructive write, so safety signaling is partly covered. The description adds the eligibility constraint for internal testers, which is useful, but it doesn't explain the destructiveHint (e.g., whether repeat calls create duplicate groups) or what enabling a public link entails.

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 core action, and every sentence adds a real constraint. 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?

With five parameters at 0% schema description coverage and no output schema, the definition is fairly thin. It covers the key internal/external distinction but leaves publicLinkLimit and the return value (e.g., the new group's ID) undescribed.

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 0%, so the description must compensate. It does explain the internal/external flag and that public links are optional, but publicLinkLimit is never explained and neither required parameter (name, appId) is elaborated beyond its obvious type.

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 gives a specific verb and resource ('Create an internal or external TestFlight group') and correctly frames the internal/external distinction. It doesn't explicitly contrast with update_beta_group or list_beta_groups, but the verb 'create' already separates it from those siblings.

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 adds a real prerequisite for internal groups ('Internal testers must already be eligible ASC team users') and notes that public links are optional. However, it never says when to choose this over update_beta_group, or what happens if a group with the same name already exists.

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 the mutation, destructive, non-idempotent and open-world profile, so the description's key contributions are the disclosed side effect ('May send invitation email') and the ASC team-access prerequisite, both of which go beyond the structured fields. It does not say what happens when the tester already exists, though the non-idempotent hint covers part of that.

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 compact sentences, front-loading the operation and following with the side effect and prerequisite. Every sentence earns its place, though phrasing could be tightened slightly.

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 and zero parameter documentation, the description covers the invitation side effect and permission prerequisite but omits what the optional name fields do and what happens on duplicate email, which an agent needs to call it safely.

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 0%, so the description must carry parameter meaning, but it only implicitly covers email and group assignment (betaGroupIds). The firstName and lastName parameters are never mentioned, nor is any format or constraint detail, leaving half the inputs undocumented.

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: create/invite a TestFlight tester by email and assign to groups. It partially distinguishes itself from the sibling add_testers_to_beta_group (which adds existing testers) without naming the alternative 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 internal-testing prerequisite ('user must already have the appropriate ASC team access') gives useful context, but there is no explicit when-to-use vs when-to-use-a-sibling guidance, and nothing tells the agent whether to use this instead of add_testers_to_beta_group or create_beta_group. Usage is only implied.

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, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds nothing beyond that — it does not explain what is created, what the destructive side effect is, whether duplicates are possible (non-idempotent), or any 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 is arguably under-specified rather than deliberately concise.

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 two-parameter create tool with full schema coverage and clear annotations, the essentials are present. However, with no output schema, the description says nothing about what is returned (e.g., the new page ID) or what happens on failure, leaving a gap for an agent that needs the created resource's identifier.

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?

Both parameters (appId, name) are fully documented in the schema at 100% coverage, so the schema carries parameter meaning. The description only echoes 'for an app' and adds no format or constraint detail beyond it — 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 (create) plus resource (custom product page) scoped to an app. The verb and the 'custom product page' resource distinguish it from siblings like update_custom_product_page and list_custom_product_pages without needing 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?

No guidance on when to use it versus alternatives (e.g., create_experiment or update_custom_product_page), no prerequisites, and no note on whether the app needs an existing version or locale setup. The agent must infer usage entirely from the 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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing about the consequences of a destructive, non-idempotent create (e.g. duplicate experiments on retry) or any permission/state requirements, leaving the mutation semantics opaque.

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 single sentence is front-loaded with the verb and resource and contains no filler. It is efficient, though the brevity comes at the cost of the behavioral and usage context noted elsewhere.

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, non-idempotent mutation with four required parameters and no output schema, the description never states what happens on success, whether a version must be in a particular state, or how the new experiment relates to start_experiment. The agent is left to discover key operational details on its own.

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 all four parameters including the 0-100 traffic range and platform enum. The description adds no additional meaning beyond the schema, which is the baseline for high coverage.

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 ('Create') and resource ('A/B test experiment for an app store version'), so the agent knows exactly what object is produced. It does not distinguish itself from siblings like start_experiment, stop_experiment, or get_experiment_results, leaving lifecycle placement implicit.

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 guidance on when to create versus start/stop/list an experiment, no prerequisites (e.g. the version must exist and be in an editable state), and no mention that creation is a separate step from starting traffic. The agent must infer the lifecycle from the verb alone.

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=false, and openWorldHint=true, so the safety profile is known. The description adds nothing beyond that: it doesn't mention that retries could duplicate IAPs (non-idempotent), that this modifies a live app's catalog, or what the resulting state is. With annotations present, the bar is lower, but zero added context still only merits a 2.

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 its brevity is partly a symptom of under-specification rather than deliberate concision.

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 four-required-parameter mutation tool with no output schema, the schema and annotations together carry most of the load. However, the description omits the natural follow-on steps (set_iap_price, submit_iap_for_review) and the fact that creation is irreversible/destructive, leaving the agent with only minimum viable context.

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%, with each of the four required parameters documented, including the inAppPurchaseType enum values. The description adds no parameter meaning (e.g. productId format conventions or immutability), so the baseline 3 is correct.

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 (create a new in-app purchase), which is unambiguous and clearly distinct from update_iap, delete_iap, and list_iaps by name. It stops short of differentiating at the behavioral level (e.g. what a new IAP is initialized with), so it earns a 4 rather than 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 guidance on when to use this versus siblings like create_subscription or create_custom_product_page, and no prerequisites (the parent app must exist, productId must be unique). The agent is left to infer usage entirely from the 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 destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the description should add what the annotations cannot: that this provisions a real product in App Store Connect, that it is non-idempotent (repeat calls create duplicates), and what state the new subscription starts in. It says none of this; 'create' is all the behavioral information provided.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single front-loaded sentence with zero waste, but the brevity here reads as under-specification rather than discipline — nothing is said that the name did not already imply.

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, open-world, non-idempotent creation tool with no output schema, the description omits what gets created, whether pricing/localization must follow, and how duplicates are handled. The rich parameter schema covers inputs, but the behavioral side is left entirely to annotations.

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 four parameters (name, groupId, productId, subscriptionPeriod with its enum) are already documented in the schema. The description adds no semantics beyond that, which is the expected baseline when the schema does the work.

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 ('Create a new auto-renewable subscription') and adds the qualifier 'auto-renewable', which mildly narrows scope beyond the tool name. However, it does nothing to separate this from close siblings such as create_iap, create_subscription_group, or create_subscription_offer, so an agent still has to infer the boundary itself.

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 guidance on when to use this versus create_iap, create_subscription_group, or create_subscription_offer, and no stated prerequisites even though a required groupId implies an existing subscription group. The agent gets a verb but no decision 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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is known structurally. The description adds nothing beyond that: it does not mention what side effects occur, whether the new group is immediately mutable/subscribable, or how failure modes (duplicate referenceName) behave.

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 or redundancy. It is efficient, though its brevity borders on under-specification rather than tightness.

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 two-parameter mutation whose annotations carry the destructive/non-idempotent warnings and whose schema fully documents inputs, the description is minimally sufficient. It leaves gaps on what the created group looks like and how it relates to subscriptions created later.

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% — both appId and referenceName are documented in the schema. The description's mention of 'for an app' loosely maps to appId but adds no constraints, format hints, or uniqueness rules for referenceName. Baseline 3 applies since the schema does the work.

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 ('Create a new subscription group') plus scope ('for an app'), so the agent knows exactly what is produced. It does not distinguish itself from sibling creation tools like create_subscription, create_iap, or create_beta_group, which is the only thing separating a 4 from 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 guidance on when to use this versus create_subscription or list_subscription_groups, no stated prerequisites, and no exclusions. The agent must infer usage entirely from the 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 flag destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is known. The description adds nothing beyond that: it does not say whether an offer can be revoked, whether re-creating with the same offerCode fails, or what side effects occur on the subscription. For a destructive, non-idempotent mutation, the near-zero added context is a clear 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?

A single front-loaded sentence with no filler, but the economy comes at the cost of substance — there is no second sentence carrying the behavior or constraints an agent needs. Efficient but under-specified rather than well-structured.

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?

This is a destructive, non-idempotent creation tool with six required parameters, no output schema, and rich sibling tools for subscriptions and offers. The description omits required preconditions, the meaning of offerCode uniqueness, how duration/mode interact, and what the agent gets back. Given the tool's complexity and risk, it is materially incomplete.

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 six parameters and both enums (duration, offerMode) are documented in the schema. Baseline 3 applies; the description contributes no additional meaning (e.g. valid numberOfPeriods combinations or duration constraints) beyond what the schema already provides.

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: 'Create a promotional offer for a subscription.' An agent can tell it creates rather than lists or updates offers. However, it does no sibling differentiation — it never distinguishes itself from create_subscription, list_subscription_offers, or create_iap, and 'promotional offer' is left undefined relative to offerCode/offerMode concepts in the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description contains no when-to-use guidance, no prerequisites (e.g. must the subscription already exist / be in a particular state?), and no mention of alternatives such as list_subscription_offers for inspection. The agent must infer everything from the tool name and schema.

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, non-idempotent, and open-world, so safety is covered structurally. The description adds meaningful behavioral context beyond that: the operation fails on submitted IAPs, which is not derivable from the schema or annotations. It omits whether deletion is permanent or what the response looks like, keeping it below 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?

One sentence, front-loaded with the action and immediately qualified by the precondition. 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?

A destructive single-param tool with no output schema; annotations cover the safety profile and the description covers the eligibility constraint. What remains unstated (irreversibility, error behavior on ineligible IAPs) is minor enough not to undercut 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?

There is a single parameter (iapId) with 100% schema description coverage, so the schema fully documents it. The description adds no format or sourcing detail for the ID, which is acceptable at the baseline for a one-parameter tool.

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 (delete an in-app purchase) and narrows scope to draft IAPs, which cleanly separates it from siblings like update_iap, submit_iap_for_review, and get_iap.

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 parenthetical gives an explicit when-not condition (only works if not yet submitted for review), which is the key gating rule for deletion. It does not name an alternative for already-submitted IAPs, 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 readOnly, idempotent, non-destructive, and open-world hints. The description adds useful behavioral context by saying there is 'No network request' and by noting that referenced definitions are included in the returned schema.

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 front-loaded sentences with no wasted words. The core purpose and the no-network behavioral note are both stated efficiently.

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 one-parameter read-only lookup with no output schema, the description adequately explains what is returned (parameters and request schemas including referenced definitions) and that no network request occurs. The main remaining gap is how operationId should be obtained or formatted.

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 0%, so the description must compensate for the undocumented operationId parameter. It only implies that operationId refers to an Apple operation, without explaining format, source, or how to discover valid values via search_api_operations.

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 ('Get') and resource ('exact parameters and request schemas ... for an Apple operation'), and adds the timing context 'before executing it.' It does not explicitly name sibling tools like search_api_operations or read_api, but the pre-execution schema-lookup purpose is clear.

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 'before executing it' gives clear usage context and implicitly positions this tool as a prerequisite to execution. It does not state exclusions or name alternatives such as search_api_operations for discovering operation IDs.

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 and destructiveHint=false, so the safety and repeatability profile is fully covered without prose. The description adds only that the key is an App Store Connect ID; it says nothing about what "details" comprises, error behavior on an invalid ID, 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?

A single front-loaded sentence with zero filler, appropriately sized for a one-parameter getter. It is efficient but so terse that it leaves no room for the differentiating or behavioral context the other dimensions lack.

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?

The tool is genuinely simple (1 required param, rich annotations), so little prose is required. However, with no output schema the word "details" leaves the return payload entirely unspecified, so an agent cannot anticipate whether it gets attributes, relationship links, or locale data.

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 100% schema description coverage the single appId parameter is already documented, and the description adds no format, example, or source-of-ID guidance beyond restating "App Store Connect app ID". Baseline 3 applies when the schema carries the semantics.

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 ("Get details for a specific app") plus the lookup key (App Store Connect ID), which cleanly separates it from list-oriented siblings such as list_apps. It stops short of explicitly naming the alternative, but the singular-resource framing is unambiguous.

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 only implied: an agent can infer this is the tool for fetching one known app rather than enumerating apps, but the description never says when to use it versus list_apps or what to do if the ID is unknown. No prerequisites or failure conditions are given.

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 the safety profile is fully covered externally. The description adds nothing beyond that — no auth requirements, no rate-limit notes, no indication of what the returned review state looks like or what it can be.

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 front-loaded sentence with no filler. The resource and scope appear before anything else and nothing is repeated from the title or 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?

A simple read-only getter with full annotations, so the bar is modest, but with no output schema the description should say what 'review state' means (e.g., the set of possible states) and where the buildId comes from. As written, an agent knows what to call but not what it will get back.

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 0% for the single required buildId, so the description must carry the load. 'for a build' does confirm that buildId identifies the build whose review state is read, which is more than the bare schema offers, but it gives no format, source, or example.

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 (Read) and a precisely-scoped resource (TestFlight Beta App Review state) qualified by 'for a build'. The 'Beta' qualifier implicitly separates it from the sibling get_review_status, but the description never names that sibling or make the distinction explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use statement, no prerequisites, and no alternatives named. An agent facing both get_beta_review_status and get_review_status (or get_review_submission) gets no help deciding which one to call.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral details beyond the basic purpose, such as what 'details' includes, error behavior, or any 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?

The description is a single, front-loaded sentence with no wasted wording. It is appropriately sized for a simple getter, even if it is sparse.

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 tool with one required parameter and rich annotations, the description is minimally adequate. However, with no output schema, it does not explain what 'details' are returned, and it provides no error or usage context.

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 single buildId parameter is already documented as 'The build ID'. The description does not mention the parameter or add format/semantic detail beyond the schema, which is acceptable for a simple required ID.

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: 'Get details' for 'a specific build'. It is clear enough to distinguish from list_builds by the 'specific build' wording, but it does not explicitly name or differentiate siblings.

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 guidance on when to use this tool versus list_builds or other build-related tools. The phrase 'specific build' implies usage when a build ID is known, but no alternatives, prerequisites, or exclusions are 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, destructiveHint=false and openWorldHint, so the safety profile is fully covered elsewhere. The description adds nothing beyond that — no note on what 'details' comprises, whether the page must exist, or what happens on an unknown pageId.

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 short sentence, front-loaded with the verb, with zero filler. It is efficient but so terse that the brevity edges into under-specification rather than clean conciseness.

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?

A simple read tool with one documented parameter and a full annotation safety profile, so the bar is low. However, with no output schema, the description could have stated what 'details' are returned; that omission leaves a real gap an agent would want answered.

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?

Single parameter pageId with 100% schema description coverage, so the schema already explains it. The description adds no format hints, ID syntax, or source for obtaining the pageId, so it lands at the baseline for full-coverage schemas.

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 (Get) and resource (custom product page), with 'specific' signalling single-item retrieval by identifier, which distinguishes it from list_custom_product_pages and create/update_custom_product_page siblings. It never names those siblings, but the verb/resource pairing is unambiguous.

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?

No when-to-use guidance, no prerequisites, no mention of the obvious alternative (list_custom_product_pages) for browsing. The agent must infer from the name that this is the single-record fetch versus the list variant.

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 and destructiveHint=false, so the safety profile is covered without the text. The description adds nothing beyond the name: no statement about behavior when the ID is unknown, no auth/scope prerequisites, no data-freshness or rate-limit context for an openWorldHint tool.

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 short sentence with no filler, and the resource being fetched is front-loaded immediately after the verb. Nothing is padded or repeated.

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 ID lookup with full schema coverage and read-only annotations, the essentials are present. But with no output schema, the description never says what 'details' comprises, nor how it differs from the related list_experiments and get_experiment_results tools an agent will be choosing between.

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 parameter at 100% schema description coverage, the schema already documents experimentId and marks it required. The description only implies that the ID selects one specific experiment, adding no format, source, or validity information 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 ('Get details for') and resource ('a specific A/B test experiment'), and the phrase 'A/B test' disambiguates the kind of experiment. It is distinguishable from siblings like list_experiments (enumeration) and get_experiment_results (metrics), though it does not name those siblings 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 word 'specific' implies you already have an identifier, so the reader can infer it is a by-ID lookup rather than a search. However, there is no explicit when-to-use guidance and no pointer to list_experiments for discovering an ID or get_experiment_results for outcome data.

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, and destructiveHint=false, so the safety profile is covered. The description adds useful context that results include conversion rates per treatment, but it does not describe freshness, finality, or access requirements for the results.

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 focused sentence with the core action and returned information front-loaded. There is no redundant or wasted language.

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 tool with one fully documented parameter and annotations covering safety behavior, the description is largely complete. It could further clarify result freshness or whether only completed experiments return data, but no output schema exists to require return-value explanation.

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 schema has 100% description coverage for the single experimentId parameter, so the baseline is 3. The description does not add meaning beyond the schema, such as the expected ID format or whether experiments must be in a particular state.

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: getting results for an A/B test experiment. It also clarifies the returned content as conversion rates per treatment. It does not explicitly distinguish itself from sibling tools like get_experiment or list_experiments, 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?

The description implies that this tool is used when experiment results are needed, but it gives no explicit guidance on when to use it instead of get_experiment, list_experiments, or other experiment-related tools. No exclusions or alternatives are named.

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, covering the full safety profile. The description adds no behavioral context beyond that – no note on what 'details' includes, error behavior for missing IDs, or auth needs.

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 wasted words, appropriate for a simple getter. Nothing extraneous, though it is close to the minimum for conveying purpose alone.

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 one-parameter read tool with full annotation coverage and no output schema, the description plus structured fields give an agent enough to invoke it correctly. Only marginal return-shape detail is missing, and no output schema exists to demand it.

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% and iapId is fully documented in the schema, so the schema carries the parameter explanation. The description adds no syntax, format, or ID-source guidance 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 (get) and resource (in-app purchase) scoped to a single record, which distinguishes it in spirit from list_iaps. It does not explicitly name that sibling, 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?

The word 'specific' hints at fetching one record versus listing, but there is no explicit when-to-use guidance or named alternative (e.g., use list_iaps to enumerate). The agent must infer the selection criteria.

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 nothing beyond that — no indication of what statuses may be returned, whether the value is cached, or whether a submission must exist first. 'Current' is the only hint at behavior, and it is too thin.

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 short, front-loaded sentence with no filler. It is efficient, though its brevity is partly the source of the missing guidance rather than a virtue of precise wording.

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 one-parameter read-only getter with full schema coverage and rich annotations, most of what an agent needs is in structured fields. However, there is no output schema, so the description should ideally say what the review status looks like or reference the review submission sibling, which it does not.

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 parameter with 100% schema description coverage ('The app store version ID'), so the schema fully documents it. The description adds no further meaning such as where to obtain the versionId or whether it accepts the internal or external ID; 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 (get) and specific resource (review status for an app store version), which is more precise than a generic 'get status'. It implicitly separates itself from get_beta_review_status and get_review_submission by scoping to an app store version, but it never names those siblings to confirm the distinction.

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?

No guidance on when to call this versus get_review_submission or get_beta_review_status, and no prerequisites or polling guidance despite being a status check. The agent must infer the usage from the name alone.

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, covering the safety profile. The description adds that it returns the 'latest' submission and may include rejection reasons, which is useful but modest. It doesn't disclose behavior when no submission exists or whether the response is paginated or empty.

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 zero waste. The core action and return content are stated immediately.

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?

Given the tool's low complexity, 100% schema coverage, and rich annotations, the description is nearly complete for calling it correctly. It states what is returned (latest submission and possible rejection reasons) but omits edge-case behavior when no submission exists and does not distinguish it from get_review_status.

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%, with appId and platform already documented, so the schema carries the parameter burden. The description adds no parameter-specific meaning beyond what the schema provides; 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 and resource: 'Get the latest review submission for an app.' It also names what the response includes ('rejection reasons if any'). However, it does not differentiate from the sibling tool get_review_status, leaving ambiguity about which tool to pick.

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 guidance on when to use this tool versus alternatives like get_review_status. The phrase 'including rejection reasons' implies a use case (checking rejections), but no conditions, exclusions, or alternatives are 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=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered externally. The description adds nothing beyond the annotations—no mention of pagination, result volume, or whether all apps are returned in one call—so it neither enhances nor contradicts them.

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. Every word carries information about the verb, the resource, and the account scope.

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 parameterless list tool with full annotation coverage and no output schema, the description is minimally adequate. It omits any statement about result size, pagination, or how it relates to get_app, which an agent would need when choosing between the two.

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 tool takes zero parameters, so there is no parameter semantics for the description to explain; the baseline for a parameterless tool applies. Nothing in the description misrepresents the signature.

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 gives a specific verb (List) and resource (apps) scoped to the App Store Connect account, which is unambiguous on its own. It does not, however, differentiate against the sibling get_app, leaving the agent to infer that this returns the collection rather than a single app.

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 and no mention of alternatives such as get_app or list_app_versions, despite both being plausible paths for app-related discovery. Usage is only implied by the verb 'List'.

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 and destructiveHint=false, so the safety profile is covered by structured data. The description adds useful context that the result contains descriptions, what's-new text and keywords per locale — effectively a partial return-shape hint in the absence of an output schema — but says nothing about pagination, ordering, or empty-locale behavior.

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 field enumeration packed into a parenthetical. 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?

For a simple one-parameter read tool with full schema coverage and complete annotations, the description covers purpose and roughly what comes back. The only shortfall is the lack of guidance on how to obtain a versionId and what to do with results (feed them to update_app_description etc.).

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 versionId parameter is documented as 'The app store version ID'; the description adds no format, source, or validation detail beyond that. With one fully-documented parameter, 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 (List) and a precise resource (localizations for an app store version), and the parenthetical enumerates the field types returned. This lets an agent distinguish it from the sibling updaters (update_app_description, update_whats_new, update_keywords) and from list_iap_localizations/list_subscription_localizations, though it never names those alternatives 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 or when-not-to-use guidance, no mention of prerequisites (e.g., that a versionId must come from list_app_versions), and no routing to the update_* tools that modify the very fields this tool lists. The use case is only implied by the resource 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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds only the scoping detail that results are for a single app; it does not mention pagination, ordering, or what 'all versions' includes. With annotations doing the heavy lifting, this is adequate but thin.

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 with no wasted words. It is appropriately sized for a simple list 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 simple list tool with full schema coverage and rich annotations, the description is minimally sufficient to support correct invocation. However, with no output schema, it leaves the return shape and ordering unexplained, which is a noticeable gap for an agent trying to understand what 'versions' will contain.

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 both parameters are clearly documented there, including the platform enum. The description does not add meaning 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?

The description states a specific verb and resource: 'List all App Store versions for an app.' It is clear what the tool retrieves and that it is scoped to an app. It does not explicitly distinguish itself from nearby list tools such as list_app_store_version_localizations, 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?

There is no explicit guidance on when to use this tool versus alternatives like get_app, list_builds, or list_app_store_version_localizations. Usage is only implied by the phrase 'for an app,' leaving the agent to infer the correct 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds only the app-scoping context; it says nothing about pagination, result ordering, or empty-state behavior for an open-world list call.

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 short sentence with the resource and scope front-loaded; nothing is wasted. It is minimal to the point of being terse, but structure is sound.

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 a trivial single-parameter input, the description covers the essentials of what is returned (beta groups) but omits pagination and whether inactive/expired groups are included — meaningful gaps for a 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?

Only one parameter, and the schema documents it at 100% coverage ('The App Store Connect app ID'). The description adds no format or sourcing detail beyond the schema, 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?

Specific verb ('List') plus resource ('TestFlight beta groups') and scope ('for an app'). It is distinguishable from siblings like create_beta_group, update_beta_group, and list_beta_testers, though it does not explicitly name them.

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?

No statement of when to use this versus alternatives such as list_apps or list_beta_testers, and no prerequisites (e.g., whether the app must have TestFlight enabled). The read-only listing intent is only implied by the verb.

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, and destructiveHint=false, so the safety profile is fully structured. The description adds the optional-filter context but says nothing about pagination, result volume, or return shape; with annotations covering behavior, 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?

One short sentence with zero waste, and the optional filter constraint is stated up front so an agent can decide immediately whether the parameter is needed.

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 zero-required-parameter read-only list tool whose annotations and schema are complete, the description covers purpose and filtering adequately. The absence of any note on result format or pagination is a minor gap given there is no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single betaGroupId parameter is documented in the schema. The description merely restates the filter, adding no format or sourcing detail beyond the schema, 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 and resource ('List TestFlight beta testers') with the optional filter scope. It is distinguishable from create_beta_tester and list_beta_groups, though it doesn't explicitly name how it relates to those siblings.

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 'optionally filtered by beta group' implies when the filter applies, but there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives like list_beta_groups or add_testers_to_beta_group.

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 the safety profile is fully covered without the description. The description adds no behavioral context beyond the schema — no mention of pagination, default page size, sort order, or how many builds are returned, which are the traits an agent still needs for a list endpoint.

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 zero filler; the resource and both optional filters land in the first read. Nothing redundant and nothing padded.

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 agent has no view of the return shape — whether builds come back as a bare array, a paginated envelope, or with cursor links — and the description does not fill that gap. For a simple three-parameter read tool the omission is survivable but leaves a real hole.

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%, including an enum for processingState, so the schema does all the parameter work. The description only restates that version and processingState act as filters; it adds no format hints (e.g. version string shape) beyond what the schema already provides.

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 ('List builds for an app') plus the two optional narrowing dimensions, so the agent knows exactly what is returned. It does not explicitly name the sibling get_build as the single-build alternative, but 'list' versus 'get' makes the split reasonably clear.

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?

'Optionally filtered by version or processing state' implies the filtering use case, but there is no explicit guidance on when to reach for this versus get_build, nor any stated prerequisite such as needing an appId from list_apps. Usage is inferable rather than taught.

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 the safety profile is covered. The description adds the 'all' scope, but does not mention pagination, permissions, or return behavior, leaving a moderate gap for a list operation.

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 efficient sentence with no wasted words, and the resource and scope are front-loaded.

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 one-parameter list tool with rich annotations and full schema coverage, the description is mostly complete. The main remaining gap is that 'List all' does not clarify whether results are paginated or complete, which could matter for an open-world App Store Connect list endpoint.

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 appId parameter is fully documented in the schema. The description's 'for an app' reinforces its purpose but does not add syntax or format details 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?

The description states a clear verb-resource pair: 'List all custom product pages' and scopes it to 'for an app'. This naturally distinguishes it from create/get/update custom product page siblings, though it does not explicitly name an alternative.

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 'List all' phrasing and the app scoping, but there is no explicit when-to-use guidance, no exclusions, and no mention of when a sibling like get_custom_product_page would be more appropriate.

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, and destructiveHint=false, so the description adds almost nothing on the behavioral side — no mention of pagination, result ordering, or what happens with an invalid versionId. The only extra information is the version scoping, which is essentially implied by the parameter.

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 sentence with no filler and the resource front-loaded. It is appropriately sized for a trivial one-parameter list tool, though it is so terse that it leaves obvious questions unaddressed rather than having its sentences earn extra value.

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 annotations cover the safety profile, so the definition is complete enough to safely invoke. It stops short of saying whether results are paginated or what fields each experiment carries, which an agent may want to know before chaining into get_experiment or get_experiment_results.

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 versionId is fully documented in the schema and the description needs to do little. It reinforces the parameter's meaning ('for an app store version') but adds no format or sourcing detail beyond what the schema says; 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 ('List') and resource ('A/B test experiments') scoped to an app store version, which separates it plainly from get_experiment, create_experiment, and start/stop_experiment. It does not explicitly name those siblings, but the scope is unambiguous.

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 'for an app store version' scope implies when to use it (you have a versionId and want the experiments attached to it), but there is no explicit guidance on when to prefer get_experiment for a single experiment or what to do if no experiments exist. 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that the returned localizations include display names and descriptions, which is useful, but it does not add further behavioral context such as locale coverage or pagination.

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 with no wasted words. It states the action, the resource, the scope, and the returned fields efficiently.

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?

This is a low-complexity read-only list tool with one fully documented parameter and rich annotations. The description identifies the returned fields, which is useful absent an output schema, though it could say more about locale coverage or result shape.

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 one required parameter, iapId, and schema description coverage is 100%, so the schema already documents it fully. The description implies that the call is scoped to an in-app purchase but does not add syntax or format details 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?

The description gives a specific verb and resource: list localizations for an in-app purchase. It also names the returned content (display names, descriptions), and the in-app purchase scope distinguishes it from list_subscription_localizations.

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 purpose: use this to list localizations for a given IAP. However, it does not explicitly say when to use this versus set_iap_localization or list_subscription_localizations, nor does it state exclusions or prerequisites.

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 the safety profile is fully covered. The description adds only the app-scoping constraint; it says nothing about pagination, result ordering, or what fields are returned for a list tool.

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, which is appropriate for a simple one-parameter list tool. It is efficient though nearly bare, leaving little beyond the minimum.

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 with one documented parameter, full annotation coverage, and no output schema to explain, the description supplies enough to call it correctly. Missing pagination and return-shape notes are minor given the tool's simplicity.

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 required parameter at 100% schema description coverage, the schema already documents appId as the App Store Connect app ID. The description adds no format, source, or validation detail beyond that, 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 (List) and resource (in-app purchases) scoped to an app, so an agent can distinguish it from get_iap, create_iap, list_iap_localizations, and list_subscriptions. It stops short of naming how it differs from those siblings, but the resource noun is unambiguous.

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 only implied by the name and the 'for an app' scope; there is no explicit statement of when to use this versus get_iap for a single IAP or the localization/subscription listing tools. An agent can infer the intent but must reason about the alternatives itself.

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 the safety profile is fully covered elsewhere. The description adds no behavioral context of its own — nothing about pagination, result ordering, or whether groups are returned with nested subscriptions, which matters given openWorldHint implies a live remote call.

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 short sentence with the scope qualifier front and center; nothing is wasted. It is arguably over-compressed rather than verbose, leaving the reader with no routing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter read tool with rich annotations, the description is technically sufficient to invoke correctly. With no output schema present, though, some indication of what is returned (group identifiers, names, nesting) would have closed the remaining gap.

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 single appId parameter is fully documented in the schema (100% coverage), so the schema carries the burden. The phrase "for an app" implicitly ties the call to appId but contributes no extra semantics such as format or validity of the ID.

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 ("List subscription groups") plus a scope qualifier ("for an app"), so the operation is unambiguous. It does not, however, distinguish itself from nearby siblings such as list_subscriptions or list_subscription_offers, which an agent could reasonably confuse with it.

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 gives no when-to-use guidance, no exclusions, and no pointer to alternatives such as list_subscriptions for individual subscriptions versus groups. Usage is only implied by the phrase "for an app".

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 the safety profile is fully covered. The description adds the nature of the returned fields but says nothing about ordering, pagination, or what happens when no localizations exist beyond the annotations' guarantees.

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; the resource and return content are stated immediately.

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 one-parameter read tool with full annotation coverage and no output schema, the definition covers purpose and return content adequately. Only the absence of pagination/ordering notes keeps it from being 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?

Schema coverage is 100% for the single required subscriptionId parameter, so the schema already documents it fully. The description adds no extra meaning about the identifier format or scope, so the 3 baseline 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 uses a specific verb+resource ("List localizations") scoped to subscriptions, which distinguishes it by name from list_iap_localizations and list_app_store_version_localizations. It also clarifies what a localization contains (display names, descriptions), but it never explicitly names the sibling tools it is not.

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 statement of when to use this versus set_subscription_localization or list_iap_localizations, nor any preconditions such as needing an existing subscription. Usage is only implied by the verb 'List'.

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 fully covered elsewhere. The description adds nothing beyond them — no note on pagination, whether inactive/expired offers are included, or remote-API latency implied by openWorldHint.

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 short sentence with the resource and scope front-loaded and zero filler. Nothing is wasted or buried.

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 one-param read tool with full annotations and no output schema, this is minimally sufficient to call correctly. It still leaves open whether results are paginated or filtered, which matters for an open-world API-backed list operation.

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% and the single parameter is self-describing, so the schema does the work. The description adds no meaning such as whether the ID must be a subscription in the same app or what format it takes, but baseline 3 applies when coverage is complete.

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: list promotional offers scoped to a subscription. It is distinguishable from create_subscription_offer by name, though the description itself never mentions that sibling.

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 guidance on when to use this versus create_subscription_offer, list_subscription_price_points, or list_subscriptions. The only hint is the required subscriptionId, which the schema already conveys.

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 the safety and idempotency profile is covered. The description adds no behavioral detail beyond the listing scope, which is acceptable given the annotation coverage but not value-adding.

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 communicates scope and the optional filter efficiently.

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 with full schema coverage and annotations carrying the safety profile, the definition is essentially complete. No output schema exists, but the description needn't explain return values for such a straightforward listing operation.

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% and both parameters carry descriptions in the schema, so the schema does the heavy lifting. The description reinforces that territory filtering is optional, adding marginal value over the schema but nothing new.

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 uses a specific verb ('List') and resource ('price points for a subscription'), with the optional territory filter noted. It's clear what the tool does, though it doesn't explicitly distinguish itself from nearby siblings like set_subscription_price or list_subscription_offers.

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 'optionally filtered by territory' implies the common usage pattern, but there's no explicit when-to-use guidance or named alternatives for retrieving price data versus setting them.

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 the agent knows this is a safe, repeatable read. The description adds only the grouping scope; it says nothing about whether results are paginated, how large a response can be, or what fields are returned on a subscription, which is the remaining behavioral value it could have provided.

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 short sentence, front-loaded with the action and resource, with no filler. It is efficient, though its brevity leaves the behavioral gaps noted above rather than trading length for completeness.

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 single-parameter read tool with full annotation and schema coverage, the description is adequate to invoke correctly. It stops short of covering the things an agent would still want for a list endpoint: result size, pagination, and how subscriptions relate to groupId when the group is empty or unknown.

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% and the single groupId parameter is documented as 'The subscription group ID'. The description's phrase 'within a subscription group' merely restates that scope without adding format, ID source, or example values, 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 and resource ('List subscriptions') plus a scoping constraint ('within a subscription group'). This clearly separates it from the sibling list_subscription_groups, which lists groups rather than the subscriptions inside one, though the description does not name that sibling 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?

Usage is only implied: the required groupId makes it evident you must know which group to enumerate. There is no explicit when-to-use/when-not guidance, no mention of list_subscription_groups vs this tool, and no note about pagination or limits on results.

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, openWorld, and non-destructive behavior. The description adds useful return semantics: one unflattened JSON:API page with relationships, included resources, pagination links, and base64 binary reports. It still omits auth, rate-limit, and error behavior, so 4 rather than 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?

Four short sentences, front-loaded with the action, then return shape, pagination, and binary handling. Every sentence adds information with no redundant restatement.

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?

Covers return shape and pagination for a read tool with no output schema, while annotations cover the safety profile. It still lacks discovery-flow and error/auth context, but the schema covers most parameter details, making this nearly 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?

Schema coverage is 75%, and the schema already documents operationId, path, and body. The description adds pagination cursor guidance from links.next but does not explain operationId sourcing or path/body semantics. 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 verb and resource: execute an official Apple GET operation. It also specifies the return shape and pagination behavior. It implicitly separates reads from write_api via GET but does not name sibling tools, so it is clear but not fully differentiated.

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?

Says to execute after schema validation and explains how to page using links.next. However, it gives no explicit when-not-use guidance or alternatives such as search_api_operations, get_api_operation, or write_api. Usage is only implied by the GET framing.

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=false and openWorldHint=true, so the safety profile is covered. The description adds nothing about what removal does (irreversibility, effect on installed builds, per-tester failure handling) and instead contributes an irrelevant statement about adding sending invitations.

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 first sentence is tight and front-loaded, but the second sentence about adding invitations does not earn its place in a removal tool and adds ambiguity.

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 0% parameter documentation, the description should explain the effect of the destructive removal and the parameters. Instead it leaves both undocumented and includes a mismatched sentence, so it is not complete enough for a destructive batch operation.

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 0%, so the description must carry the parameter meaning, yet it explains neither betaGroupId nor betaTesterIds (an array of at least one tester ID). The agent gets no added semantics beyond the property names.

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 first sentence names a specific verb and resource ('Remove existing TestFlight testers from a group'), which clearly separates it from the sibling add_testers_to_beta_group. There is no explicit sibling callout, but the add/remove contrast is implied.

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 statement of when to use this versus add_testers_to_beta_group or other tester tools, and no prerequisites such as needing an existing beta group. The only contextual sentence discusses 'adding', which gives no guidance on removal usage.

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 and destructiveHint=false, so the safety profile is covered structurally. The description's contribution is "No network request", which usefully signals a local/offline lookup rather than a live API call, but it says nothing about result ordering, truncation, or what happens with an empty query. There is a mild tension with openWorldHint=true, though the open-ended catalog domain arguably explains that flag.

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?

Short and front-loaded: the core action leads, with the coverage list and the no-network note following. The trailing "and more" is filler and the subject-area list is long relative to the payload, but it does double duty as query vocabulary hints.

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 no parameter documentation, the description should say at least what a hit looks like (operation ID, path, method, summary) and how limit/offset page through results. Annotations cover the safety profile, so the gap is moderate rather than severe, but an agent still cannot predict the response shape or how to consume it.

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 0% across all four parameters, so the description must compensate and does not: query, limit, offset and method are never mentioned or explained. Only the enum on method is self-documenting; the matching semantics of query (substring? keywords? operation ID?) and the paging behavior of limit/offset are left entirely to guesswork, and the domain list only loosely hints at query vocabulary.

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: searching the official App Store Connect OpenAPI catalog, with an enumeration of covered domains (provisioning, TestFlight, pricing, Xcode Cloud). This clearly separates it from the CRUD-style siblings like update_app_description. It does not, however, distinguish itself from the closely related get_api_operation/read_api/write_api siblings, which is the differentiation an agent most needs here.

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?

"No network request" plus the subject-area list implies this is the discovery step before calling read_api/get_api_operation, but the description never states that workflow explicitly. There is no when-not guidance and no mention of the alternative tools for retrieving a known operation.

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 this as a destructive, non-idempotent, open-world mutation, so the safety profile is covered by structured fields. The description adds some context by explaining that the tool creates or updates localized beta test text, but it does not explain overwrite behavior, permissions, or side effects beyond what annotations imply.

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, front-loaded with the core action and followed by the key update-mode condition. No wasted text.

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 low-complexity mutation with rich annotations and no output schema, the description is adequate but leaves notable gaps: parameter formats, what happens to existing localization text, and domain-specific constraints are not described.

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 0%, so the description must carry parameter meaning. It only explains localizationId's role and loosely maps whatsNew to 'What to Test text'; buildId, locale, and validation/format expectations remain undocumented.

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 pair (Create or update) and resource (localized What to Test text for a TestFlight build), which is clear and differentiated from generic App Store whats-new tools. It does not explicitly name a sibling alternative, but the TestFlight-build scope makes the purpose distinguishable.

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 sentence 'Supply localizationId to update an existing locale' gives clear create-vs-update guidance and tells the agent how to select update mode. It lacks broader when-to-use guidance versus sibling tools, but the core usage condition is explicit.

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 disclose destructive=true, idempotent=false, readOnly=false and openWorld=true, so the safety profile is covered. The description adds no behavioral context beyond the mutation verb—it does not say whether the declaration can be changed later, whether it overwrites earlier values, or what the consequence of a wrong declaration is. The one extra sentence is advice, not 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?

Two short sentences with the operation front-loaded and no filler. It is efficiently sized, though the second sentence is a usage caveat rather than a necessary structural element.

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 and zero schema description coverage, two sentences are thin. Missing are prerequisites (build must exist), timing relative to review/submission, and any explanation of how buildId is sourced.

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 0%, so the description must carry parameter meaning. It clarifies that the boolean corresponds to 'non-exempt encryption,' which is useful, but says nothing about how buildId is obtained or formatted, leaving half the parameters undocumented in both schema and prose.

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 ('Declare') and resource ('whether a build uses non-exempt encryption') that clearly maps to a build export-compliance setting. No sibling tool performs the same function, so the operation is distinguishable, though the description never explicitly names it as the export-compliance tool for a given buildId.

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 sentence 'Use the app's actual export-compliance determination' gives a correctness instruction but does not say when this must be called (e.g., before beta review or submission) or what alternative exists if the determination is unknown. Usage is implied rather than explicitly scoped.

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=false and openWorldHint=true, so the description should add what those mean here (does an update overwrite existing name/description? is a missing locale created silently?). It adds nothing beyond the bare 'create or update' framing, which is restated by the schema's localizationId parameter description.

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; the purpose is stated before anything else and nothing redundant is included.

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, non-idempotent mutation with five parameters the description gives no behavior on overwrite semantics, locale conflicts, or required scopes, and there is no output schema to fill the gap. Only the annotations keep this from being unusable.

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%, including the key detail that localizationId switches update-vs-create, so the schema carries the semantic load. The description adds no parameter meaning beyond that 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?

Clear verb+resource: "Create or update a localization for an in-app purchase" tells an agent exactly what the tool mutates. It does not differentiate itself from near-identical siblings such as set_subscription_localization or set_beta_build_localization, so the agent must infer the target object from the name alone.

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?

No guidance on when to call this versus create_iap/update_iap or set_subscription_localization, and no statement of prerequisites (e.g. IAP must already exist). The create-vs-update decision is left entirely implicit.

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=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that — it does not say whether the new price takes effect immediately, whether existing purchasers are grandfathered, or whether the previous price is replaced or retained.

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 tightly worded sentence with the resource front-loaded and no filler. It is appropriately sized, though its brevity is partly the reason other dimensions are thin.

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 2-parameter mutation with a rich schema and no output schema, the description covers the minimum: what it changes and by what key. It omits the operational consequences of a destructive price change and any mention of what comes back, leaving a gap larger than necessary for a money-affecting write.

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%, with both parameters documented inline, so the schema carries the load. The description only restates that a price point ID is required, adding no format, sourcing, or validation detail beyond the schema's own 'get available price points via the API' note.

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 (set/update), resource (in-app purchase price) and mechanism (price point ID), so an agent can distinguish it from set_subscription_price and the other IAP tools. It stops short of an explicit contrast with those siblings, so it is clear but not maximally differentiated.

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 resource name: use this when changing an IAP's price. There is no explicit when-to-use/when-not guidance, no statement of prerequisites (a valid price point must already exist), and no named alternative such as listing price points before calling 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?

Annotations declare destructiveHint=true and idempotentHint=false, yet the description never warns that updating an existing localization overwrites its fields or that repeated calls are not idempotent. 'Create or update' hints at mutation but adds no permissions, overwrite, or side-effect context that the annotations don't already imply.

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 its brevity is arguably under-specification rather than true conciseness for a destructive upsert.

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, non-idempotent mutation with no output schema, the description should explain overwrite semantics and the create/update branch. As written, an agent could call it without knowing that omitting or supplying localizationId changes behavior or that existing data may be replaced.

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 (including localizationId's 'provide to update instead of create') are documented in-schema. The description adds no parameter-level meaning beyond the schema, which is the baseline case for full coverage.

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 pair (create or update) and resource (localization for a subscription), which cleanly differentiates it from the list_subscription_localizations and the IAP analog set_iap_localization. It is clear what the tool acts on, though the upsert duality is left to the sentence rather than spelled out.

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?

No guidance on when to use this versus list_subscription_localizations, update_iap-style tools, or update_subscription. The create-vs-update branch condition exists only in the schema's localizationId parameter description, not in the tool description.

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, openWorldHint=true, and idempotentHint=false, so the safety profile is known. The description adds no behavioral context beyond that—it does not explain what existing pricing may be replaced, whether changes affect current subscribers, or any irreversible impact.

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 with no wasted words. It is appropriately concise, though its brevity contributes to gaps in usage and behavioral context that are scored elsewhere.

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, non-idempotent mutation tool with no output schema, the description is too thin. It omits critical context such as effects on existing subscribers, reversibility, and how startDate interacts with immediate changes, leaving the agent under-informed for a consequential write operation.

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 input schema already documents all three parameters clearly, including startDate semantics. The description adds no additional meaning, which meets the baseline of 3 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 (Set) and resource (price point for a subscription), which is clear enough to distinguish it from most sibling tools. It does not explicitly differentiate from adjacent tools like set_iap_price or set_subscription_localization.

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 guidance on when to use this tool versus alternatives such as set_iap_price, nor any mention of prerequisites like needing an existing subscription or price point. The agent gets no context on the expected workflow or when not to use 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?

Annotations already flag destructiveHint=true, idempotentHint=false and openWorldHint=true, so the description is not obligated to restate safety. However, it adds nothing beyond them: no mention that this transitions state and is not repeatable, that it begins serving traffic to real users, or what happens to a running experiment.

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 short, front-loaded sentence with no filler. It is efficiently written but arguably too terse for a destructive lifecycle transition.

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 non-idempotent, destructive state transition with no output schema, the description leaves out preconditions, resulting state, and side effects on live traffic. An agent could call it correctly in the mechanical sense but cannot predict the consequences.

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 the single experimentId parameter, so the schema carries the documentation burden and baseline 3 applies. The description adds no meaning about accepted ID formats or where to obtain the ID.

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 gives a specific verb ('Start') and resource ('A/B test experiment'), so an agent immediately knows the operation. It does not distinguish itself from the closely related siblings stop_experiment and create_experiment, which is the only thing keeping it from 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 guidance on when to call this rather than create_experiment or stop_experiment, and no stated precondition such as the experiment needing to exist in a draft or stopped state. The agent must infer the lifecycle from the sibling names alone.

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 disclose destructiveHint=true, idempotentHint=false and openWorldHint=true, so the risk profile is covered structurally. The description adds nothing beyond that – it does not say whether stopping is reversible, what happens to live traffic/allocations, or that a stopped experiment cannot be restarted.

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 zero filler. It is efficient, though its brevity borders on under-specification rather than pure conciseness.

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 one-parameter mutation tool, the annotations carry the safety profile and the schema carries the parameter, so the description covers the minimum. It still leaves out the operational consequences of stopping an experiment, which matters for a destructive, non-idempotent call.

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 required parameter with 100% schema description coverage, so the baseline is 3. The description adds no meaning about the ID format or where to obtain it, but none is required given the schema already documents 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 ('Stop') and resource ('running A/B test experiment'), so the agent immediately knows the action. It does not explicitly distinguish itself from the sibling start_experiment or from update_experiment, though the pairing is 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?

No guidance on when to use this versus alternatives such as start_experiment or update_experiment, and no prerequisites (e.g., the experiment must be running, or what happens if already stopped). The only contextual cue is the word 'running' embedded in the purpose statement.

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 the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true), so the safety burden is partly carried. The description usefully adds the prerequisite chain and the pre-condition that the build must be "processed," but says nothing about consequences — whether the submission can be withdrawn, what state the build enters, or typical review turnaround — which matters far more given destructiveHint=true.

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 sentences — the action and scope first, the disambiguation second. Every clause carries information; no filler or restatement of the title.

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 one-parameter submission tool with no output schema, the essentials (what it does, prerequisites, disambiguation) are covered. Missing are what the caller gets back or should do next — the tool has no output schema and the description does not route to get_beta_review_status — and any clarification of the required buildId format.

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 single parameter (buildId) has 0% schema description coverage and the description never mentions it, so the agent gets no guidance on whether this is an App Store Connect build identifier versus a build/version number, nor how to obtain it. The only implicit hint is "processed build," which gestures at a required build state but never links it to the 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?

Names a specific verb and resource ("Submit a processed build for TestFlight external Beta App Review") and explicitly scopes it against App Store review, which is the sibling operation an agent could easily confuse it with (submit_for_review). An agent can route correctly 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?

States the preconditions (beta app description, review contacts, export compliance must be complete) and rules out the App Store review path via "This is separate from App Store review." It stops short of naming the actual sibling tools to use for those prerequisites (e.g., set_build_export_compliance) or for checking the resulting status (get_beta_review_status).

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 the risky profile (destructiveHint=true, idempotentHint=false, openWorldHint=true); the description adds real value beyond that by exposing the multi-step internal flow (resolve/reuse draft, attach version, set submitted=true) and a failure/resume path. It still doesn't say what is irreversible about a submission, e.g. that review is queued and the submitted flag cannot simply be un-set.

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 dense sentences with zero filler, front-loading the action and followed by the disambiguation and failure path in priority order. Nothing could be cut without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema but full annotation coverage, the description covers purpose, sibling disambiguation, internal steps, and recovery. Missing only the consequences of a successful submit (locked state, review queue timing) that would let an agent warn the user before acting.

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 goes beyond it by explaining where submissionId comes from ("resume the returned submission ID") — an output-to-input relationship the schema doesn't state. The versionId/platform interaction is left to the schema's own descriptions.

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 ("Submit an app version for App Store review") plus the internal mechanics (resolve/reuse draft submission, attach version, set submitted=true). It explicitly distinguishes itself from submit_beta_review ("Separate from TestFlight beta review"), which is the nearest-sounding sibling.

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 an explicit when-not (TestFlight beta review is the other path) and a recovery rule ("On failure inspect and resume the returned submission ID"). It stops short of naming the exact recovery tool (get_review_submission) or stating preconditions such as the version needing to be in an editable state.

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=false, and openWorldHint=true, so the agent knows this is an irreversible external mutation. The description adds only the 'independent of app version' scope note and says nothing about side effects such as the IAP becoming locked from edits while in review or the failure mode on duplicate submission, which would be the valuable extra context given destructive/non-idempotent flags.

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 front-loaded sentence with the differentiator at the end; nothing redundant and nothing that could be cut.

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 single-parameter mutation with fully documented schema and annotations covering safety and idempotency, the description covers the essential purpose and scope. It could be slightly more complete about post-submission state changes, but there is no major gap.

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?

Only one parameter and schema coverage is 100%, with the schema documenting iapId as 'The in-app purchase ID'. The description adds no format, source, or lookup guidance, 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 (submit) and resource (in-app purchase) plus a scope qualifier ('independently of the app version') that separates it from the sibling submit_for_review, which presumably submits the app version itself. An agent can pick this over submit_for_review and submit_beta_review without opening a schema, though the differentiation is implied rather than stated by name.

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 'independently of the app version' hints at the use case (IAP review that isn't tied to an app version submission), but it never says when to choose this over submit_for_review, nor what prerequisites exist (e.g., IAP must be in a ready state, no pending review).

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, openWorldHint=true, idempotentHint=false, and readOnlyHint=false. The description adds only the locale-scoping notion, but does not explain what gets overwritten, whether the change is reversible, or what permissions are required.

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, efficient sentence with no wasted words.

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?

The schema is fully documented and annotations carry the safety profile, so the tool is callable. Still, for a destructive mutation with no output schema, the description could say more about effects, validation, or return behavior.

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 required parameters are already documented in the schema. The description adds little beyond reinforcing that the update targets a locale, which is already clear from localizationId.

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 ('Update the app description') and adds scope ('for a specific locale'). However, it does not distinguish this from nearby siblings like update_whats_new or update_keywords, which also mutate localized app-store text.

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 guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The agent must infer usage entirely from the name and schema.

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, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds nothing beyond the plain actions: it does not say what enabling a public link exposes (unauthenticated joiners), whether disabling revokes access for already-joined testers, or what permissions are needed.

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 with the resource and actions front-loaded and no filler. It is efficient, though it could be split to separate the rename case from the public-link case.

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?

This is a destructive, non-idempotent mutation with five undocumented parameters and no output schema. The description does not cover permission requirements, side effects on existing testers, or the interaction between the limit flag and the limit value, leaving meaningful gaps for an agent.

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 0%, so the description must compensate. It maps the name parameter to renaming and the three publicLink* parameters to the invitation link and tester limit, which is useful, but it never explains the coupling between publicLinkEnabled and publicLinkLimitEnabled or the 1–10000 bound on publicLinkLimit.

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 resource (TestFlight group) and specific operations (rename, toggle public invitation link, set tester limit), which distinguishes it from create_beta_group and list_beta_groups. It is clear but does not explicitly state that it is the sole mutator for these group attributes beyond creation.

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 guidance on when to use this versus alternatives (create_beta_group, add_testers_to_beta_group) or on prerequisites such as needing an existing betaGroupId. Usage is only implied by the verb 'rename' and 'enable/disable'.

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 disclose that this is not read-only, is open-world, non-idempotent, and destructive. The description adds only that name or visibility can be changed, but does not explain the destructive implications of changing visibility, permission requirements, or what happens to the page after the update.

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 with no redundant or wasted language. It is appropriately sized for the amount of information it chooses to convey.

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?

The annotations and complete parameter schema provide the essential context, and the description states the editable fields. However, for a destructive update tool with no output schema, it does not explain prerequisites, side effects of visibility changes, or expected results.

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 pageId, name, and visible. The description mentions name and visibility but does not add meaning beyond the schema, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: update a custom product page, limited to name or visibility. It is clear, but it does not explicitly differentiate this tool from siblings like create_custom_product_page, get_custom_product_page, or list_custom_product_pages.

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 gives no guidance on when to use this tool versus alternatives such as get_custom_product_page or create_custom_product_page. Usage is only implied by the verb 'Update'.

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 this is a destructive, non-idempotent, open-world write operation. The description adds nothing beyond 'update'—it doesn't say whether omitted fields are preserved, whether reviewNotes trigger re-review, or what prior state is needed. With annotations covering the safety profile, the description should still add operational context but doesn't.

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 waste. It is appropriately sized for a one-line purpose statement, though it leaves the reader wanting scope details.

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 several sibling tools, the description is too thin. It doesn't clarify partial-vs-full update semantics, does not route price/localization edits to their dedicated siblings, and gives no prerequisite context (e.g., needing an existing iapId from get_iap).

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 three parameters (iapId, name, reviewNote) are fully documented in the schema. The description adds no additional meaning, 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?

The description states a verb and resource ('Update an existing in-app purchase'), but it is vague about scope: it doesn't say which fields are updatable. With siblings like set_iap_price, set_iap_localization, and submit_iap_for_review, an agent cannot tell whether this is the metadata-edit tool or something broader.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives. The description gives no hint that price changes belong to set_iap_price or localization changes belong to set_iap_localization.

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=false, and openWorldHint=true, so the description's burden is lighter — yet it adds nothing. Critically, it never says that the supplied keywords replace the existing keyword set entirely (the likely source of the destructive hint) or whether there are length/character 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 front-loaded sentence with zero padding. It is efficient, though the brevity reflects under-specification rather than deliberate compression of rich content.

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, non-idempotent mutation with no output schema, the description omits replace-vs-append semantics, validation limits, and what is returned. An agent can guess the intent but not the consequences of calling it.

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% (both params documented, including 'Comma-separated keywords'), so the baseline is 3. The phrase 'for a specific locale' loosely gestures at localizationId but adds no format or sourcing detail 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 ('Update the keywords') plus a scope qualifier ('for a specific locale'), which is enough to distinguish it from siblings like update_app_description or set_iap_localization. It does not explicitly name those siblings as alternatives, keeping it below 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?

The description gives no guidance on when to use this tool versus update_app_description, update_whats_new, or the localization listers. No prerequisites are mentioned, such as needing an existing localization ID from list_app_store_version_localizations.

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, idempotentHint=false, and openWorldHint=true, so the safety profile is partly covered. But the description adds nothing: it does not say that the change affects a live App Store subscription, that omitted fields are left untouched, that the operation is not idempotent, or that App Review-relevant fields are in scope. For a destructive mutation with no output schema, this is a substantial 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?

The single sentence is front-loaded and free of waste, but it is under-specified rather than concise in a useful way – brevity here costs information rather than saving 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?

For a five-parameter destructive mutation with no output schema and no annotations that explain side effects, the description should say what changes, what is preserved, and what the result looks like. None of that is present, leaving the agent dependent entirely on the schema field names.

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%, with each of the five parameters documented in the schema itself (including the required subscriptionId and the meaning of groupLevel priority). The description contributes no additional parameter meaning, 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?

The description names a specific verb (Update) and resource (subscription), so the basic operation is unambiguous. However, it adds nothing beyond the tool name and does not distinguish it from the many sibling mutation tools (update_iap, update_beta_group, update_app_description), nor does it say which aspects of the subscription are updatable.

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 such as create_subscription or set_subscription_price. The agent must infer from the name alone that this is the tool for modifying an existing subscription's metadata.

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 and idempotentHint=false, so the safety profile is covered. The description adds nothing beyond that — it doesn't say the existing text is overwritten, whether the change is reversible, or what permissions/version states are required for a destructive mutation.

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 efficient sentence with the resource and scope front-loaded and zero padding. It is terse but not wasteful.

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, non-idempotent mutation with no output schema, the description omits what an agent needs most: permissions, version-state prerequisites, overwrite semantics, and the expected result. Annotations cover only the safety flags.

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% and both parameters carry descriptions, so the schema does the heavy lifting. The phrase 'for a specific locale' loosely maps to localizationId but adds no format or sourcing guidance (e.g., where the localization ID comes 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?

The description gives a specific verb ('Update') and resource ('What's New' text) scoped to a locale, which is clear enough to distinguish it from sibling tools like update_app_description or update_keywords. It stops short of explicitly naming those siblings as alternatives.

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 indication of when to use this tool versus update_app_description/update_keywords, nor any mention of prerequisites such as the version localization needing to be in an editable state. The agent must infer the context entirely.

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 this as a non-read-only, destructive, open-world, non-idempotent operation. The description adds valuable operational context beyond annotations: chunk streaming, checksum commit behavior, host timeout risk for large builds, and inspecting returned reservation IDs before retrying after failure.

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 four short sentences, front-loads the core upload action, and every sentence contributes either scope, safe-usage guidance, or failure behavior. There is no redundant wording.

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 complex write tool with five parameters and no output schema, the description covers purpose, scope, and failure behavior well. However, it leaves significant gaps around the meanings of four required parameters and does not describe the successful return shape beyond referencing reservation IDs on failure.

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 20%, and only filePath is documented in the schema. The description adds some semantics for the file (signed, local, supported extensions), but it does not explain appId, version, buildNumber, or platform, leaving most required parameters without added meaning.

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: uploading a ready, signed local .ipa/.pkg/.zip via Apple's Build Upload API. It also explicitly excludes compile, sign, distribute, and submit-review behavior, which distinguishes it from siblings such as 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?

It clearly says when to use it (a ready, signed local build), when not to use it (not for compiling, signing, distributing, or submitting review), and gives an alternative for large builds: prefer the CLI to avoid host timeouts. It also includes a retry guideline on failure.

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, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description contributes real context beyond that — reservation must pre-exist, instructions are fetched from Apple (open-world behavior), checksum is committed — but never explains what the destructive behavior actually destroys (e.g. overwriting an existing asset) or what happens on a checksum mismatch.

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 core action and its constraint, with zero filler. The closing note about Apple-sourced upload instructions is slightly tangential but still earns its place as behavioral context.

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, open-world mutation with no output schema and no parameter documentation, the description covers the prerequisite chain but omits the result contract (is the checksum echoed back? what signals success?) and failure modes. Adequate to attempt a call, not enough to call it confidently.

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 0%, so the description carries the burden and it partially does: the four enumerated resource types are spelled out in prose, mapping to the resourceType enum. However, filePath (local vs remote path) and resourceId (what ID space it lives in) get no explanation at all, leaving two of three parameters undocumented anywhere.

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 pair: upload a local file into an existing Apple reservation and commit its checksum, which is more precise than the name alone. It does not explicitly differentiate itself from the sibling upload_build, even though buildUploadFiles is listed as one of its resource types, leaving a small ambiguity an agent must resolve.

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 clear prerequisite: the reservation must exist and is created through write_api first, and notes that upload instructions come from Apple. It stops short of stating when to choose this over upload_build or what to do on failure, so no explicit exclusions are offered.

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, openWorldHint and non-idempotency, but the description adds context annotations cannot: the operation mutates production data, and dryRun performs validation without any network call. It does not say what a successful call returns or how partial failures surface, leaving a gap for a destructive no-output-schema tool.

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 action and the production-impact warning, then the dryRun escape hatch, then the hard limitation. No sentence is 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 five-parameter, nested-object, destructive tool with no output schema, it covers safety and validation but omits the response shape and any guidance on resolving path/query values. An agent knows it is dangerous but not what it gets back.

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%: operationId and body are described there, but path and query are undocumented in both places. The description's one real contribution is the dryRun semantic (validates without a network call), which the bare boolean in the schema does not convey; it says nothing about operationId sourcing or path/query usage.

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 class plus resource and scope: 'Execute a schema-validated official Apple POST/PATCH/DELETE operation.' The word 'official' and the schema-validated framing distinguish it from the read-only sibling read_api and from the discovery tools search_api_operations/get_api_operation.

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 real precondition ('only use within the user's authorized scope'), a validation path via dryRun, and one explicit exclusion ('Cannot create a new app record: Apple requires its website'). It stops short of steering the agent to dedicated siblings such as update_app_description or set_iap_price when those exist for a specific mutation.

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