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

# Tool Reference

> Complete reference for BuildBetter MCP tools — parameters, usage examples, and tips

# MCP Tool Reference

<Info>
  The BuildBetter MCP server exposes tools that give AI agents structured access to your calls, signals, people, documents, knowledge base, product-ops workflows, and raw GraphQL. This page documents the core tool families and usage patterns.
</Info>

## Key Terminology

| Term                    | Definition                                                                                                            |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Signal / Extraction** | An AI-extracted insight from a call, conversation, or document (e.g. a bug, feature request, complaint, testimonial). |
| **Interview**           | BuildBetter's internal term for a call or recording.                                                                  |
| **Persona**             | A user segment label (e.g. Team Member, Customer, Enterprise).                                                        |
| **Knowledge Page**      | A markdown wiki page in the BuildBetter knowledge base.                                                               |

***

## Call Tools

### search-calls

Search for calls by optional phrase and/or date range. Without a phrase, returns the most recent calls.

| Parameter  | Type       | Required | Description                                                              |
| ---------- | ---------- | -------- | ------------------------------------------------------------------------ |
| `phrase`   | string     | No       | Matches against call name/title. Does **not** search transcript content. |
| `fromDate` | ISO string | No       | Lower bound timestamp (e.g. `2026-01-01T00:00:00Z`).                     |
| `toDate`   | ISO string | No       | Upper bound timestamp.                                                   |
| `limit`    | integer    | No       | Max results. Default: 20.                                                |

<Warning>
  `phrase` only matches call names/titles — not transcript content. To search what was discussed inside calls, use `search-signals` or `search-extractions` instead.
</Warning>

```
// Get recent calls
search-calls({ limit: 10 })

// Find calls in a date range
search-calls({ fromDate: "2026-01-01T00:00:00Z", toDate: "2026-03-01T00:00:00Z", limit: 20 })
```

***

### get-call

Get full details for a single call including summary, attendees, tags, and a sample of signals.

| Parameter     | Type    | Required | Description                               |
| ------------- | ------- | -------- | ----------------------------------------- |
| `id`          | integer | Yes      | Call ID (from `search-calls`).            |
| `signalLimit` | integer | No       | How many signals to include. Default: 20. |

```
get-call({ id: 20784, signalLimit: 10 })
```

***

### get-call-transcript

Returns the full speaker-attributed transcript for a call, broken into monologue segments with start/end timestamps.

| Parameter | Type    | Required | Description                    |
| --------- | ------- | -------- | ------------------------------ |
| `id`      | integer | Yes      | Call ID (from `search-calls`). |

<Tip>
  Check `hasTranscript` in the response before trying to render or search the transcript. Use `startSec` to build deep-link URLs to specific moments in the call.
</Tip>

***

## Signal / Extraction Tools

Signals are the core data object in BuildBetter — AI-extracted insights from any ingested content. They have types, topics, keywords, sentiment, severity, bias scores, and person/company linkage.

### list-signal-types

Returns all configured signal (extraction) types.

```
list-signal-types({ limit: 100 })

// Returns 35 types including:
// achievement, actionItem, blockers, bug, challenge, change, competition,
// complaint, compliment, concern, confusion, customerInsight, decision,
// dependency, discovery, feature, featureRequest, feedback, idea, improvement,
// inquiry, interest, issue, milestone, objection, observation, opportunity,
// priority, question, risk, strategic, strategy, suggestion, testimonial, update
```

***

### search-signals

Search signals by phrase and optionally filter by type, call, or persona. This is the **preferred tool for content searches** — use it instead of searching calls.

| Parameter    | Type       | Required | Description                                                             |
| ------------ | ---------- | -------- | ----------------------------------------------------------------------- |
| `phrase`     | string     | No       | Searches signal summaries and content.                                  |
| `type`       | string     | No       | Filter by signal type name (e.g. `featureRequest`, `bug`, `complaint`). |
| `callId`     | integer    | No       | Restrict results to signals from one specific call.                     |
| `personaIds` | integer\[] | No       | Filter by persona IDs.                                                  |
| `limit`      | integer    | No       | Max results. Default: 20.                                               |

```
// Search all signals mentioning 'churn'
search-signals({ phrase: 'churn', limit: 10 })

// Only feature requests mentioning 'API'
search-signals({ phrase: 'API', type: 'featureRequest', limit: 20 })

// All signals from a specific call
search-signals({ callId: 20784, limit: 50 })
```

***

### search-extractions

Identical parameters to `search-signals`. Use this as a reliable alternative if `search-signals` encounters a loading issue.

```
search-extractions({ phrase: 'pricing objection', type: 'objection', limit: 10 })
```

***

### list-extractions

