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.
MCP Tool Reference The BuildBetter MCP server exposes 21 tools that give AI agents structured access to your calls, signals, people, documents, knowledge base, and raw GraphQL. This page documents every tool.
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.
search-calls Search for calls by optional phrase and/or date range. Without a phrase, returns the most recent calls.
Parameter Type Required Description phrasestring No Matches against call name/title. Does not search transcript content. fromDateISO string No Lower bound timestamp (e.g. 2026-01-01T00:00:00Z). toDateISO string No Upper bound timestamp. limitinteger 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 idinteger Yes Call ID (from search-calls). signalLimitinteger 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 idinteger 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.
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 phrasestring No Searches signal summaries and content. typestring No Filter by signal type name (e.g. featureRequest, bug, complaint). callIdinteger No Restrict results to signals from one specific call. personaIdsinteger[] No Filter by persona IDs. limitinteger 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 })
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 })
Structured list endpoint for extractions with full filter, select, order, and pagination support.
Parameter Type Required Description whereobject No Hasura-style filter object. selectstring[] No Fields to include. Defaults to all standard fields. orderByarray[] No Sort order. Default: [['date', 'desc']]. pageinteger No Page number for pagination. Default: 1. limitinteger 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'] })
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 })
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 phrasestring No Search across taxonomy display values. propertyNamestring No Filter by property name (e.g. 'Product Taxonomy'). propertySlugstring No Filter by property slug (e.g. 'product-taxonomy'). signalIdinteger No Get all property values for one specific signal. callIdinteger No Restrict to signals from one call. limitinteger No Max results. Default: 20.
search-signal-property-values({ phrase: 'dashboard', limit: 10 })
search-people Search for person records by name, email, title, or department. Optionally filter by persona ID.
Parameter Type Required Description phrasestring Yes Search term (name, email, title, department). personaIdsinteger[] No Filter by persona IDs. limitinteger 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 phrasestring Yes Search term across all property values. limitinteger No Max results. Default: 20.
search-people-properties({ phrase: 'enterprise', limit: 5 })
search-documents Search AI-generated documents by phrase. Can optionally include full document content in results.
Parameter Type Required Description phrasestring Yes Search term across document name, content, and instructions. includeContentboolean No If true, returns full markdown content. Default: false. sourcestring No Filter by source (e.g. 'ai_generated', 'notion_import'). statusstring No Filter by status (e.g. 'completed', 'processing'). limitinteger 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 idinteger Yes Document ID (from search-documents).
get-document({ id: 2872 })
search-knowledge-pages Search the internal knowledge base (wiki-style pages) by title or content.
Parameter Type Required Description querystring Yes Search query. Use short 1–2 word terms for best results. limitinteger 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 idinteger Yes Page ID (from search-knowledge-pages).
get-knowledge-page({ id: 34 })
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.
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 typeNamestring 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 typeNamestring Yes GraphQL type to query. fieldsstring[] Yes Fields to include in the query. limitinteger No Record limit to embed in the query. filterobject 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 querystring Yes Valid GraphQL query string. variablesobject No GraphQL variables object.
Recommended workflow for GraphQL:
list-types() — discover available typesfind-fields({ typeName }) — discover fields for a typebuild-query({ typeName, fields, limit }) — generate query stringrun-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 })
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' })
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>' })
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 idstring Unique signal ID. namestring Short title of the signal (AI-generated). summarystring 1–2 sentence summary of the insight. contextstring Additional context explaining why this was extracted. dateISO timestamp When the source content was created. sentimentinteger Sentiment score: -10 (very negative) to +10 (very positive). severityinteger Severity score: 0 (low) to 10 (critical). biasinteger 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. personobject Person who generated the signal: id, firstName, lastName, email, avatarUrl. person.companyobject Company linked to the person (may be null). person.personaobject Persona of the person (may be null). dataobject Source data reference: id, type (conversation/interview), source (github/zoom/slack/etc).
Tool Status Notes search-callsWorking Phrase matches names only, not content. get-callWorking Rich: summary, attendees, signals, tags, source. get-call-transcriptWorking Full speaker-attributed transcript with timestamps. list-signal-typesWorking Returns all 35 configured signal types. search-signalsWorking Preferred for content searches. search-extractionsWorking Alias of search-signals. list-extractionsWorking Nested where filters on types may be ignored. list-extraction-filter-fieldsWorking Returns all CRM/integration metadata fields. list-signal-propertiesWorking Returns workspace-level property definitions. search-signal-property-valuesWorking Returns taxonomy-tagged values per signal. search-peopleWorking Returns person records with persona, email, source, company. search-people-propertiesWorking Returns CRM enrichment (job history, skills, etc). search-documentsWorking Searches name + content. Supports source and status filters. get-documentWorking Returns full markdown content + metadata. search-knowledge-pagesWorking Keyword-sensitive — short queries work best. get-knowledge-pageWorking Returns full content + child page IDs. list-typesWorking Returns ~700 GraphQL types in the schema. find-fieldsWorking Returns all fields + types for any GraphQL type. build-queryWorking Generates a valid GraphQL query string — does not execute it. run-queryWorking Executes raw read-only GraphQL. Returns live data.
