amekala/ads-mcp/adspirer-mcp

Calling the Adspirer MCP hub

Adspirer exposes a small set of top-level tools. Platform and product tools sit behind routers. Calling a platform tool by its own name does not work — it is not in the tool list. Read this before your first tool call. The live list wins over the names below: list_tools and get_tool_schema are free.

The tool surface

Call these directly, by name:

These are routers. Never call their inner tools by name:

google_ads · meta_ads · linkedin_ads · tiktok_ads · amazon_ads · walmart_ads · microsoft_ads · chatgpt_ads · monitoring_and_reporting · community_plugins

These appear only when that product is connected:

google_analytics · google_search_console · google_tag_manager · klaviyo

Another product router may show up the same way. If you don't see it, it isn't connected — say so and point the user at https://adspirer.ai/connections. Don't insist the tool exists.

The router two-step

Every router takes the same three fields: action, tool_name, arguments.

Step 1 — discover. Always first. Never costs quota.

{ "action": "list_tools" }

Returns every tool on that platform with its full parameter schema.

Step 2 — execute. Use an exact tool_name from step 1.

{
  "action": "execute",
  "tool_name": "list_tiktok_campaigns",
  "arguments": { "advertiser_id": "7012345678901234567" }
}

Rules

• action: "execute" without a tool_name is invalid. It returns an error. **Do not retry

the same call** — go back to list_tools and read the real tool name.

• Never pass a platform tool name as action. action is only ever "list_tools" or "execute".
• search_tools and get_tool_schema are top-level. Call them directly when they are in

your tool list. If your client does not list get_tool_schema, call it through any platform router: google_ads with action: "execute", tool_name: "get_tool_schema", arguments: {"tool_names": [...]}. It returns the same schema. Never stop because it is missing.

• Never guess a tool name or a parameter. If you are unsure, call list_tools or get_tool_schema.

Finding the right tool

When you don't know which tool does the job:

1. search_tools with a natural-language description of the task.
2. get_tool_schema with the candidate names to get their exact parameters. Not in your tool

list? Call it through a router (see Rules above).

1. Call the tool: directly if it's in the direct list above, otherwise through its router with

action: "execute".

Budgets: the unit differs per platform

This is the single most common error. Read the row before you send a budget.

Every platform takes the budget in the account's own currency as a plain decimal — never cents, never multiplied by anything. For a $20/day budget send 20, not 2000. For $50/day send 50. The tools convert to each platform's internal unit for you; if you send 2000 meaning $20 you will book `$2,000/day` — a 100× overspend.

Never convert the user's currency to USD. Send the number in the account's own currency.

Accounts

One connected account is selected automatically. With two or more active accounts you must name one — the call fails with a multi_account error that lists them.

The parameter name differs per platform:

Send IDs as strings, not numbers. Naming an account the user has not connected returns a 403 — it never quietly falls back to another account, so do not treat 403 as "try again without the id."

Use get_connections_status to see what is connected.

Conversion-tracking audit

audit_conversion_tracking is direct. Send platform and the account id as a string (customer_id on Google). lookback_days is 7, 14, 30, 60, or 90. It covers Google, Meta, and LinkedIn — not Microsoft. It looks back from today, not over whatever history a performance read cached. If that window had no delivery, "no conversions" is not proof the tag is broken. Say the window had no delivery.

With more than one Google Ads account connected, the tool can ignore customer_id and answer "You have N google_ads accounts connected. Please specify..." anyway. Retry the same call once. If it fails the same way, don't keep retrying. See the error catalog.

Switching the primary account (switch_primary_account) changes which account later calls treat as active. That needs its own yes. It is not something you do silently to make an audit run.

Quota

Every tool call against a platform costs one call from the user's monthly quota (Free 15 · Plus 150 · Pro 600 · Max 3,000).

Free — call these as much as you need: action: "list_tools" on any router, start_here, get_connections_status, get_usage_status, echo_test, and everything under community_plugins.

Because discovery is free, there is never a reason to guess a tool name to save quota.

When a user runs out: Plus/Pro/Max monthly plans keep working and bill per extra call; annual plans stop at the cap. Show the error message you receive — it carries the upgrade link. Do not work around a quota error or invent the data.

Tools that may not be there

google_analytics, google_search_console, google_tag_manager, and klaviyo appear only when that product is connected. If you don't see the router, the connection is missing — say so and point them at https://adspirer.ai/connections. Don't insist the tool exists. microsoft_ads is a platform router like Google and Meta; a missing performance or keyword tool inside it is a catalog gap, not a missing connection. adspirer-microsoft-ads describes that gap.

When something fails

Read references/error-catalog.md for the known error codes and their fixes before retrying anything. Retrying an invalid call unchanged will fail the same way.