search_app_listing

What it does

• Read-only
• Idempotent
• Open world
• Account required

Stop typing what Apple already published. Search by app or developer name and each result comes back with the app’s exact name, its seller, its icon, its bundle ID and its numeric app ID, plus the App Store Connect languages and the iPhone devices ShotOps would apply if you linked it. Hand the chosen result’s app ID to save_project as appListing and the project it creates is the real app rather than a guess. Read-only: it renders nothing, writes nothing and changes no project.

You can ask: “Find the Tidebook app so the project carries its real name and languages.”

Open-world because the answer comes from Apple, not from ShotOps: the same term can return something different tomorrow, so the result is not a thing to cache.

Finding a public listing proves nothing about who owns the app. The bundle ID on the project stays freely editable, and a store release verifies ownership separately.

Input

• termstringrequiredat least 1 characterat most 200 characters

  What to search the App Store for — the app name as the user said it ("Duolingo"), or the developer's name. Each result carries the app ID to pass as save_project's appListing.

• countrystringoptionalpattern ^[A-Za-z]{2}$

  The two-letter App Store storefront to search, e.g. "dk". Defaults to "us". An app released in one country only is invisible to a search of any other, so pass the user's own storefront when they say the app is not showing up.

Result

• okbooleanoptional

• resultsarrayoptional

  each item

  object

  • appIdstringrequired

    Apple’s numeric app ID, as a string. Pass it as save_project’s appListing.

  • bundleIdstringrequired

  • namestringrequired

  • sellerstringrequired

  • storeUrlstringoptional

    The listing’s own App Store page. Carries the storefront, so it is the reference to reuse for a non-US app.

  • iconUrlstringoptional

    The app icon on Apple’s CDN. Shown as project chrome; never downloaded and never rendered into a strip.

  • localesarrayrequired

    The App Store Connect locales this listing’s languages map to, in catalog order.

    each item

    string

  • baseLocalestringrequired

    The caption base the other locales inherit from. Derived — Apple never says which language is primary.

  • outputsarrayrequired

    The ShotOps output devices this listing fills. iPhone only, and EMPTY for an iPad-only app.

    each item

    string

  • supportsIpadbooleanrequired

    The listing supports iPad. Recorded, and applied to no output until iPad panels ship.

  • storefrontstringrequired

    The two-letter storefront this was read from. It decides baseLocale.

  • droppedLanguageCodesarrayoptional

    Apple language codes this build maps no App Store Connect locale for. Omitted when nothing was dropped.

    each item

    string

• messagestringoptional

Example

That request maps to this call:

{
  "name": "search_app_listing",
  "arguments": {
    "term": "Tidebook tide forecast"
  }
}

Up to ten matching apps. Each carries appId, bundleId, name, seller, iconUrl, storeUrl, and the locales, baseLocale and outputs linking it would apply. Let the user pick — the icon and the seller are what prove which app is theirs.

Access and cost

• Needs an account, on both doors. An unsigned local server has no way to reach the App Store and says so.
• Free and unmetered. Searching spends no cloud credits.
• Apple’s public listing data only — the same page anyone can open. No Apple or App Store Connect credential is involved.

When it refuses

The user’s app does not come back.

An app released in one country is invisible to a search of any other. Pass country with their two-letter storefront, or ask them for the App Store link and hand that straight to save_project’s appListing.

Several results look alike.

Do not guess. Show the names, sellers and icons and let the user say which one is theirs — linking the wrong app puts the wrong bundle ID and the wrong language list on the project.

The reply says the App Store is rate-limiting or unreachable.

Apple throttles lookups per server. Wait a moment and try again; nothing was saved or changed, and the user can still name the project themselves.

Where this fits

• Linking a project to its App Store listing

What the agent is told

The title and description the server publishes on tools/list — this is the copy a model chooses between, reproduced verbatim.