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 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, 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
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 |