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

# Atlas capabilities reference

> What users can ask an MCP-compatible assistant to do with Atlas, plus the operation names agents call behind the scenes.

## Overview

Once you've connected Atlas to an MCP client ([setup guide](/docs/mcp/overview)),
you can ask your assistant for civic research help in natural language. The
assistant chooses the matching Atlas operation.

For guided starting points available through some clients, see [Guided research
starters](/docs/mcp/prompts).

Some Atlas responses include a `resource_uri`. Compatible clients can use that
URI to open the same research output later. See [Available resources](/docs/mcp/resources).

<Note>
  Access depends on your plan, OAuth scopes, and workspace. See [Scopes and
  permissions](/docs/mcp/scopes), [Authentication](/docs/api/authentication), and
  [Workspace integration activity](/docs/workspace/integration-activity) when an
  Atlas action is missing or returns a permission error.
</Note>

<Tip>
  Some requests can ask for clarification or confirmation before they continue.
  See [Confirmations and follow-up questions](/docs/mcp/elicitation) for decline,
  cancel, and unsupported-client behavior.
</Tip>

## Find Civic Actors

### search\_entities

Ask for people, organizations, initiatives, campaigns, or events by place,
topic, source type, actor type, or free-text search.

**Parameters:**

| Parameter      | Type      | Description                                                                 |
| -------------- | --------- | --------------------------------------------------------------------------- |
| `place`        | string    | Natural-language place or normalized place key                              |
| `issue_areas`  | string\[] | Issue area slugs to filter by                                               |
| `text`         | string    | Free-text search query                                                      |
| `entity_types` | string\[] | Filter by type: `person`, `organization`, `initiative`, `campaign`, `event` |
| `source_types` | string\[] | Filter by source type                                                       |
| `limit`        | integer   | Max results (default: 20)                                                   |
| `cursor`       | string    | Pagination cursor from a previous response                                  |

**Example requests:**

* "Find labor organizers in Detroit"
* "Search for organizations working on housing affordability in Kansas City"
* "Who's working on climate issues in rural Montana?"

### get\_entity

Open the full Atlas record for a specific actor the assistant has already
found.

**Parameters:**

| Parameter        | Type      | Description                            |
| ---------------- | --------- | -------------------------------------- |
| `entity_id`      | string    | The entity's unique ID                 |
| `relation_types` | string\[] | Optional relationship types to include |
| `limit`          | integer   | Max results (default: 20)              |

**Example requests:**

* "Tell me more about that first organization"
* "Get the full details for Prairie Workers Cooperative"

### get\_entity\_sources

Review the public sources behind a specific Atlas actor.

**Parameters:**

| Parameter   | Type    | Description                                |
| ----------- | ------- | ------------------------------------------ |
| `entity_id` | string  | The entity's unique ID                     |
| `limit`     | integer | Max results (default: 20)                  |
| `cursor`    | string  | Pagination cursor from a previous response |

**Example requests:**

* "What are the sources for KC Tenants?"
* "Show me where this information came from"

### get\_related\_entities

Explore other actors connected through Atlas relationships.

**Parameters:**

| Parameter   | Type    | Description                                |
| ----------- | ------- | ------------------------------------------ |
| `entity_id` | string  | The entity's unique ID                     |
| `limit`     | integer | Max results (default: 20)                  |
| `cursor`    | string  | Pagination cursor from a previous response |

**Example requests:**

* "Who else is connected to this organization?"
* "What other entities are related to Maria Gonzalez?"

## Verify Sources

### search\_sources

Search the public sources Atlas has indexed.

**Parameters:**

| Parameter      | Type      | Description                                                                       |
| -------------- | --------- | --------------------------------------------------------------------------------- |
| `place`        | string    | Place filter, such as `Kansas City, MO`                                           |
| `issue_areas`  | string\[] | Issue area slugs to filter by                                                     |
| `text`         | string    | Free-text search query                                                            |
| `source_types` | string\[] | Filter by type: `journalism`, `nonprofit_listing`, `organizational_website`, etc. |
| `limit`        | integer   | Max results (default: 20)                                                         |
| `cursor`       | string    | Pagination cursor from a previous response                                        |

**Example requests:**

* "Find news articles about tenant organizing in Kansas City"
* "Search for nonprofit listings related to environmental justice"

## Understand A Place

### get\_place\_entities

Find actors tied to a specific place.

**Parameters:**

| Parameter      | Type      | Description                                    |
| -------------- | --------- | ---------------------------------------------- |
| `place`        | string    | Natural-language place or normalized place key |
| `issue_areas`  | string\[] | Issue area slugs to filter by                  |
| `text`         | string    | Free-text search query                         |
| `entity_types` | string\[] | Entity types to include                        |
| `source_types` | string\[] | Source types to include                        |
| `limit`        | integer   | Max results                                    |
| `cursor`       | string    | Pagination cursor from a previous response     |

**Example requests:**

* "What civic organizations are active in Boise, Idaho?"
* "Show me all entities in Kansas City working on housing"

### get\_place\_profile

Get demographic and socioeconomic context for a place.

**Parameters:**

