Expert Fields Reference

Use this page while creating or editing experts. It explains what each field controls, defaults, and how to choose values.

Basics and Behavior

Field	Required	Default	What It Controls	Recommended Value
Name	Yes	None	Display name in marketplace/cards	Clear role-based name, e.g. `Quarterly Planning Expert`
Description	Yes	None	One-line summary in lists/details	1-2 sentences focused on outcomes
Logo URL	No	Empty	Avatar image shown in UI	Stable HTTPS image URL
About (Markdown)	No	Empty	Long-form detail page content	Scope, examples, limits, expected outputs
System Prompt	Yes	None	Core behavior/rules	Role, boundaries, tools, output format
Custom Hiring Message	No	System message	First DM response after hire	One line with a suggested first question
Skills	No	Empty	Reusable packaged behavior/files	Add only for structured reusable workflows
Categories	No	Empty	Marketplace discoverability tags	2-5 specific categories
Primary Model	No	Claude Sonnet 4.6	The AI model that powers this expert. Standard users can pick standard-tier models; admins can also pick premium models (e.g. Claude Opus 4.8, Claude Fable 5, or GPT-5.5).	Leave unset to use the platform default. Choose a lighter model for high-volume simple tasks; a heavier model for deep reasoning.
Reasoning effort	No	Model-dependent	Per-expert override of the reasoning token budget. Enum string: one of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Only honored by reasoning-capable models (currently Claude Sonnet 4.6, the Claude Opus family, Claude Fable 5, and the OpenAI GPT-5.4 / GPT-5.5 models); hidden for all other models (e.g. Claude Haiku 4.5 and the Gemini models).	Start with `medium`. See Reasoning effort for the full value guide.

Configuration

Hives

Hives are Braintrust’s pre-built tool bundles. Always prefer hives over custom MCP servers when a hive exists for the service you need — they are tested, maintained, and handle per-user credential isolation automatically. See the Hives Reference for the full catalog.

Field	Required	Default	What It Controls	Recommended Value
Hives	Usually	Empty	Built-in tool bundles that connect the expert to external services (Google Drive, Sheets, Notion, Jira, etc.)	Start minimal; add only what the expert actually needs
Hive Env Overrides	No	Empty	Shared default values for a hive that apply to all users of this expert (e.g. a default Jira project key, a default database name)	Safe, non-sensitive shared defaults only — never credentials or API keys

MCP Servers

Use custom MCP servers only when no built-in hive covers the service you need. You are responsible for maintaining the endpoint and debugging connection issues.

Field	Required	Default	What It Controls	Recommended Value
MCP Server Name	If MCP used	None	Label for the server shown in the editor	Human-readable integration name
MCP Server URL	If MCP used	None	The custom tool endpoint the expert connects to	Valid `https://` URL
MCP Transport	If MCP used	`sse`	MCP protocol mode used to communicate with the server	Keep `sse` unless the server explicitly requires `streamable_http`
Verify MCP Server	Recommended	Not run	Runs a connectivity and tool discovery check against the URL	Always run before saving — an unverified server fails silently at runtime

Automations (Advanced)

Field	Required	Default	What It Controls	Recommended Value
Automation Type	Yes	`cron` when created as cron	Trigger mode	`cron` for schedules, `calendar` for event-driven
Display Name	Yes	Empty	User-facing automation label	Action-focused and specific
Description	No	Empty	Why/when automation is used	One sentence with clear use case
Execution Prompt	Yes	Empty	Task instructions during trigger execution	Explicit action + output format
Policy Prompt (calendar only)	No	Falls back to agent name + description	Tells the AI how to evaluate each calendar event — which to ignore, which to schedule, and how many minutes before the event to run	Write explicit criteria: which event types to act on, which to ignore, and your preferred lead time. See Triggers for examples.

Access and Visibility

Field	Required	Default	What It Controls	Recommended Value
Expert Email (local part)	Yes (create)	Empty	Unique expert identity	Lowercase, readable, stable (`sales-ops-bot`)
Visibility	Yes	`Private`	Who can discover/hire	Start private, publish after validation
Access List (Manage Access)	Depends	Empty	Who can edit/hire	Minimum required users/domains only

Edit-Only Fields

Field	Required	Default	What It Controls	Recommended Value
Images	No	Empty	Visual examples on expert page	2-4 screenshots of real outputs
Available On	No	Empty	Platform compatibility hints	Only platforms you actively support
Google Drive Folder	No	Empty	Synced knowledge source folder (RAG chunk injection)	See Knowledge Base for how retrieval works

Common Mistakes and Fixes

