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

# Tools

> Use this to see what BulkNotion exposes to Claude, and which tools change anything.

Nine tools. **Eight of them only read** — the ninth is the one that runs a bulk
update.

## Reading

| Tool                | What it does                                                                                                               |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `whoami`            | Which account this is, its plan, remaining pages, connected workspaces                                                     |
| `get_credits`       | Remaining pages, plan type, next refill date                                                                               |
| `list_workspaces`   | Your connected Notion workspaces                                                                                           |
| `search_databases`  | Finds a database by name                                                                                                   |
| `describe_database` | The one that matters: what you can filter on, which templates exist, how many pages, how many credits you have — in one go |
| `preview_selection` | How many pages a condition matches, with a few example titles. Changes nothing                                             |
| `list_jobs`         | Your recent runs and their progress                                                                                        |
| `get_job`           | One run's status — used to follow a job to completion                                                                      |

`describe_database` is what lets Claude hold a sensible conversation rather than
interrogating you. Give it a database and it already knows which properties exist,
what values they take, and what templates are available.

## Running

| Tool                | What it does                                              |
| ------------------- | --------------------------------------------------------- |
| `start_bulk_update` | Applies a template to every page in a previewed selection |

<Warning>
  This is the only tool that changes anything. It spends one credit per page.

  By default it **adds** the template to each page and leaves the existing content
  in place — unlike the console, which clears the page first. Ask for clearing
  explicitly if that is what you want, and know that it cannot be undone.

  It will not run from a bare instruction either — it needs a selection you have
  previewed and a count you have been shown. See
  [What to watch for](/mcp/safety).
</Warning>

## How a run actually goes

<Steps>
  <Step title="Claude finds the database">
    `search_databases`, then `describe_database` for the details.
  </Step>

  <Step title="It proposes a condition">
    Built from the properties that actually exist, not guessed.
  </Step>

  <Step title="It previews">
    `preview_selection` returns the count, the credits it will cost, and a few
    example page titles — so you can tell whether it caught what you meant.
  </Step>

  <Step title="You agree">
    Nothing runs before this.
  </Step>

  <Step title="It runs and follows the job">
    `start_bulk_update`, then `get_job` until it finishes.
  </Step>
</Steps>

## Selecting specific pages

Conditions are the way to target a lot of pages. For a specific handful, name them
and Claude will pass those instead — up to 100 that way. Past that, a condition is
both easier and more reliable.

## Next

<CardGroup cols={2}>
  <Card title="What to watch for" icon="shield-exclamation" href="/mcp/safety">
    Credits, irreversibility, and the guards that stop surprises.
  </Card>

  <Card title="Credits and plans" icon="coins" href="/credits">
    What a run costs.
  </Card>
</CardGroup>