AppTail – ASO & Keyword Research

Search Apps

search_apps

Search for iOS apps by name, bundle ID, or App Store URL. Supports all languages including Cyrillic, Chinese, etc. If the app is not in our database, it will be fetched from the App Store, persisted as a shared public app record, and queued for enrichment. This does not add the app to your account or competitor watchlist. Auto-detects the likely App Store region from the query language (e.g. Cyrillic → Russia, Chinese → China). To add what you find, add_competitors and add_app take the same name or URL directly — you do not have to look up an app_id first.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Max results. Default 10, capped at 25.
`query`	Yes	App name in any language, a bundle id (com.example.app), or a full App Store URL. Searches Apptail first and falls back to the App Store, importing anything it finds — so this returns a usable app_id even for an app we have never seen. This is how you turn a name a user typed into an app_id.
`country`	No	Storefront to search (e.g. "us", "ru"). Omit and it is guessed from the script the query is written in — Cyrillic implies ru, and so on. Pass it explicitly when the user names a market, because the guess is about language and not about where they sell.

Output Schema

TableJSON Schema

Name	Required	Description
`apps`	Yes	Matching apps, best match first. Empty when nothing was found.
`hint`	No	Present when nothing was found: suggests how to retry.
`note`	No	Present when the results need a caveat, e.g. data still being fetched in the background.
`count`	Yes	Number of apps returned.
`source`	Yes	Where the results came from. "app_store" means they were just imported and are still being enriched.
`country`	No	Storefront that was searched. Null when answered from the local database, which is not country-specific.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 2, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only say readOnlyHint=false and openWorldHint=true; the description supplies the real behavioral story the agent needs: a miss triggers an App Store fetch, persistence of a shared public app record, and an enrichment queue. That explains why a 'search' is not read-only, which the annotations alone leave opaque.

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

Conciseness4/5

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

Six sentences, front-loaded with purpose and searchable forms, then side effects, then routing. Every sentence carries information, though the closing note that no app_id lookup is needed slightly overlaps what the query parameter description already says.

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 an open-world, non-read-only lookup tool with 3 params, an output schema, and full schema coverage, the description covers the import side effects, region inference, and sibling routing. Nothing an agent needs to call it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: the region is auto-detected from the query script (Cyrillic→ru, Chinese→China) and it warns that the guess reflects language, not market, so country should be passed explicitly when a market is named. It goes beyond restating the schema.

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?

Names a specific verb and resource ('Search for iOS apps') and spells out the accepted query forms: name, bundle ID, or App Store URL. It is clearly distinguishable from get_app, add_app, and other siblings by being the lookup/import entry point.

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 states what this does NOT do ('does not add the app to your account or competitor watchlist') and routes the agent to the correct alternatives, add_competitors and add_app, noting they accept the same name or URL. This is exactly the when/when-not/alternatives guidance the dimension asks for.

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

All AppTail – ASO & Keyword Research tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?