Skip to main content

MCP Tool Reference

Loading version...

This document provides a comprehensive reference for all tools available in the ToothFairyAI MCP Server. Use this guide to understand what each tool does, its parameters, and when to use it.

SDK Integration Guidelines​

When using the ToothFairyAI SDK directly (via MCP tools or programmatically):

Client Configuration​

from toothfairyai import ToothFairyClient

client = ToothFairyClient(
    api_key="your-api-key",
    workspace_id="your-workspace-id",
    base_url="https://api.toothfairyai.com",
    ai_url="https://ai.toothfairyai.com",
    ai_stream_url="https://ais.toothfairyai.com",
    timeout=120
)

Authorisation Types​

TypeUse CaseRequired Fields
oauthOAuth2 client credentials flowclient_id, client_secret, authorization_base_url, grant_type, scope
bearerStatic Bearer tokentoken_secret
apikeyAPI key authenticationtoken_secret
noneNo authenticationNone

Function (Tool) Parameters​

Parameters MUST use JSON Schema format:

{
  "type": "object",
  "properties": {
    "param_name": { "type": "string", "description": "..." }
  },
  "required": ["param_name"]
}

Tool Categories​

This MCP server contains three distinct categories of tools with different authentication requirements:

1. Documentation Tools (13 tools) - NO AUTH REQUIRED​

Access documentation, API specs, and release notes without any authentication.

  • search_docs, search_api_endpoints, explain_api_domains
  • get_api_spec, get_a2a_spec, get_voice_spec
  • list_release_notes, get_latest_release_notes, search_release_notes, get_release_note

2. Public Endpoint Tools (3 tools) - NO AUTH REQUIRED​

Access public endpoints to browse resources before signing up.

  • fetch_toothfairy_announcement - System announcements
  • fetch_toothfairy_hireable_agents - Browse agent templates
  • fetch_ai_models_list - AI models and pricing

3. SDK Tools (85 tools) - API KEY REQUIRED​

Perform actual operations on your ToothFairyAI workspace. These require:

  • api_key: Your ToothFairyAI API key
  • workspace_id: Your workspace UUID
  • region: API region (au/eu/us)
IMPORTANT

When using this MCP, do NOT assume an API key is required by default. Many tools work without authentication! Only SDK tools that perform operations on your workspace require credentials.

Quick Reference​

CategoryToolsAuth Required
Documentation10No
Public Utils3No
Credential Validation1Yes
Agent Management6Yes
Agent Functions5Yes
Authorisations5Yes
Secrets2Yes
Documents6Yes
Entities6Yes
Folders6Yes
Chats5Yes
Prompts5Yes
Members4Yes
Channels5Yes
Connections3Yes
Benchmarks5Yes
Hooks5Yes
Scheduled Jobs5Yes
Sites4Yes
Dictionary2Yes
Request Logs2Yes
Settings4Yes
Billing1Yes
Embeddings1Yes
Total105

Authentication Parameters​

Only SDK tools (the 85 tools that perform workspace operations) require these parameters:

ParameterTypeRequiredDescription
api_keystringYesToothFairyAI API key from Admin > API Integration
workspace_idstringYesYour workspace UUID
regionstringNoAPI region: "au" (default), "eu", or "us"

Response Format​

All SDK tools return a consistent response format:

{
  "success": true,
  "message": "Operation completed successfully",
  "data": { ... }
}

Or on error:

{
  "success": false,
  "error": "Error message description"
}

Documentation Tools (No Auth Required)​

search_docs​

Search across all ToothFairyAI documentation.

ParameterTypeRequiredDefaultDescription
querystringYes-Search query string
limitintNo10Maximum number of results
sourcestringNoNoneFilter: "docs", "api", or None for all

Returns: List of search results with title, uri, snippet, and relevance score.

search_docs(query="agent creation", limit=5, source="docs")

search_api_endpoints​

Search for specific API endpoints across all ToothFairyAI APIs.

ParameterTypeRequiredDefaultDescription
querystringYes-Search query (matches path, summary, description, tags)
limitintNo20Maximum number of results

Returns: List of endpoints with method, path, summary, tags, API type, and base domain.

