Tools

Every tool runs one route of the REST API with the caller's credential: one authorization path, so a tool needs the same permission as its route, checks site access the same way and answers the same data. The tool reference below lists every tool with its arguments, its permission and the route it runs. It is generated from the server's own tools/list answer, and the backend's tests fail when it falls behind.

A client sees only the tools its credential allows: an API key gets the tools of its permissions, an OAuth token those of its scopes and the person's role together. Calling a tool the credential does not have is a JSON-RPC error, -32602 "Tool create_goal not found".

How a tool runsCopy Anchor Link

The tool's arguments become the route's request:

• Arguments named in the route's path (siteId, and id, sessionId or userId where the route has them) fill the path. An empty value, . or .. is refused before the route runs (bad_request, "Invalid id" for an id).
• body, for the tools that have it, is the route's JSON request body.
• Every other argument goes to the query string, to the REST parameter of the same name; filters is sent as JSON, as the REST API expects. The route's page in the API reference documents the values each parameter takes (GET /api/v1/sites/{siteId}/pages for the pages tool, for example).
• list_sites takes no organization: it reads the credential's own organization.

The route then validates the request, checks the credential's access to the site and runs. When the client cancels an MCP request, a GET tool's route stops its query too.

Arguments shared by the reportsCopy Anchor Link

SiteCopy Anchor Link

siteId is the site's public id, the same value as the tracking script's data-site attribute. list_sites returns the ids the credential can reach.

Time windowCopy Anchor Link

Every tool that takes start, end, last and all needs a time window, given in exactly one of three ways:

The tool's input schema (and the reference below) marks each of these arguments as optional, because the REST route checks the combination, not the schema; the description of start says that every call needs exactly one window. A call without a window, or with two forms, fails with this error result:

{"code":"bad_request","message":"Invalid request","details":[{"in":"querystring","path":"/","code":"custom","message":"exactly one of start+end, last or all is required"}]}

This holds for overview, timeseries, breakdown, pages, geo_countries, geo_points, events, event_names, errors, vitals, sessions, users, analyze_funnel, journeys, retention, revenue_summary, revenue_breakdown and annotations. The one exception is events with since (a realtime tail of the events since an ISO instant within the last 24 hours), which takes no window. The other tools (list_sites, get_site, live, session, user, goals, funnels, segments, and the create, update, save and delete tools) have no window arguments. If you write instructions for an assistant, tell it to pass a window, such as "last": "28d".

