Set an app's availability by specifying the countries it is sold in. Submit an empty list to remove it from all territories.
Set an app’s availability — the countries it is sold in. Submitting an empty list removes the app from all territories; submitting some limits it to those. [POST /v2/appAvailabilities]
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | JSON:API request body (Apple schema: AppAvailabilityV2CreateRequest). |
Changes observed during successful MCP inspections.
v1.3.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide generic hints (not read-only, not idempotent, not destructive). The description adds critical behavior: 'Submitting an empty list removes the app from all territories; submitting some limits it to those.' This clarifies the replace/clear semantics and goes beyond the schema. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sntences with no wasted words. Purpose, key behavior, and HTTP endpoint are each front-loaded. The critical empty-list rule is succinctly stated and easy to parse.
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 nested JSON:API create, the description covers high-level behavior but omits response details (no output schema) and prerequisites or error conditions. It is sufficient for selecting the tool but an agent might need to inspect the schema deeply to construct a valid body correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds semantic meaning for the territoryAvailabilities array (empty list clears fully). However, no explanation is given for required fields like availableInNewTerritories or the included territory attributes, so parameter guidance remains partial.
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?
Description opens with a specific verb and resource: 'Set an app's availability — the countries it is sold in.' This clearly distinguishes the write operation from sibling read tools like app_availabilities_v2__get. The added empty-list semantics further pins down the exact behavior.
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 when to use it (to set or remove territories) but does not explicitly name alternatives or state 'use this instead of get/list.' An agent can infer the write intent from 'Set' and the contrast with sibling get/list tools, but explicit routing guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.