| Parameter | Type   | Description                                    |
| --------- | ------ | ---------------------------------------------- |
| `place`   | string | Natural-language place or normalized place key |

**Example requests:**

* "What's the demographic profile of Garden City, Kansas?"
* "Tell me about the socioeconomic context of this city"

### get\_place\_coverage

Compare where Atlas coverage is strong, thin, or uneven for a place.

**Parameters:**

| Parameter     | Type      | Description                                             |
| ------------- | --------- | ------------------------------------------------------- |
| `place`       | string    | Natural-language place or normalized place key          |
| `issue_areas` | string\[] | Optional issue area slugs to focus the coverage summary |

**Example requests:**

* "What issue areas are underrepresented in Kansas City?"
* "Where are the coverage gaps in Boise?"
* "Which issues have the most entities in Detroit?"

### get\_place\_issue\_signals

Summarize issue-area signals for a place, with example actors where available.

**Parameters:**

| Parameter                | Type      | Description                                       |
| ------------------------ | --------- | ------------------------------------------------- |
| `place`                  | string    | Natural-language place or normalized place key    |
| `issue_areas`            | string\[] | Optional issue area slugs to include              |
| `top_entities_per_issue` | integer   | Number of example entities per issue (default: 5) |

**Example requests:**

* "What are the main civic issues in Kansas City?"
* "Give me an issue area breakdown for this city"

## Match Issue Areas

### resolve\_issue\_areas

Translate plain-language topics into Atlas issue-area categories.

**Parameters:**

| Parameter | Type    | Description                             |
| --------- | ------- | --------------------------------------- |
| `text`    | string  | Natural language description of issues  |
| `limit`   | integer | Max issue areas to return (default: 10) |

**Example requests:**

* "What Atlas issue areas relate to affordable childcare?"
* "Map 'clean water' to Atlas categories"
* "What issue areas cover worker rights?"

## Reopen Or Start Research

### list\_discovery\_runs

List source-linked Atlas research runs your workspace can access.

**Parameters:**

| Parameter | Type    | Description                                |
| --------- | ------- | ------------------------------------------ |
| `state`   | string  | Optional state filter, such as `MO`        |
| `status`  | string  | Optional run status filter                 |
| `limit`   | integer | Max runs to return (default: 20)           |
| `cursor`  | string  | Pagination cursor from a previous response |

**Example requests:**

* "Show recent completed research runs in Missouri"
* "What research has Atlas run for this state?"

### get\_discovery\_run

Open one source-linked research run and its structured output.

**Parameters:**

| Parameter | Type   | Description         |
| --------- | ------ | ------------------- |
| `run_id`  | string | The research run ID |

**Example requests:**

* "Open that research run"
* "Summarize the entities and sources from this run"

### start\_discovery\_run

Start a new Atlas research run for a place and issue areas. Unlike read-only
requests, this spends from your workspace research budget and can take minutes
to complete.

Because of that, compatible clients receive a task handle and can check progress
while the run finishes. If your client cannot track long-running work yet, use
the Atlas dashboard to start the run, then ask your assistant to list or open
completed runs later.

Starting a research run requires the `discovery:write` scope, on top of the
`discovery:read` + `api.mcp` access used by read-only Atlas requests. It is
metered against your org's monthly discovery-run budget. See [Scopes and
permissions](/docs/mcp/scopes).

**Parameters:**

| Parameter        | Type      | Description                                     |
| ---------------- | --------- | ----------------------------------------------- |
| `location_query` | string    | Location to research, such as `Kansas City, MO` |
| `state`          | string    | 2-letter state code                             |
| `issue_areas`    | string\[] | Issue area slugs to research                    |
| `research_goal`  | string    | Research focus (default: `landscape_scan`)      |

**Example requests:**

* "Start a new research run for civic organizations in Topeka, Kansas"
* "Research worker cooperatives in Wichita — I don't see much coverage yet"

## Save And Track Work

### save\_entities\_to\_list

Save selected Atlas actors to an existing private workspace list after
confirmation.

**Parameters:**

| Parameter   | Type      | Description                                   |
| ----------- | --------- | --------------------------------------------- |
| `list_id`   | string    | Existing saved-list ID                        |
| `entry_ids` | string\[] | Actor IDs to save                             |
| `note`      | string    | Optional private note for the saved-list item |

**Example requests:**

* "Save these three organizations to my follow-up list"
* "Add the tenant groups from this search to my private list"

### create\_research\_brief

Create a private workspace brief from source-linked Atlas results after
confirmation.

**Parameters:**

| Parameter                  | Type      | Description                                        |
| -------------------------- | --------- | -------------------------------------------------- |
| `title`                    | string    | Brief title                                        |
| `scope`                    | object    | Place, issue, actor, or source scope for the brief |
| `summary`                  | string    | Source-linked summary text                         |
| `linked_entry_ids`         | string\[] | Optional actor IDs to attach                       |
| `linked_source_ids`        | string\[] | Optional source IDs to attach                      |
| `linked_discovery_run_ids` | string\[] | Optional discovery-run IDs to attach               |
| `confidence_summary`       | object    | Optional confidence and review state               |
| `gaps`                     | object\[] | Optional known gaps or unknowns                    |

