The tool surface

Why a router

A flat list of 203 tools costs thousands of tokens on every request, and some clients truncate a list that long. So the client sees a short, stable list: the tools people ask for by name, plus a read router and a write router per platform. Everything else is one hop away and costs nothing to discover.

Reads and changes

Assistants such as Claude ask permission per tool, not per call. Looking things up never changes an account, so an assistant that asks permission per tool can allow google_ads once. Every change runs through google_ads_write, which asks each time and creates a proposal.

Callable by name

Routers

The three actions

A read router takes three actions. Its write router takes one: execute, with a change.

google_ads(action="list_tools")
google_ads(action="get_tool_schema", tool_name="google_pause_campaign")
google_ads(action="execute", tool_name="google_analyze_search_terms",
           arguments={"customer_id": "1234567890", "date_range": "last_30_days"})
google_ads_write(action="execute", tool_name="google_pause_campaign",
                 arguments={"customer_id": "1234567890", "campaign_id": "111"})

• list_tools returns every tool the pair covers, reads and changes, grouped by category, each with a one-line summary and the exact line to call it with. Free, and no task is charged.
• get_tool_schema returns the JSON schema, required fields, enums and example prompts for any of those tools, changes included. Free.
• execute on google_ads runs read tools only, and they answer immediately. A change sent there runs nothing and returns the exact google_ads_write call to make instead.
• execute on google_ads_write runs change tools only, through the same pipeline as everything else: auth, validation, quota, the proposal gate, execution, read-back, audit. Nothing changes until you approve, in the chat or in the web app, and whatever it creates starts behind a paused switch. It bills the tool’s own cost. A read sent there points back to google_ads.

Finding the right tool

search_tools ranks the whole registry against the user’s own wording, across every platform, and returns the exact line to call each match with. It is free and instant, and it is the right first call whenever the tool is not obvious.

search_tools(query="stop a campaign that is wasting money", top_k=5)
get_tool_schema(tool_names=["meta_pause_entity"])
meta_ads_write(action="execute", tool_name="meta_pause_entity",
               arguments={"entity_type": "campaign", "entity_id": "23851..."})

Both discovery tools cost nothing, so an assistant never has to guess a name, or which router to send it to: the call line names it. An unknown name returns suggestions rather than a result.

One read across several accounts

A platform’s read router takes an accounts argument on read tools. It runs the tool once per account, one after another, and returns a single consolidated answer.

google_ads(action="execute", tool_name="google_get_campaign_performance",
           arguments={"date_range": "last_30_days"}, accounts="all_active")

• accounts takes a list of account ids or the literal "all_active".
• Reads only. The write routers take no accounts; writes stay one account at a time.
• Free, like every read. At most 20 accounts in one call.
• Results are grouped per account, with the currency each one reports in.

Over REST

Routers, read and write, are MCP only. Over the REST API the URL is the dispatch: POST /api/v1/tools/{tool_name}/execute. Same pipeline, same quota, same proposals. search_tools and get_tool_schema work there too, and their call lines come back as the request to send.