MCP Tool Reference

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.

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.

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

// 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`).

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.

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.

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.

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({})

Use list-extractions-schema before building advanced where, select, orderBy, or pagination requests in strict clients.

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 })

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

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.

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.

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.

Recommended workflow for GraphQL:

list-types() — discover available types
find-fields({ typeName }) — discover fields for a type
build-query({ typeName, fields, limit }) — generate query string
run-query({ query }) — execute and get results

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

Recommended Workflows

Customer Feedback Analysis

Get recent calls: search-calls({ limit: 20 })
Pull signals by topic: search-signals({ phrase: 'API integration', type: 'featureRequest', limit: 30 })
Get full call context: get-call({ id: <id>, signalLimit: 50 })
Read transcript for quotes: get-call-transcript({ id: <id> })
Find relevant docs: search-documents({ phrase: 'integration', includeContent: false })

Customer Profile Lookup

Find person: search-people({ phrase: 'carol@company.com' })
Get their signals: search-signals({ phrase: 'customer name', limit: 20 })
Get enrichment data: search-people-properties({ phrase: 'company name' })

Advanced Custom Query

Discover types: list-types()
Explore fields: find-fields({ typeName: 'extraction' })
Generate query: build-query({ typeName: 'extraction', fields: ['id', 'name', 'sentiment', 'severity'], limit: 10 })
Execute query: run-query({ query: '<output from build-query>' })

Knowledge Base Context

Browse pages: search-knowledge-pages({ query: 'pricing' })
Get full page: get-knowledge-page({ id: 34 })
Find related signals: search-signals({ phrase: 'pricing objection', type: 'objection' })

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.

Last updated March 2026

​MCP Tool Reference

​Key Terminology

​Call Tools

​search-calls

​get-call

​get-call-transcript

​Signal / Extraction Tools

​list-signal-types

​search-signals

​search-extractions

​list-extractions

​list-extractions-schema

​list-extraction-filter-fields

​Product Ops Tools

​Projects and Inbox

​Linear Discovery

​Natural-Language Signal Search

​list-signal-properties

​search-signal-property-values

​People Tools

​search-people

​search-people-properties

​Document Tools

​search-documents

​get-document

​Knowledge Base Tools

​search-knowledge-pages

​get-knowledge-page

​GraphQL Tools

​list-types

​find-fields

​build-query

​run-query

​Recommended Workflows

​Signal Schema Reference

​Tool Status Overview

MCP Tool Reference

Key Terminology

Call Tools

search-calls

get-call

get-call-transcript

Signal / Extraction Tools

list-signal-types

search-signals

search-extractions

list-extractions

list-extractions-schema

list-extraction-filter-fields

Product Ops Tools

Projects and Inbox

Linear Discovery

Natural-Language Signal Search

list-signal-properties

search-signal-property-values

People Tools

search-people

search-people-properties

Document Tools

search-documents

get-document

Knowledge Base Tools

search-knowledge-pages

get-knowledge-page

GraphQL Tools

list-types

find-fields

build-query

run-query

Recommended Workflows

Signal Schema Reference

Tool Status Overview