Account tools

Some connected accounts offer tools: reports and lookups you can run on them. Right now: Facebook, Instagram, Google Search Console, Google Analytics, YouTube and Google Ads. Each platform page lists its tools and their parameters.

List an account’s tools

GET /api/v1/accounts/{id}/tools returns each tool with a description, a read_only flag and an input_schema (JSON Schema). Accounts that only receive posts return an empty list.

curl https://socialhelper.app/api/v1/accounts/ACCOUNT_ID/tools \
  -H "Authorization: Bearer $SOCIALHELPER_API_KEY"

{
    "data": [
        {
            "object": "tool",
            "name": "list_sites",
            "description": "List the Search Console properties this account can access, with its permission level on each.",
            "read_only": true,
            "input_schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
            }
        }
    ]
}

Run a tool

POST /api/v1/accounts/{id}/tools/{tool} with the tool’s input as the JSON body (not wrapped in another object). Parameters you leave out get their defaults. The tool runs once, straight away, and isn’t retried automatically.

curl https://socialhelper.app/api/v1/accounts/ACCOUNT_ID/tools/search_analytics \
  -H "Authorization: Bearer $SOCIALHELPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "site_url": "sc-domain:example.com",
      "start_date": "2026-09-01",
      "end_date": "2026-09-30",
      "dimensions": [
          "query"
      ],
      "row_limit": 10
  }'

{
    "object": "tool_result",
    "account": "ACCOUNT_ID",
    "tool": "search_analytics",
    "data": {
        "…": "…"
    }
}

A successful run returns 200. data holds what the platform returned, in the shape the tool’s description explains.

Tips

• Start with a listing tool, such as list_sites or list_properties, to get the identifiers other tools need.
• Most tools only read. Tools that make changes have read_only set to false.
• Tool calls count towards the same rate limit as everything else.

Errors

Platform problems come back with a code you can act on:

From an AI agent

Over MCP, list_account_tools takes an account_id, and run_account_tool takes account_id, tool and the tool’s input as an object. Problems come back as tool errors the agent can read.