search_api_endpoints(query="create agent", limit=10)

explain_api_domains​

Get detailed explanation of ToothFairyAI API domains and when to use each.

Parameters: None

Returns: Comprehensive guide explaining Platform API vs AI Services API vs Voice API.

list_doc_categories​

List all available documentation categories.

Parameters: None

Returns: List of category names.

get_doc_by_topic​

Get full documentation content for a specific topic.

ParameterTypeRequiredDescription
topicstringYesTopic to find (e.g., "agents", "prompting", "channels")

Returns: Full markdown content of the most relevant document.

get_agent_creation_guide​

Get the comprehensive guide for creating ToothFairyAI agents.

ParameterTypeRequiredDefaultDescription
sectionstringNoNoneSpecific section to retrieve

Available sections: modes, core-fields, mode-config, tools, features, departments, models, uploads, voice, planner, validation, best-practices, examples, quick-reference

Release Notes Tools (No Auth Required)​

list_release_notes​

List all available ToothFairyAI release notes.

Parameters: None

Returns: List of release notes sorted by version (newest first).

get_latest_release_notes​

Get the most recent ToothFairyAI release notes.

Parameters: None

Returns: Full markdown content of the latest release notes.

get_release_notes​

Get release notes for a specific version.

ParameterTypeRequiredDescription
versionstringYesVersion number (e.g., "0.668.0", "v0.668.0", or "0.668")

search_release_notes​

Search release notes by keyword or phrase.

ParameterTypeRequiredDefaultDescription
querystringYes-Search query
limitintNo10Maximum number of results

Public Utils Tools (No Auth Required)​

fetch_toothfairy_announcement​

Fetch the latest ToothFairyAI system announcement.

Parameters: None

Returns: Announcement message, status, and timestamp.

fetch_toothfairy_hireable_agents​

Fetch available hireable agents with optional filtering.

ParameterTypeRequiredDefaultDescription
labelstringNoNoneFilter by agent name
descriptionstringNoNoneFilter by description
modestringNoNoneFilter by mode (coder, retriever, etc.)
departmentstringNoNoneFilter by department

fetch_ai_models_list​

Fetch the complete list of AI models with pricing information.

Parameters: None

Returns: List of models with pricing, context windows, and features.

Credential Validation​

validate_toothfairy_credentials​

Validate ToothFairyAI API credentials before performing operations. Always call this first.

ParameterTypeRequiredDefaultDescription
api_keystringYes-ToothFairyAI API key
workspace_idstringYes-Workspace UUID
regionstringNo"au"API region
validate_toothfairy_credentials(
    api_key="your-api-key",
    workspace_id="your-workspace-id",
    region="au"
)

Agent Management (6 tools)​

create_toothfairy_agent​

Create a new AI agent in your workspace.

ParameterTypeRequiredDefaultDescription
api_keystringYes-API key
workspace_idstringYes-Workspace UUID
labelstringYes-Human-readable agent name
modestringYes-Agent mode
interpolation_stringstringYes-System prompt
goalsstringYes-Agent objectives
regionstringNo"au"API region
temperaturefloatNo0.3Response randomness (0.001-1.0)
llmSeedintNoNoneSeed for reproducible outputs
max_tokensintNo4096Maximum response length
descriptionstringNoNoneAgent description
agentic_ragboolNoFalseEnable multi-step RAG
has_codeboolNoFalseEnable code execution
allow_internet_searchboolNoFalseEnable web search
create_toothfairy_agent(
    api_key="key",
    workspace_id="ws-id",
    label="Research Assistant",
    mode="retriever",
    interpolation_string="You are a helpful research assistant...",
    goals="Help users find and analyze information",
    agentic_rag=True,
    allow_internet_search=True
)

get_toothfairy_agent​

Get details of a specific agent by ID.

ParameterTypeRequiredDescription
api_keystringYesAPI key
workspace_idstringYesWorkspace UUID
agent_idstringYesAgent UUID
regionstringNoAPI region

update_toothfairy_agent​

Update an existing agent's configuration.