Mistake	What Happens	Fix
Prompt is too generic	Low-quality/unstable responses	Add explicit role, scope, and output rules
Too many hives initially	Noisy tool behavior and harder debugging	Start with minimal hives, expand later
Broken/incorrect Logo URL	Missing avatar in UI	Use a public HTTPS image URL
MCP URL saved without verify	Runtime tool failures	Verify each MCP server before saving
Automation prompt too vague	Unusable scheduled output	Specify exact output shape and audience
Access too broad	Unintended usage/edit risk	Restrict access list and roles

Validation Rules (Current Product Behavior)

Name: minimum 3 characters; letters/spaces only.
Description: minimum 10 characters.
System Prompt: minimum 10 characters.
Email local part: minimum 3; lowercase letters/numbers/./_/-; no @.
MCP server: name and valid URL required.
Automation template: display name minimum 3; prompt minimum 10; names must be unique.

System Prompt Patterns

A well-structured system prompt is the single biggest factor in expert quality. Use these patterns as a starting point.

Role Definition

Start every prompt with a clear role statement: “You are [ROLE] for [CONTEXT].” This anchors the expert’s behavior.

Boundary Setting

Explicitly state what the expert should not do. This prevents scope creep and hallucinated capabilities.

Tool Usage Instructions

Tell the expert when to use which tool. Without guidance, experts may use tools unnecessarily or miss tools they should use.

Output Format Specification

Define the expected format, length, and structure of responses. Be specific — “a bullet list” is better than “a summary.”

Uncertainty Handling

Tell the expert what to do when it doesn’t know: ask the user, state uncertainty, or skip the question.

Template

You are [ROLE] for [CONTEXT].

**Your job:** [1-2 sentences on primary function]

**What you do NOT do:** [3-5 explicit exclusions]

**Tools available:**
- [Tool name]: use when [condition]
- [Tool name]: use when [condition]

**Output format:** [specify format, length, structure]

**When unsure:** [how to handle uncertainty - ask vs assume vs skip]

Recommended Configurations by Use Case

Q&A / Information Agent

A simple expert that answers questions using a knowledge base.

Field	Recommended Value
Hives	Minimal — Google Drive if using a knowledge base
System Prompt	Strong, focused prompt with clear scope and refusal rules
Skills	Domain knowledge skill if available
Triggers	None — fully interactive
Drive Folder	Connect a curated folder as a RAG knowledge source — see Knowledge Base for how retrieval works and when to pair it with the Google Drive hive

Data Analysis Agent

An expert that pulls data from various sources and produces analysis.

Field	Recommended Value
Hives	Google Sheets, Supabase, NetSuite, or other data hives
System Prompt	Include detailed output format instructions (tables, charts, summaries)
Skills	Analysis templates or report format skills
Triggers	Optional cron for recurring reports

Automated Reporting Agent

An expert that runs on a schedule and delivers reports to a Space or DM.

Field	Recommended Value
Hives	Data source hives (Sheets, NetSuite, Supabase)
System Prompt	Focus on report structure, audience, and delivery format
Triggers	Cron trigger with explicit execution prompt
Execution Prompt	Specify exact data to pull, report format, and where to deliver
Delivery Mode	Space for team reports, DM for individual summaries

Get Started

Work with Experts

Create and Manage Experts

Automate Tasks

Basics and Behavior

Configuration

Hives

MCP Servers

Automations (Advanced)

Access and Visibility

Edit-Only Fields

Common Mistakes and Fixes

Validation Rules (Current Product Behavior)

System Prompt Patterns

Role Definition

Boundary Setting

Tool Usage Instructions

Output Format Specification

Uncertainty Handling

Template

Recommended Configurations by Use Case

Q&A / Information Agent

Data Analysis Agent

Automated Reporting Agent

​Basics and Behavior

​Configuration

​Hives

​MCP Servers

​Automations (Advanced)

​Access and Visibility

​Edit-Only Fields

​Common Mistakes and Fixes

​Validation Rules (Current Product Behavior)

​System Prompt Patterns

​Role Definition

​Boundary Setting

​Tool Usage Instructions

​Output Format Specification

​Uncertainty Handling

​Template

​Recommended Configurations by Use Case

​Q&A / Information Agent

​Data Analysis Agent

​Automated Reporting Agent

Basics and Behavior

Configuration

Hives

MCP Servers

Automations (Advanced)

Access and Visibility

Edit-Only Fields

Common Mistakes and Fixes

Validation Rules (Current Product Behavior)

System Prompt Patterns

Role Definition

Boundary Setting

Tool Usage Instructions

Output Format Specification

Uncertainty Handling

Template

Recommended Configurations by Use Case

Q&A / Information Agent

Data Analysis Agent

Automated Reporting Agent