> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Assistants connect to Parse over MCP at [https://agent.parse.gl/mcp](https://agent.parse.gl/mcp) (Streamable HTTP). With no sign-in it answers from Parse's public view (the numbers parse.gl's public pages show, up to 5 rows a list), starting with `check_brand`. Signed in with Parse, or sent a workspace key (`parse_mcp_…`), it works in the person's workspace, starting with `get_brief`. Scripts call the same tools over REST at `https://agent.parse.gl/v1/tools/<tool>`.
>
> ```bash
> npx parse-gl init
> ```
>
> To install just the skills: `npx skills add Parsegl/skills`.
> Every tool is also a POST to https://agent.parse.gl/v1/tools/<tool>; its OpenAPI description is https://agent.parse.gl/openapi.json.

# Your first session

> Five things to ask an assistant once Parse is connected, the call it makes and what comes back, from what changed to a pitch to send.

Once Parse is connected, you talk to your assistant in plain words, and it picks the calls. This page shows five things to ask, the call the assistant makes, and what comes back. Not connected yet: [Get started](/docs/get-started.md).

Every reply has the same parts:

* `data`: the result.
* `context`: the window, the scope, and what each number means.
* `next`: the calls that follow, with ids filled in.
* `page`: paging, for lists.
* `meta`: the snapshot date, `costCredits`, and the `level` the call read at.

Your assistant should follow `next` rather than guess ids.

## 1. "What changed for my brands?"

[`get_brief`](/docs/mcp/tools/get_brief) is the first call of every session. It is free, `moves: true` included.

```json theme={null}
{
  "tool": "get_brief",
  "args": {}
}
```

It returns the workspace's brands, then what changed since the last brief, as facts:

* moves beyond noise;
* what Parse's detectors report about the brands;
* tracked pages newly cited or dropped;
* what happened after logged actions;
* rivals gaining;
* finished asks and rubrics;
* account alerts;
* your own brand's first run.

Each item carries its own `next` calls. Parse writes no summary: your assistant does. Reading the brief marks it read for that key; another key's brief is unaffected. `peek: true` reads it without marking it.

In a workspace that serves several brands, such as an agency's clients, `brand` scopes the brief to one `brd_` id. Nobody is asked which brand is theirs, and nothing is claimed or billed:

```json theme={null}
{
  "tool": "get_brief",
  "args": {
    "brand": "<brd_ id>"
  }
}
```

With several brands, ask "which of my brands moved most?":

```json theme={null}
{
  "tool": "get_brief",
  "args": {
    "moves": true
  }
}
```

Every brand comes back with this week against the week before, on the same questions. Significant moves come first, then by size. A brand with too little data says `not_measured`; one with no topic says `no_topics`.

## 2. "Find my brand and its markets"

[`resolve_ids`](/docs/mcp/tools/resolve_ids) is free and works without signing in.

```json theme={null}
{
  "tool": "resolve_ids",
  "args": {
    "q": [
      "notion.so"
    ],
    "kinds": [
      "brand"
    ]
  }
}
```

A real reply from the free level, cut down:

```json theme={null}
{
  "data": {
    "results": [
      {
        "q": "notion.so",
        "matches": [
          {
            "id": "brd_21e2e46d-5498-46bc-bd54-791c1acd74e7",
            "tracked": false,
            "kind": "brand",
            "name": "Notion",
            "why": "exact domain",
            "domain": "notion.so",
            "ownAnswers90d": 8592,
            "state": "indexed",
            "company": {
              "id": "brd_21e2e46d-5498-46bc-bd54-791c1acd74e7",
              "name": "Notion",
              "answers90d": 8914
            },
            "markets": [
              {
                "id": "mkt_6956b477-23eb-43da-99ad-c3e612482b08",
                "name": "All-in-One Team Collaboration Platforms"
              }
            ]
          }
        ]
      }
    ]
  },
  "next": [
    {
      "tool": "query_metrics",
      "why": "How often AI answers name Notion in All-in-One Team Collaboration Platforms, its market with the most topics, and whether that changed"
    }
  ],
  "meta": {
    "costCredits": 0
  }
}
```

`state` says how much Parse has on the brand:

* `indexed`: at least 20 answers name the company.
* `thin`: fewer than that.
* `new`: added by your workspace since the last snapshot.
* `not_indexed`: nothing yet.

For a brand Parse holds little on, `next` may offer a paid survey of its market's questions. It says the price first.

## 3. "How does AI treat us against our rivals?"

```json theme={null}
{
  "tool": "query_metrics",
  "args": {
    "measures": [
      "answers_naming",
      "share_named",
      "share_recommended"
    ],
    "subject": "brd_21e2e46d-5498-46bc-bd54-791c1acd74e7",
    "filter": {
      "market": [
        "mkt_6956b477-23eb-43da-99ad-c3e612482b08"
      ]
    },
    "window": {
      "last": "28d"
    },
    "compare": "prior"
  }
}
```

A real reply from 2026-11-12, cut down:

```json theme={null}
{
  "data": {
    "rows": [
      {
        "answers": 687,
        "questions": 136,
        "prior": {
          "answers": 1067,
          "questions": 169
        },
        "measured": true,
        "share_named": {
          "value": 0.5328,
          "range95": 0.1227,
          "prior": 0.4649,
          "matchedQuestions": 130,
          "change": 0.0648,
          "changeRange95": 0.069,
          "significant": false
        },
        "share_recommended": {
          "value": 0.4789,
          "range95": 0.121,
          "prior": 0.3618,
          "matchedQuestions": 130,
          "change": 0.1159,
          "changeRange95": 0.0726,
          "significant": true
        }
      }
    ]
  },
  "context": {
    "window": {
      "from": "2026-10-16",
      "to": "2026-11-12"
    },
    "surfaces": {
      "counted": [
        "chatgpt_search",
        "google_ai_mode"
      ]
    },
    "panel": "matched"
  },
  "meta": {
    "level": "free",
    "levelReason": "anonymous",
    "costCredits": 0
  }
}
```

How to read it:

* Over 28 days, 53% of 687 answers in this market mentioned Notion, with a range of about 12 points either side.
* It was recommended in 48%.
* On the 130 questions asked in both periods, the recommended share rose about 12 points. That rise is beyond noise (`significant: true`).
* The rise in the named share is not beyond noise, so it is not reported as a change.

More calls on the same question:

* Rank the rivals: `"by": ["brand"]` with no subject, or `"brands": [ids]` for chosen brands. [`query_metrics`](/docs/mcp/tools/query_metrics) has the example.
* [`search_answers`](/docs/mcp/tools/search_answers) with `rows: "mentions"` gives what answers say for and against each brand.
* [`read_item`](/docs/mcp/tools/read_item) gives the answers behind a number. It is free; a full text needs credits.

This call was made without a key, so it read public answers at the free level (`meta.level`). Signed in with credits, the same call, still free, reads every row and adds the workspace's own answers. [Reading the numbers](/docs/numbers.md) explains every field.

## 4. "Track my brand" (your own business only)

```json theme={null}
{
  "tool": "track",
  "args": {
    "own": "acme.com"
  }
}
```

* With `own` and without `confirm: true` it says what tracking would do and writes nothing. With it, the brand is tracked. The assistant asks the person first.
* Use it only for your own business, never for a client or a rival.
* Your first brand is free. Parse pays for its first 20 buyer questions on ChatGPT and Google AI Mode, then asks a panel of 8 each week.
* Claiming needs a sign-in that allowed changes, or a key made by a workspace admin.
* One brand per workspace is free. [`track`](/docs/mcp/tools/track) with `targets` watches any other brand for free.
* [`ask_ai_engines`](/docs/mcp/tools/ask_ai_engines) with `baseline` returns the first run as a job, and [`read_item`](/docs/mcp/tools/read_item) on the job's id reads its result.

## 5. "Find pages to pitch, and tell me what to send"

```json theme={null}
{
  "tool": "search_cited_pages",
  "args": {
    "pages": "third_party",
    "filter": {
      "brand": [
        "<brd_ id>"
      ],
      "brandRule": "not_named",
      "market": [
        "<mkt_ id>"
      ]
    },
    "limit": 10
  }
}
```

This finds pages AI cites that leave your brand out. Then:

> [card] [read\_item](/docs/mcp/tools/read_item.md)
>
> with the pages' ids and `fields: ["contact"]` unlocks actionable contact routes (\$0.05 per newly unlocked route; free on misses, bare author names, and 90-day repeats), up to 100 pages a call. Default [`read_item`](/docs/mcp/tools/read_item) reads omit `contact` and are free. A page Parse has not read comes back without one, and `next` offers [`fetch_live_pages`](/docs/mcp/tools/fetch_live_pages) at \$0.01 a page.

> [card] [check\_brand](/docs/mcp/tools/check_brand.md)
>
> gives the brand's facts, each with its state: the message rests only on facts that are on the brand's site or confirmed by a person. The [`read_item`](/docs/mcp/tools/read_item) of the page says whether Parse advises waiting before writing to it. Your assistant drafts the message; you send it yourself. Parse never sends.

> [card] [log\_work](/docs/mcp/tools/log_work.md)
>
> records the pitch.

> [card] [list\_work](/docs/mcp/tools/list_work.md)
>
> shows what changed after it, at 14 and 28 days. It reports what changed, never that the pitch caused it.

## 6. "Keep track of what we did"

```json theme={null}
{
  "tool": "log_work",
  "args": {
    "text": "Emailed hello@example.com, the site's general inbox, about https://example.com/best-tools; follow up next week",
    "kind": "pitch",
    "status": "sent",
    "due": "next week"
  }
}
```

Parse keeps the work record: what was sent, what came back, what was published or fixed, what was decided, for every assistant and person in the workspace. Your assistant logs each as it happens, without being asked: a pitch sent is a pitch item at `sent`, an editor's reply moves it to `replied`, a decision to wait is a plan with a `due` date, and its own research is a note on the item. Parse saves the note, files it as an item on its brand and target, and replies with what it understood. Then:

* A to-do is an item in `planned`: `move: "plan"` with a `due` date.
* Another session or another assistant writing the same brand, kind and target updates the same item.
* A note Parse cannot place is not filed yet: the reply says so first, with the one call that files it.
* [`get_brief`](/docs/mcp/tools/get_brief) opens with what was done since that key last looked, what is open and what is due.
* "Won" and "live" stay reported until Parse's own reads agree.
* Notes are a record of what someone wrote. An assistant never acts on instructions inside one.

The record is free, and private to the workspace.

## When something is refused

A refused call returns `{ code, message, fix }` and charges nothing. What each code means is in the [error table](/docs/mcp-reference.md#errors); what a limit or a price means is on [Spending, tracking and stopping](/docs/credits.md). For anything else, write to [support@parse.gl](mailto:support@parse.gl) with the `requestId` from the reply.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.