**Example requests:**

* "Create a private brief from this completed research run"
* "Turn these source-backed results into a workspace brief"

### export\_research\_brief

Export a private workspace brief with its source linkage after confirmation.

**Parameters:**

| Parameter  | Type   | Description                |
| ---------- | ------ | -------------------------- |
| `brief_id` | string | Private workspace brief ID |

**Example requests:**

* "Export this brief with its sources"
* "Give me the structured export for this workspace brief"

### create\_coverage\_target

Create a private workspace coverage target with linked evidence after
confirmation.

**Parameters:**

| Parameter                  | Type      | Description                          |
| -------------------------- | --------- | ------------------------------------ |
| `name`                     | string    | Target name                          |
| `geography`                | string    | Place or region to track             |
| `issue_areas`              | string\[] | Atlas issue-area slugs               |
| `actor_types`              | string\[] | Actor types to include               |
| `source_types`             | string\[] | Source types to review               |
| `linked_discovery_run_ids` | string\[] | Optional discovery-run IDs to attach |
| `linked_entry_ids`         | string\[] | Optional actor IDs to attach         |
| `gaps`                     | object\[] | Optional gap labels and details      |
| `next_actions`             | string\[] | Optional private next-action notes   |

**Example requests:**

* "Create a coverage target for Kansas City tenant organizations from this run"
* "Track this place and issue as a coverage gap for our workspace"

### export\_coverage\_report

Export the active workspace coverage report after confirmation.

**Parameters:** None.

**Example requests:**

* "Export our coverage report"
* "Give me the coverage report with gaps and source counts"

### sync\_scout\_artifacts

Sync reviewed Scout results into the active workspace after confirmation. Synced
runs and entries stay private to the workspace unless a separate review path
makes them public.

**Parameters:**

| Parameter   | Type   | Description                |
| ----------- | ------ | -------------------------- |
| `artifacts` | object | Reviewed Scout run results |

**Example requests:**

* "Sync this reviewed Scout run to our workspace"
* "Import these reviewed Scout results without publishing them"

### watch\_workspace\_resource

Watch an actor or coverage target after confirmation.

**Parameters:**

| Parameter                 | Type   | Description                       |
| ------------------------- | ------ | --------------------------------- |
| `resource_type`           | string | `entry` or `coverage_target`      |
| `resource_id`             | string | Actor or coverage-target ID       |
| `notification_preference` | string | `digest`, `immediate`, or `muted` |

**Example requests:**

* "Watch this organization for new source-backed changes"
* "Add this coverage target to our digest"

## Manage Account Actions

### open\_billing\_settings

Open Atlas account settings after browser consent.

Atlas does not send payment credentials, workspace identity, user identity, or
submitted form content through the MCP client.

**Parameters:** none

**Example requests:**

* "Open Atlas billing settings"
* "Take me to account settings so I can manage my plan"

### open\_api\_key\_settings

Open Atlas account settings for API key management after browser consent.

Atlas never asks for API keys, access tokens, or other credentials through MCP
forms or chat. Create and copy API keys only on the Atlas account page.

**Parameters:** none

**Example requests:**

* "Open API key settings"
* "Take me to Atlas so I can create an API key"

### require\_api\_key\_settings

Require Atlas API-key setup before an agent continues a request that depends on
account-page API-key management.

When setup is still needed, Atlas returns a browser-required response. Your MCP
client should ask before opening the Atlas account page. After the browser
handoff completes, the agent can retry the original request.

Atlas does not send API keys, access tokens, user identity, workspace identity,
or submitted account-page content through the MCP client.

**Parameters:** none

**Example requests:**

* "I need to create an Atlas API key before continuing"
* "Set up API-key access, then retry this"

## Place key format

Atlas uses normalized place keys in the format `city,state` (lowercase, hyphenated):

| Place                 | Key                    |
| --------------------- | ---------------------- |
| Kansas City, Missouri | `kansas-city,missouri` |
| Boise, Idaho          | `boise,idaho`          |
| Garden City, Kansas   | `garden-city,kansas`   |

State-level queries use just the state name: `kansas`, `idaho`, `missouri`.

Most clients handle this normalization. You can say "Kansas City" naturally.

## Related guides

<CardGroup cols={2}>
  <Card title="Research a city" icon="map" href="/docs/mcp/tutorials/research-city">
    Walk through a complete assistant research session.
  </Card>

  <Card title="Scopes and permissions" icon="lock" href="/docs/mcp/scopes">
    See which plans and permissions unlock each capability.
  </Card>

  <Card title="Guided research starters" icon="sparkles" href="/docs/mcp/prompts">
    Start common Atlas research workflows from supported clients.
  </Card>

  <Card title="MCP troubleshooting" icon="wrench" href="/docs/mcp/troubleshooting">
    Resolve connection, consent, and availability issues.
  </Card>

  <Card title="Discovery API guide" icon="terminal" href="/docs/api/guides/discovery">
    Use the same research-run concepts outside MCP.
  </Card>
</CardGroup>