MCP Apple Ads

Apple Ads: Raw API Request

apple_ads_request

Read-only

Call any Apple Ads Platform API endpoint not covered by a dedicated tool, with ad-account context injected automatically; only GET requests are permitted by default.

Instructions

Call any Apple Ads Platform API endpoint that no dedicated tool wraps — Maps advertising (/business-brands/*), asset upload, recommendations, location targeting, change history. The ad-account context header is injected for you. You get no argument validation, no response shaping and no safety checks: prefer a dedicated tool where one exists. Writes are DISABLED: only GET is permitted. Set APPLE_ADS_ALLOW_WRITES=1 to allow mutations.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "path": "<path>"
    },
    "name": "apple_ads_request"
  }
}

Input Schema

Name	Required	Description	Default
`body`	No	JSON body, for POST and PUT. Most Apple Ads queries are POST with a body.
`path`	Yes	Path relative to the API root, e.g. "/recommendations/daily-budgets/query". Not a full URL.
`method`	No	HTTP method.	GET
`savePath`	No	Absolute path to also write this result to, as pretty-printed JSON. Use it rather than copying values out of the response into a file by hand. Parent directories are created.
`adAccountId`	No	The ad account to act on. Omit it when you have exactly one or APPLE_ADS_AD_ACCOUNT_ID is set — it is resolved automatically. List them with apple_ads_list_accounts.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 7, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Goes well beyond the readOnlyHint/destructiveHint annotations: it discloses that the ad-account context header is injected automatically, that there is no argument validation, no response shaping, and no safety checks. The only wrinkle is the APPLE_ADS_ALLOW_WRITES=1 mention, which is inconsistent with the schema's GET-only method enum rather than with the annotations — a stale-looking caveat rather than a contradiction of readOnlyHint.

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

Conciseness5/5

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

Three tight sentences, front-loaded with what the tool is and what it covers, followed by the routing rule and then the safety constraints. No filler, and the most decision-relevant facts (no dedicated tool, GET only) appear before the caveats.

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

Completeness5/5

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

For a raw passthrough tool with five parameters and no output schema, the definition covers everything an agent needs before calling: scope, path expectations, write restrictions, absence of validation/shaping, auth/account handling, and the sibling alternative. Return values need not be described since responses are unshaped API payloads, which the description says outright.

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

Parameters3/5

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

Schema description coverage is 100%, so the five parameters (path, method, body, savePath, adAccountId) are already fully documented, including the relative-path rule and body usage. The description adds only the header-injection note tying adAccountId to transport behavior, which is a marginal gain over the schema — baseline 3 applies.

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

Purpose5/5

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

States a specific verb and resource — call any Apple Ads Platform API endpoint not covered by a dedicated tool — and enumerates the concrete gaps it fills (/business-brands/*, asset upload, recommendations, location targeting, change history). An agent can immediately tell this apart from the enumerated sibling list tools like apple_ads_get_campaign or apple_ads_list_keywords.

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

Usage Guidelines5/5

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

Explicitly routes the agent: use this only where no dedicated tool exists, and 'prefer a dedicated tool where one exists.' It also states the operational constraint (GET only, writes disabled unless APPLE_ADS_ALLOW_WRITES=1), which is exactly the when-to-use / when-not-to-use guidance needed for a raw passthrough tool.

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