Structured list endpoint for extractions with full filter, select, order, and pagination support.

| Parameter | Type      | Required | Description                                         |
| --------- | --------- | -------- | --------------------------------------------------- |
| `where`   | object    | No       | Hasura-style filter object.                         |
| `select`  | string\[] | No       | Fields to include. Defaults to all standard fields. |
| `orderBy` | array\[]  | No       | Sort order. Default: `[['date', 'desc']]`.          |
| `page`    | integer   | No       | Page number for pagination. Default: 1.             |
| `limit`   | integer   | No       | Results per page. Default: 20.                      |

<Warning>
  Nested relationship filters (e.g. filtering by type name) may be ignored. Use `search-signals` or `search-extractions` with the `type` parameter for type-based filtering instead.
</Warning>

```
list-extractions({
  limit: 20,
  page: 1,
  orderBy: [['severity', 'desc']],
  select: ['id', 'name', 'summary', 'severity', 'date']
})
```

### list-extractions-schema

Returns the expected input schema for `list-extractions`. Use this when an MCP client validates tool calls strictly or needs to construct a valid filter request before calling `list-extractions`.

```
list-extractions-schema({})
```

<Tip>
  Use `list-extractions-schema` before building advanced `where`, `select`, `orderBy`, or pagination requests in strict clients.
</Tip>

***

### list-extraction-filter-fields

Returns all metadata fields available from connected integrations (Salesforce, Pendo, HubSpot, etc.) that can be used to filter signals.

```
list-extraction-filter-fields({ limit: 100, page: 1 })
```

## Product Ops Tools

BuildBetter MCP also exposes product-ops tools for Projects Hub, Inbox, folders, and Linear. Exact availability depends on your workspace permissions and the MCP client.

### Projects and Inbox

Use product-ops tools to:

* View projects and project details
* Review Inbox items and backlog counts
* Inspect project or Inbox evidence
* Open folder details related to product work
* Promote approved Inbox items into projects when the client supports approval-based actions

### Linear Discovery

Linear tools help discover issues that may belong in Projects Hub. Assistants can search for candidate tickets, summarize why they matter, and prepare selected tickets for approval-based promotion.

### Natural-Language Signal Search

Signed-in users can search signals with natural-language queries, not only structured filters. Use this for prompts like:

```
search-signals({ phrase: "enterprise onboarding complaints from the last month", limit: 20 })
```

When you need exact filtering or pagination, use `list-extractions` with the schema helper.

***

### list-signal-properties

Returns custom properties configured for the signal/extraction entity type. These are workspace-level schema definitions, not signal values.

***

### search-signal-property-values

Search the actual taxonomy/property values that have been auto-filled onto signals. Useful for finding signals tagged with specific taxonomy nodes.

| Parameter      | Type    | Required | Description                                          |
| -------------- | ------- | -------- | ---------------------------------------------------- |
| `phrase`       | string  | No       | Search across taxonomy display values.               |
| `propertyName` | string  | No       | Filter by property name (e.g. `'Product Taxonomy'`). |
| `propertySlug` | string  | No       | Filter by property slug (e.g. `'product-taxonomy'`). |
| `signalId`     | integer | No       | Get all property values for one specific signal.     |
| `callId`       | integer | No       | Restrict to signals from one call.                   |
| `limit`        | integer | No       | Max results. Default: 20.                            |

```
search-signal-property-values({ phrase: 'dashboard', limit: 10 })
```

***

## People Tools

### search-people

Search for person records by name, email, title, or department. Optionally filter by persona ID.

| Parameter    | Type       | Required | Description                                   |
| ------------ | ---------- | -------- | --------------------------------------------- |
| `phrase`     | string     | Yes      | Search term (name, email, title, department). |
| `personaIds` | integer\[] | No       | Filter by persona IDs.                        |
| `limit`      | integer    | No       | Max results. Default: 20.                     |

```
search-people({ phrase: 'morgan', limit: 5 })
```

<Note>
  The same person may appear multiple times if they exist in multiple integration sources (e.g. BuildBetter + GitHub + Salesforce).
</Note>

***

### search-people-properties

Search CRM-enriched person property values. Returns job history, skills, titles, and other enrichment data linked to person records.

| Parameter | Type    | Required | Description                             |
| --------- | ------- | -------- | --------------------------------------- |
| `phrase`  | string  | Yes      | Search term across all property values. |
| `limit`   | integer | No       | Max results. Default: 20.               |

```
search-people-properties({ phrase: 'enterprise', limit: 5 })
```

***

## Document Tools

### search-documents

Search AI-generated documents by phrase. Can optionally include full document content in results.

