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

# Tool reference

> Reference for the tools exposed by the Weavable MCP server

The Weavable MCP server exposes three tools. All tools require an authenticated session — see [Connect a client](/mcp/connect) for setup.

The typical workflow is:

1. Call **`list-contexts`** to discover what's available and to obtain `contextId`s and `insightId`s.
2. Call **`context-summary`** with a `contextId`, a natural-language `query`, and a time range to generate a written summary.
3. Call **`context-insight`** with a `contextId` and an `insightId` from step 1 to generate a markdown insight (chart/table/visualization rendered as markdown).

***

## list-contexts

Lists all contexts accessible by the authenticated user. Each entry describes the context's data sources and the insight IDs that are compatible with it.

### Parameters

*None.*

### Returns

A JSON array of context objects:

| Field                | Type                  | Description                                                                                                         |
| -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `id`                 | string                | Context ID. Pass to `context-summary` and `context-insight`.                                                        |
| `title`              | string                | Human-readable context title.                                                                                       |
| `created`            | string (ISO datetime) | When the context was created.                                                                                       |
| `updated`            | string (ISO datetime) | When the context was last updated.                                                                                  |
| `dataSources`        | array                 | Data sources backing the context. Each item has `app` (e.g. `"GitHub"`), `name`, and an optional `type`.            |
| `compatibleInsights` | array                 | Insights that can be generated against this context. Each item has `id` and `name`. Pass `id` to `context-insight`. |

Contexts with no data sources are omitted. Results are sorted by most recently created first.

### Example

```json theme={null}
[
  {
    "id": "ctx_01HXYZ...",
    "title": "Engineering weekly",
    "created": "2026-04-21T10:14:00.000Z",
    "updated": "2026-05-06T08:02:11.000Z",
    "dataSources": [
      { "app": "GitHub", "name": "weavable/api", "type": "Repository" },
      { "app": "Linear", "name": "Backend", "type": "Team" }
    ],
    "compatibleInsights": [
      { "id": "insight_pr_throughput", "name": "PR throughput" },
      { "id": "insight_issue_burndown", "name": "Issue burndown" }
    ]
  }
]
```

***

## context-summary

Generates a written summary from a context using a natural-language query and a time range.

### Parameters

| Name        | Type   | Required | Description                                                                        |
| ----------- | ------ | -------- | ---------------------------------------------------------------------------------- |
| `contextId` | string | yes      | The ID of the context to summarize, from `list-contexts`.                          |
| `query`     | string | yes      | The question, summarization instruction, or prompt.                                |
| `fromDate`  | string | yes      | Start of time range. ISO date (`2025-02-25`) or datetime (`2025-02-25T00:00:00Z`). |
| `toDate`    | string | no       | End of time range, same format as `fromDate`. Defaults to now.                     |
| `timeZone`  | string | no       | IANA timezone (e.g. `America/New_York`). Defaults to UTC.                          |

### Returns

Markdown text containing the generated summary. While the summary is being generated, the server emits MCP `notifications/progress` events (rendered by the client as a running word count) so the UI stays responsive during long generations.

If the request fails, the response is returned with `isError: true` and the text contains a human-readable error message.

### Example

Request:

```json theme={null}
{
  "contextId": "ctx_01HXYZ...",
  "query": "Summarise PRs merged and notable issues opened",
  "fromDate": "2026-04-30",
  "toDate": "2026-05-07",
  "timeZone": "America/New_York"
}
```

Response (text content, truncated):

```markdown theme={null}
## Engineering weekly — Apr 30 to May 7

**PRs merged (12)**
- Auth: migrated session token storage to satisfy compliance review …
- Frontend: reworked the canvas share modal …

**Notable issues opened (3)**
- P0: webhook retries timing out for Slack connector …
```

***

## context-insight

Generates a markdown insight (chart, table, or other visualization rendered as markdown) for a context using a given insight ID. Only `insightId`s returned by `list-contexts` for that context are valid.

### Parameters

| Name        | Type   | Required | Description                                                                                |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `contextId` | string | yes      | The ID of the context.                                                                     |
| `insightId` | string | yes      | The ID of the insight to generate, from the `compatibleInsights` array on `list-contexts`. |

### Returns

Markdown text with the rendered insight, prefixed with the insight title as an `## H2` heading.

If the context cannot be found or the user lacks access, the response text is `"Context not found or access denied"`. If the insight isn't compatible with the context, the response explains that and points back to `list-contexts`.

### Example

Request:

```json theme={null}
{
  "contextId": "ctx_01HXYZ...",
  "insightId": "insight_pr_throughput"
}
```

Response (text content, truncated):

```markdown theme={null}
## PR throughput

| Week         | Opened | Merged | Median time to merge |
| ------------ | ------ | ------ | -------------------- |
| 2026-04-21   | 18     | 14     | 1d 4h                |
| 2026-04-28   | 22     | 19     | 0d 21h               |
```