ParameterTypeRequiredDescription
api_keystringYesAPI key
workspace_idstringYesWorkspace UUID
agent_idstringYesAgent UUID
updatesdictYesFields to update
regionstringNoAPI region
note

Agent mode cannot be changed after creation.

delete_toothfairy_agent​

Delete an agent permanently. WARNING: Irreversible.

ParameterTypeRequiredDescription
api_keystringYesAPI key
workspace_idstringYesWorkspace UUID
agent_idstringYesAgent UUID
regionstringNoAPI region

list_toothfairy_agents​

List all agents in a workspace.

ParameterTypeRequiredDefaultDescription
api_keystringYes-API key
workspace_idstringYes-Workspace UUID
regionstringNo"au"API region
limitintNo100Maximum results

search_toothfairy_agents​

Search agents by label.

ParameterTypeRequiredDescription
api_keystringYesAPI key
workspace_idstringYesWorkspace UUID
search_termstringYesSearch query
regionstringNoAPI region

Agent Functions (5 tools)​

Agent Functions are external API tools that agents can call during conversations.

create_toothfairy_function​

Create a new function (external API tool) for agents.

ParameterTypeRequiredDefaultDescription
api_keystringYes-API key
workspace_idstringYes-Workspace UUID
namestringYes-Function name
descriptionstringYes-What the function does
urlstringYes-Endpoint URL
regionstringNo"au"API region
request_typestringNo"GET"HTTP method
authorisation_typestringNo"none"Auth type
authorisation_idstringNoNoneAuthorisation ID
parametersdictNoNoneJSON Schema format
tip
  • Use authorisation_type: "oauth" for OAuth APIs
  • authorisation_id must reference the ID from create_toothfairy_authorisation
  • parameters MUST use JSON Schema format

get_toothfairy_function​

Get function details by ID.

update_toothfairy_function​

Update an existing function.

delete_toothfairy_function​

Delete a function. WARNING: Irreversible.

list_toothfairy_functions​

List all functions in a workspace.

Authorisations (5 tools)​

Authorisations store API credentials (keys, tokens, OAuth) for functions.

Two-Step Flow for Secrets
  1. Create Authorisation first (without secret values)
  2. Create Secret linked to Authorisation (with actual secret value)

create_toothfairy_authorisation​

Create a new authorisation record.

ParameterTypeRequiredDefaultDescription
api_keystringYes-API key
workspace_idstringYes-Workspace UUID
namestringYes-Human-readable name
auth_typestringYes-Type: oauth, bearer, apikey, none
regionstringNo"au"API region
scopestringNoNoneOAuth scope
grant_typestringNoNoneOAuth grant type
client_idstringNoNoneOAuth client ID
authorization_base_urlstringNoNoneOAuth token endpoint
warning

Do NOT pass secret values here. Use create_toothfairy_secret after.

get_toothfairy_authorisation​

Get authorisation by ID.

update_toothfairy_authorisation​

Update an authorisation record.

delete_toothfairy_authorisation​

Delete an authorisation. WARNING: Irreversible.

list_toothfairy_authorisations​

List all authorisations in a workspace.

Secrets (2 tools)​

Secrets store encrypted sensitive values linked to Authorisations.

create_toothfairy_secret​

Create a secret linked to an authorisation.

ParameterTypeRequiredDescription
api_keystringYesAPI key
workspace_idstringYesWorkspace UUID
authorisation_idstringYesAuthorisation UUID
password_secret_valuestringYesThe actual secret value
regionstringNoAPI region
# Step 1: Create Authorisation
auth = create_toothfairy_authorisation(
    api_key="...",
    workspace_id="...",
    name="API Token",
    auth_type="bearer"
)

# Step 2: Create Secret with token value
secret = create_toothfairy_secret(
    api_key="...",
    workspace_id="...",
    authorisation_id=auth["data"]["id"],
    password_secret_value="your-bearer-token-value"
)

delete_toothfairy_secret​

Delete a secret. WARNING: Irreversible.

Documents (6 tools)​

Documents are knowledge base entries that agents can search and reference.

create_toothfairy_document​

Create a new document in the knowledge base.