| Parameter        | Type    | Required | Description                                                  |
| ---------------- | ------- | -------- | ------------------------------------------------------------ |
| `phrase`         | string  | Yes      | Search term across document name, content, and instructions. |
| `includeContent` | boolean | No       | If true, returns full markdown content. Default: false.      |
| `source`         | string  | No       | Filter by source (e.g. `'ai_generated'`, `'notion_import'`). |
| `status`         | string  | No       | Filter by status (e.g. `'completed'`, `'processing'`).       |
| `limit`          | integer | No       | Max results. Default: 20.                                    |

```
// Search without content (fast)
search-documents({ phrase: 'onboarding', limit: 10 })

// Include full content (slower, larger response)
search-documents({ phrase: 'brex', includeContent: true, limit: 5 })
```

***

### get-document

Fetch a single document by ID, including its full markdown content.

| Parameter | Type    | Required | Description                            |
| --------- | ------- | -------- | -------------------------------------- |
| `id`      | integer | Yes      | Document ID (from `search-documents`). |

```
get-document({ id: 2872 })
```

***

## Knowledge Base Tools

### search-knowledge-pages

Search the internal knowledge base (wiki-style pages) by title or content.

| Parameter | Type    | Required | Description                                              |
| --------- | ------- | -------- | -------------------------------------------------------- |
| `query`   | string  | Yes      | Search query. Use short 1–2 word terms for best results. |
| `limit`   | integer | No       | Max results. Default: 20.                                |

<Warning>
  This tool uses keyword matching, not semantic search. Short, broad queries work best (e.g. `'pricing'`, `'workflows'`). Long phrases may return 0 results — try a single-word subset instead.
</Warning>

```
search-knowledge-pages({ query: 'pricing', limit: 5 })
```

***

### get-knowledge-page

Fetch a single knowledge page by ID with full plain-text content and any child page references.

| Parameter | Type    | Required | Description                              |
| --------- | ------- | -------- | ---------------------------------------- |
| `id`      | integer | Yes      | Page ID (from `search-knowledge-pages`). |

```
get-knowledge-page({ id: 34 })
```

***

## GraphQL Tools

For advanced queries not covered by the domain-specific tools above. The schema exposes \~700 types covering the full BuildBetter data model.

### list-types

Returns all available GraphQL object types in the current authenticated context. Useful for discovering what data is queryable.

```
list-types()
```

***

### find-fields

Returns all field names and their types for a specific GraphQL type. Use this before `build-query` or `run-query` to know what fields are available.

| Parameter  | Type   | Required | Description                            |
| ---------- | ------ | -------- | -------------------------------------- |
| `typeName` | string | Yes      | GraphQL type name (from `list-types`). |

```
find-fields({ typeName: 'interview' })
```

***

### build-query

Generates a valid Hasura-style GraphQL query string for a given type and set of fields. Does **not** execute the query — pass the output to `run-query`.

| Parameter  | Type      | Required | Description                         |
| ---------- | --------- | -------- | ----------------------------------- |
| `typeName` | string    | Yes      | GraphQL type to query.              |
| `fields`   | string\[] | Yes      | Fields to include in the query.     |
| `limit`    | integer   | No       | Record limit to embed in the query. |
| `filter`   | object    | No       | Hasura `where` clause to embed.     |

```
build-query({
  typeName: 'interview',
  fields: ['id', 'name', 'recorded_at', 'summary_state', 'source'],
  limit: 10
})
```

***

### run-query

Executes a raw, read-only GraphQL query against the BuildBetter schema. This is the most powerful and flexible tool — use it when domain tools don't cover your use case.

| Parameter   | Type   | Required | Description                 |
| ----------- | ------ | -------- | --------------------------- |
| `query`     | string | Yes      | Valid GraphQL query string. |
| `variables` | object | No       | GraphQL variables object.   |

<Tip>
  **Recommended workflow for GraphQL:**

  1. `list-types()` — discover available types
  2. `find-fields({ typeName })` — discover fields for a type
  3. `build-query({ typeName, fields, limit })` — generate query string
  4. `run-query({ query })` — execute and get results
</Tip>

```
run-query({
  query: `query GetRecentCalls {
    interview(limit: 5, order_by: {recorded_at: desc}) {
      id
      name
      recorded_at
      summary_state
      source
    }
  }`
})
```

***

## Recommended Workflows