tz is an IANA time zone (default: the site's). bucket sets the time series' step (default: chosen from the window's length). compare (previous or year) adds the previous period of the same length, or the same period a year earlier, to overview, timeseries and revenue_summary, the only tools that take it. See Time windows, filters and comparisons for the details.

Filters and saved segmentsCopy Anchor Link

filters is a list of conditions, all of which must hold (at most 20): { "dim": "country", "op": "eq", "values": ["US"] }. The dimensions and operators are the REST API's, listed in Time windows, filters and comparisons.

segment applies a saved segment: pass the id of one returned by the segments tool, and its filters apply, merged with any filters you add. These two calls give the same numbers when segment ae378024-… holds those two filters:

{ "siteId": "SITE_ID", "last": "7d", "segment": "ae378024-68b3-43b3-8ba3-5860a3a5beec" }

{
  "siteId": "SITE_ID",
  "last": "7d",
  "filters": [
    { "dim": "device_type", "op": "eq", "values": ["desktop"] },
    { "dim": "referrer_domain", "op": "eq", "values": ["google.com"] }
  ]
}

An API key sees only the segments shared with the organization; an OAuth token also sees the person's own private segments. A segment the credential cannot see answers not_found "Segment not found".

PagingCopy Anchor Link

Lists return one page at a time. breakdown, pages, errors and revenue_breakdown take limit and offset, and their meta.totalCount gives the number of rows. events, sessions and users take limit and cursor: pass the previous page's meta.nextCursor as cursor to get the next one (it is null on the last page). See Pagination.

Results and error resultsCopy Anchor Link

A successful call returns one text block holding the route's JSON response, { "data": …, "meta": … }, with every string cleaned of invisible and control characters (see Tool results are data, not instructions). A tool whose route answers 204 No Content, such as delete_goal, returns {}.

{
  "content": [
    {
      "type": "text",
      "text": "{\"data\":[{\"value\":\"google.com\",\"visitors\":72,\"sessions\":78,\"pageviews\":177,\"bounce_rate\":35.8974358974359,\"avg_session_duration\":90.77826923076924,\"percentage\":36.18090452261307},{\"value\":\"news.ycombinator.com\",\"visitors\":22,\"sessions\":23,\"pageviews\":49,\"bounce_rate\":47.82608695652174,\"avg_session_duration\":87.45765217391305,\"percentage\":11.055276381909549}],\"meta\":{\"window\":{\"from\":\"2026-10-20T20:39:21.096Z\",\"to\":\"2026-10-27T20:39:21.096Z\",\"tz\":\"UTC\",\"bucket\":\"day\"},\"totalCount\":7,\"cache\":\"miss\"}}"
    }
  ]
}

A call that fails returns isError: true and a text block:

A site the credential cannot reach answers not_found, whether it exists or not.

Write toolsCopy Anchor Link

The tools whose Effect is "adds" or "changes or deletes" in the reference write. They need goals:write, funnels:write or annotations:write, and their body is the request body of their REST route.

Goal bodiesCopy Anchor Link

create_goal takes { name, condition, icon? } and update_goal any of these fields (at least one). name has 1 to 100 characters; icon is one character or null; condition is one of:

props is a list of up to 10 property conditions { key, op, value }, with op one of eq, neq, contains, gt, lt. A site holds at most 100 goals. The full schema is in the API reference: create a goal, update a goal.

{
  "siteId": "SITE_ID",
  "body": { "name": "Viewed pricing", "condition": { "kind": "page", "path": "/pricing" } }
}

Funnel bodiesCopy Anchor Link

save_funnel takes { name, steps, windowSeconds? }, and analyze_funnel { steps, windowSeconds? } plus a time window. steps holds 2 to 10 conditions of the goal form above, each with an optional label (1 to 100 characters). Without windowSeconds, a funnel counts the steps within one session; with it (1 to 7,776,000 seconds), it follows each user across sessions and keeps the steps within that many seconds of the first. analyze_funnel only reads: it reports the conversion of steps you have not saved. See analyze a funnel and save a funnel.

{
  "siteId": "SITE_ID",
  "last": "7d",
  "body": {
    "steps": [
      { "kind": "page", "path": "/" },
      { "kind": "page", "path": "/pricing", "label": "Pricing" }
    ]
  }
}

{
  "data": {
    "unit": "sessions",
    "windowSeconds": null,
    "steps": [
      { "step": 1, "label": null, "condition": { "kind": "page", "path": "/" }, "count": 95, "conversion": 100, "dropoff": null, "median_seconds": null },
      { "step": 2, "label": "Pricing", "condition": { "kind": "page", "path": "/pricing" }, "count": 24, "conversion": 25.263157894736842, "dropoff": 74.73684210526316, "median_seconds": 108.122 }
    ]
  },
  "meta": { "window": { "from": "2026-10-20T20:31:17.841Z", "to": "2026-10-27T20:31:17.841Z", "tz": "UTC", "bucket": "day" } }
}

Annotation bodiesCopy Anchor Link

create_annotation takes the annotation's own fields only: title, startsAt and optionally description, endsAt, color and icon (see its reference). The annotation is always private to the organization's members and shown on this site only.

{
  "siteId": "SITE_ID",
  "body": { "title": "Pricing page redesign", "startsAt": "2026-10-20T09:00:00Z", "color": "blue" }
}

SafetyCopy Anchor Link

• Writes are marked. Every tool carries MCP tool annotations, hints a client can use to ask before it acts:

  Annotation	Meaning here
  readOnlyHint: true	Reads only. Every GET tool, and analyze_funnel, which is a POST that only reads.
  readOnlyHint: false, destructiveHint: false	Adds something and changes nothing that exists (the create and save tools).
  readOnlyHint: false, destructiveHint: true	Changes or deletes something that exists (the update and delete tools).
  openWorldHint: false	On every tool: none reaches anything outside PilotFox.

  Annotations are hints for the client. What a tool may do is decided by the credential's permissions, checked by the REST route on every call.

• create_annotation cannot publish. It has no isPublic and no scope, and refuses them (Input validation error: … Unrecognized key: "isPublic") before anything is stored. The REST route refuses a public or organization-wide annotation from any MCP call as well. So text a model read in a tool result can never reach share links, public-site visitors or the organization's other sites through MCP.

• Nothing beyond goals, funnels and annotations. No tool manages sites, members, API keys, share links, settings or data deletion.

• Give assistants read-only credentials unless they must write, and prefer clients that ask before a write. A model can be steered by text your visitors sent; see Tool results are data, not instructions.

Tool referenceCopy Anchor Link

list_sitesCopy Anchor Link

The sites this credential can see.

• Permission: site:read
• Runs: GET /api/v1/orgs/{orgId}/sites, with orgId set to the credential's organization
• Annotations: readOnlyHint: true, openWorldHint: false

No arguments.

get_siteCopy Anchor Link

One site: name, domain, time zone, settings.

• Permission: analytics:read
• Runs: GET /api/v1/sites/{siteId}
• Annotations: readOnlyHint: true, openWorldHint: false

overviewCopy Anchor Link

Visitors, sessions, pageviews, bounce, duration.

• Permission: analytics:read
• Runs: GET /api/v1/sites/{siteId}/overview
• Annotations: readOnlyHint: true, openWorldHint: false

timeseriesCopy Anchor Link

Metrics per time bucket.

• Permission: analytics:read
• Runs: GET /api/v1/sites/{siteId}/timeseries
• Annotations: readOnlyHint: true, openWorldHint: false

breakdownCopy Anchor Link

Top values of one dimension.

• Permission: analytics:read
• Runs: GET /api/v1/sites/{siteId}/breakdown
• Annotations: readOnlyHint: true, openWorldHint: false

pagesCopy Anchor Link

Pages with entries, exits, bounce and time on page.

• Permission: analytics:read
• Runs: GET /api/v1/sites/{siteId}/pages
• Annotations: readOnlyHint: true, openWorldHint: false

liveCopy Anchor Link

Visitors right now, top pages, referrers, countries.

• Permission: analytics:read
• Runs: GET /api/v1/sites/{siteId}/live
• Annotations: readOnlyHint: true, openWorldHint: false

geo_countriesCopy Anchor Link

Visitors per country.

• Permission: analytics:read
• Runs: GET /api/v1/sites/{siteId}/geo/countries
• Annotations: readOnlyHint: true, openWorldHint: false

geo_pointsCopy Anchor Link

Visitors binned on a map grid.

• Permission: analytics:read
• Runs: GET /api/v1/sites/{siteId}/geo/points
• Annotations: readOnlyHint: true, openWorldHint: false

eventsCopy Anchor Link

The raw event list, newest first.

• Permission: sessions:read
• Runs: GET /api/v1/sites/{siteId}/events
• Annotations: readOnlyHint: true, openWorldHint: false

event_namesCopy Anchor Link

Custom event names with counts.

• Permission: analytics:read
• Runs: GET /api/v1/sites/{siteId}/events/names
• Annotations: readOnlyHint: true, openWorldHint: false

errorsCopy Anchor Link

JavaScript errors grouped by fingerprint.

• Permission: analytics:read
• Runs: GET /api/v1/sites/{siteId}/errors
• Annotations: readOnlyHint: true, openWorldHint: false

vitalsCopy Anchor Link

Core Web Vitals percentiles.

• Permission: analytics:read
• Runs: GET /api/v1/sites/{siteId}/vitals
• Annotations: readOnlyHint: true, openWorldHint: false

sessionsCopy Anchor Link

Sessions, newest first.

• Permission: sessions:read
• Runs: GET /api/v1/sites/{siteId}/sessions
• Annotations: readOnlyHint: true, openWorldHint: false

sessionCopy Anchor Link

One session with its events.

• Permission: sessions:read
• Runs: GET /api/v1/sites/{siteId}/sessions/{sessionId}
• Annotations: readOnlyHint: true, openWorldHint: false

usersCopy Anchor Link

Visitors and identified users.

• Permission: users:read
• Runs: GET /api/v1/sites/{siteId}/users
• Annotations: readOnlyHint: true, openWorldHint: false

userCopy Anchor Link

One user's profile and traits.

• Permission: users:read
• Runs: GET /api/v1/sites/{siteId}/users/{userId}
• Annotations: readOnlyHint: true, openWorldHint: false

goalsCopy Anchor Link

The site's goals.

• Permission: goals:read
• Runs: GET /api/v1/sites/{siteId}/goals
• Annotations: readOnlyHint: true, openWorldHint: false

create_goalCopy Anchor Link

Creates a goal: {name, condition, icon?}.

• Permission: goals:write
• Runs: POST /api/v1/sites/{siteId}/goals
• Annotations: readOnlyHint: false, destructiveHint: false, openWorldHint: false

update_goalCopy Anchor Link

Updates a goal.

• Permission: goals:write
• Runs: PATCH /api/v1/sites/{siteId}/goals/{id}
• Annotations: readOnlyHint: false, destructiveHint: true, openWorldHint: false

delete_goalCopy Anchor Link

Deletes a goal.

• Permission: goals:write
• Runs: DELETE /api/v1/sites/{siteId}/goals/{id}
• Annotations: readOnlyHint: false, destructiveHint: true, openWorldHint: false

funnelsCopy Anchor Link

The site's saved funnels.

• Permission: funnels:read
• Runs: GET /api/v1/sites/{siteId}/funnels
• Annotations: readOnlyHint: true, openWorldHint: false

analyze_funnelCopy Anchor Link

Conversion through steps: {steps}.

• Permission: funnels:read
• Runs: POST /api/v1/sites/{siteId}/funnels/analyze
• Annotations: readOnlyHint: true, openWorldHint: false

save_funnelCopy Anchor Link

Saves a funnel: {name, steps}.

• Permission: funnels:write
• Runs: POST /api/v1/sites/{siteId}/funnels
• Annotations: readOnlyHint: false, destructiveHint: false, openWorldHint: false

delete_funnelCopy Anchor Link

Deletes a funnel.

• Permission: funnels:write
• Runs: DELETE /api/v1/sites/{siteId}/funnels/{id}
• Annotations: readOnlyHint: false, destructiveHint: true, openWorldHint: false

journeysCopy Anchor Link

The most common page paths.

• Permission: analytics:read
• Runs: GET /api/v1/sites/{siteId}/journeys
• Annotations: readOnlyHint: true, openWorldHint: false

retentionCopy Anchor Link

Cohort retention.

• Permission: analytics:read
• Runs: GET /api/v1/sites/{siteId}/retention
• Annotations: readOnlyHint: true, openWorldHint: false

revenue_summaryCopy Anchor Link

Revenue, payments, refunds, average order and conversion of paying visitors, in one currency.

• Permission: revenue:read
• Runs: GET /api/v1/sites/{siteId}/revenue/summary
• Annotations: readOnlyHint: true, openWorldHint: false

revenue_breakdownCopy Anchor Link

Revenue by one dimension of the paying visit (channel, referrer_domain, utm_source, country…) or affiliate.

• Permission: revenue:read
• Runs: GET /api/v1/sites/{siteId}/revenue/breakdown
• Annotations: readOnlyHint: true, openWorldHint: false

segmentsCopy Anchor Link

Saved segments; pass one's id as segment.

• Permission: segments:read
• Runs: GET /api/v1/sites/{siteId}/segments
• Annotations: readOnlyHint: true, openWorldHint: false

annotationsCopy Anchor Link

Chart annotations.

• Permission: analytics:read
• Runs: GET /api/v1/sites/{siteId}/annotations
• Annotations: readOnlyHint: true, openWorldHint: false

create_annotationCopy Anchor Link

Creates a private annotation on this site's charts: {title, startsAt, description?, endsAt?, color?, icon?}.

• Permission: annotations:write
• Runs: POST /api/v1/sites/{siteId}/annotations
• Annotations: readOnlyHint: false, destructiveHint: false, openWorldHint: false