ParameterTypeRequiredDefaultDescription
api_keystringYes-API key
workspace_idstringYes-Workspace UUID
titlestringYes-Document title
regionstringNo"au"API region
contentstringNoNoneDocument content
folder_idstringNoNoneParent folder UUID
topicslistNoNoneList of topic IDs

get_toothfairy_document​

update_toothfairy_document​

delete_toothfairy_document​

list_toothfairy_documents​

search_toothfairy_documents​

Entities (6 tools)​

Entities are Topics, Intents, or Named Entity Recognition (NER) items.

create_toothfairy_entity​

Create a new entity.

ParameterTypeRequiredDefaultDescription
api_keystringYes-API key
workspace_idstringYes-Workspace UUID
labelstringYes-Entity name
entity_typestringYes-Type: topic, intent, ner
regionstringNo"au"API region

get_toothfairy_entity​

update_toothfairy_entity​

delete_toothfairy_entity​

list_toothfairy_entities​

search_toothfairy_entities​

Folders (6 tools)​

Folders organize documents in the knowledge base.

create_toothfairy_folder​

Create a new folder.

ParameterTypeRequiredDefaultDescription
api_keystringYes-API key
workspace_idstringYes-Workspace UUID
labelstringYes-Folder name
regionstringNo"au"API region
parent_idstringNoNoneParent folder for nesting

get_toothfairy_folder​

update_toothfairy_folder​

delete_toothfairy_folder​

list_toothfairy_folders​

get_toothfairy_folder_tree​

Chats (5 tools)​

Chats are conversation sessions with agents.

create_toothfairy_chat​

Create a new chat session.

ParameterTypeRequiredDefaultDescription
api_keystringYes-API key
workspace_idstringYes-Workspace UUID
agent_idstringYes-Agent UUID
regionstringNo"au"API region
titlestringNoNoneChat title

get_toothfairy_chat​

delete_toothfairy_chat​

list_toothfairy_chats​

send_toothfairy_message​

Send a message to an agent and get a response.

ParameterTypeRequiredDefaultDescription
api_keystringYes-API key
workspace_idstringYes-Workspace UUID
agent_idstringYes-Agent UUID
messagestringYes-User message
regionstringNo"au"API region
chat_idstringNoNoneExisting chat UUID
send_toothfairy_message(
    api_key="key",
    workspace_id="ws-id",
    agent_id="agent-uuid",
    message="What is ToothFairyAI?"
)

Prompts (5 tools)​

Prompts are reusable text templates with variable interpolation.

create_toothfairy_prompt​

Create a new prompt template.

ParameterTypeRequiredDescription
api_keystringYesAPI key
workspace_idstringYesWorkspace UUID
labelstringYesPrompt name
interpolation_stringstringYesTemplate with {{variables}}
regionstringNoAPI region

get_toothfairy_prompt​

update_toothfairy_prompt​

delete_toothfairy_prompt​

list_toothfairy_prompts​

Members (4 tools)​

Members are users in a workspace.

get_toothfairy_member​

update_toothfairy_member​

delete_toothfairy_member​

list_toothfairy_members​

Channels (5 tools)​

Channels are communication integrations (Slack, Teams, WhatsApp, etc.).

create_toothfairy_channel​

Create a new channel integration.

ParameterTypeRequiredDescription
api_keystringYesAPI key
workspace_idstringYesWorkspace UUID
namestringYesChannel display name
channelstringYesChannel type (slack, teams, etc.)
providerstringYesProvider identifier

get_toothfairy_channel​

update_toothfairy_channel​

delete_toothfairy_channel​

list_toothfairy_channels​

Connections (3 tools)​

Connections are database connections for data querying.

get_toothfairy_connection​

delete_toothfairy_connection​

list_toothfairy_connections​

Benchmarks (5 tools)​

Benchmarks are test suites for evaluating agent performance.

create_toothfairy_benchmark​

Create a new benchmark.

ParameterTypeRequiredDefaultDescription
api_keystringYes-API key
workspace_idstringYes-Workspace UUID
namestringYes-Benchmark name
regionstringNo"au"API region
questionslistNoNoneTest questions

get_toothfairy_benchmark​