<AccordionGroup>
  <Accordion title="Customer Feedback Analysis" icon="chart-line">
    1. Get recent calls: `search-calls({ limit: 20 })`
    2. Pull signals by topic: `search-signals({ phrase: 'API integration', type: 'featureRequest', limit: 30 })`
    3. Get full call context: `get-call({ id: <id>, signalLimit: 50 })`
    4. Read transcript for quotes: `get-call-transcript({ id: <id> })`
    5. Find relevant docs: `search-documents({ phrase: 'integration', includeContent: false })`
  </Accordion>

  <Accordion title="Customer Profile Lookup" icon="user">
    1. Find person: `search-people({ phrase: 'carol@company.com' })`
    2. Get their signals: `search-signals({ phrase: 'customer name', limit: 20 })`
    3. Get enrichment data: `search-people-properties({ phrase: 'company name' })`
  </Accordion>

  <Accordion title="Advanced Custom Query" icon="code">
    1. Discover types: `list-types()`
    2. Explore fields: `find-fields({ typeName: 'extraction' })`
    3. Generate query: `build-query({ typeName: 'extraction', fields: ['id', 'name', 'sentiment', 'severity'], limit: 10 })`
    4. Execute query: `run-query({ query: '<output from build-query>' })`
  </Accordion>

  <Accordion title="Knowledge Base Context" icon="book">
    1. Browse pages: `search-knowledge-pages({ query: 'pricing' })`
    2. Get full page: `get-knowledge-page({ id: 34 })`
    3. Find related signals: `search-signals({ phrase: 'pricing objection', type: 'objection' })`
  </Accordion>
</AccordionGroup>

***

## Signal Schema Reference

Every signal returned by `search-signals`, `search-extractions`, `get-call`, and `list-extractions` shares this schema:

| Field            | Type          | Description                                                                                     |
| ---------------- | ------------- | ----------------------------------------------------------------------------------------------- |
| `id`             | string        | Unique signal ID.                                                                               |
| `name`           | string        | Short title of the signal (AI-generated).                                                       |
| `summary`        | string        | 1–2 sentence summary of the insight.                                                            |
| `context`        | string        | Additional context explaining why this was extracted.                                           |
| `date`           | ISO timestamp | When the source content was created.                                                            |
| `sentiment`      | integer       | Sentiment score: -10 (very negative) to +10 (very positive).                                    |
| `severity`       | integer       | Severity score: 0 (low) to 10 (critical).                                                       |
| `bias`           | integer       | Bias score: -10 (heavily biased) to 0 (unbiased). Null if not applicable.                       |
| `types[]`        | object\[]     | Signal types (e.g. featureRequest, bug). Each has `id` and `name`.                              |
| `topics[]`       | object\[]     | Topics associated with the signal. Each has `id` and `name`.                                    |
| `keywords[]`     | object\[]     | Keywords extracted from the signal. Each has `id` and `name`.                                   |
| `person`         | object        | Person who generated the signal: `id`, `firstName`, `lastName`, `email`, `avatarUrl`.           |
| `person.company` | object        | Company linked to the person (may be null).                                                     |
| `person.persona` | object        | Persona of the person (may be null).                                                            |
| `data`           | object        | Source data reference: `id`, `type` (conversation/interview), `source` (github/zoom/slack/etc). |

***

## Tool Status Overview

| Tool                            | Status  | Notes                                                         |
| ------------------------------- | ------- | ------------------------------------------------------------- |
| `search-calls`                  | Working | Phrase matches names only, not content.                       |
| `get-call`                      | Working | Rich: summary, attendees, signals, tags, source.              |
| `get-call-transcript`           | Working | Full speaker-attributed transcript with timestamps.           |
| `list-signal-types`             | Working | Returns all 35 configured signal types.                       |
| `search-signals`                | Working | Preferred for content searches.                               |
| `search-extractions`            | Working | Alias of search-signals.                                      |
| `list-extractions`              | Working | Nested `where` filters on types may be ignored.               |
| `list-extraction-filter-fields` | Working | Returns all CRM/integration metadata fields.                  |
| `list-signal-properties`        | Working | Returns workspace-level property definitions.                 |
| `search-signal-property-values` | Working | Returns taxonomy-tagged values per signal.                    |
| `search-people`                 | Working | Returns person records with persona, email, source, company.  |
| `search-people-properties`      | Working | Returns CRM enrichment (job history, skills, etc).            |
| `search-documents`              | Working | Searches name + content. Supports source and status filters.  |
| `get-document`                  | Working | Returns full markdown content + metadata.                     |
| `search-knowledge-pages`        | Working | Keyword-sensitive — short queries work best.                  |
| `get-knowledge-page`            | Working | Returns full content + child page IDs.                        |
| `list-types`                    | Working | Returns \~700 GraphQL types in the schema.                    |
| `find-fields`                   | Working | Returns all fields + types for any GraphQL type.              |
| `build-query`                   | Working | Generates a valid GraphQL query string — does not execute it. |
| `run-query`                     | Working | Executes raw read-only GraphQL. Returns live data.            |

***

<Note>
  Last updated March 2026
</Note>