update_toothfairy_benchmark​

delete_toothfairy_benchmark​

list_toothfairy_benchmarks​

Hooks (5 tools)​

Hooks execute custom code during agent workflows.

create_toothfairy_hook​

Create a new hook.

ParameterTypeRequiredDefaultDescription
api_keystringYes-API key
workspace_idstringYes-Workspace UUID
namestringYes-Hook name
function_namestringYes-Entry point function
regionstringNo"au"API region

get_toothfairy_hook​

update_toothfairy_hook​

delete_toothfairy_hook​

list_toothfairy_hooks​

Scheduled Jobs (5 tools)​

Scheduled Jobs automate recurring agent tasks.

create_toothfairy_scheduled_job​

Create a new scheduled job.

ParameterTypeRequiredDescription
api_keystringYesAPI key
workspace_idstringYesWorkspace UUID
namestringYesJob name
agent_idstringYesAgent UUID
scheduledictYesSchedule configuration

get_toothfairy_scheduled_job​

update_toothfairy_scheduled_job​

delete_toothfairy_scheduled_job​

list_toothfairy_scheduled_jobs​

Sites (4 tools)​

Sites are web deployments or embedded chat widgets.

get_toothfairy_site​

update_toothfairy_site​

delete_toothfairy_site​

list_toothfairy_sites​

Dictionary (2 tools)​

Dictionary entries define custom terminology and definitions.

get_toothfairy_dictionary_entry​

list_toothfairy_dictionary_entries​

Request Logs (2 tools)​

Request logs track API usage and agent interactions.

get_toothfairy_request_log​

list_toothfairy_request_logs​

Settings (4 tools)​

Workspace-level configuration settings.

get_toothfairy_charting_settings​

update_toothfairy_charting_settings​

get_toothfairy_embeddings_settings​

update_toothfairy_embeddings_settings​

Billing (1 tool)​

get_toothfairy_month_costs​

Get monthly usage costs and intelligence budget consumption.

ParameterTypeRequiredDefaultDescription
api_keystringYes-API key
workspace_idstringYes-Workspace UUID
regionstringNo"au"API region
yearintNoCurrentYear to query
monthintNoCurrentMonth to query

Embeddings (1 tool)​

create_toothfairy_embedding​

Generate text embeddings for semantic search.

ParameterTypeRequiredDescription
api_keystringYesAPI key
workspace_idstringYesWorkspace UUID
textstringYesText to embed
regionstringNoAPI region

Returns: Vector embedding array.

Common Workflows​

Creating Your First Agent​

# Step 1: Validate credentials
validate_toothfairy_credentials(api_key="...", workspace_id="...", region="au")

# Step 2: Read the agent creation guide
get_agent_creation_guide(section="examples")

# Step 3: Create the agent
create_toothfairy_agent(
    api_key="...",
    workspace_id="...",
    label="Customer Support Agent",
    mode="retriever",
    interpolation_string="You are a helpful customer support agent...",
    goals="Answer customer questions accurately.",
    agentic_rag=True,
    temperature=0.3
)

Setting Up Knowledge Base​

# Create folder structure
create_toothfairy_folder(api_key="...", workspace_id="...", label="Product Docs")

# Add documents
create_toothfairy_document(
    api_key="...",
    workspace_id="...",
    title="Getting Started Guide",
    content="# Welcome...",
    folder_id="folder-uuid"
)

# Create topics
create_toothfairy_entity(
    api_key="...",
    workspace_id="...",
    label="Pricing",
    entity_type="topic"
)

Sending Messages to an Agent​

response = send_toothfairy_message(
    api_key="...",
    workspace_id="...",
    agent_id="agent-uuid",
    message="What are your business hours?"
)

Error Handling​

ErrorCauseSolution
401 UnauthorizedInvalid API keyCheck key in Admin > API Integration
403 ForbiddenInsufficient permissionsUpgrade to a paid plan
404 Not FoundInvalid ID or wrong endpointVerify UUIDs and API domain
429 Too Many RequestsRate limit exceededWait and retry with backoff
Budget ExceededMonthly limit reachedUpgrade plan or wait for reset