MCP Tool Reference
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
| Type | Use Case | Required Fields |
|---|---|---|
oauth | OAuth2 client credentials flow | client_id, client_secret, authorization_base_url, grant_type, scope |
bearer | Static Bearer token | token_secret |
apikey | API key authentication | token_secret |
none | No authentication | None |
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_domainsget_api_spec,get_a2a_spec,get_voice_speclist_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 announcementsfetch_toothfairy_hireable_agents- Browse agent templatesfetch_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 keyworkspace_id: Your workspace UUIDregion: API region (au/eu/us)
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
| Category | Tools | Auth Required |
|---|---|---|
| Documentation | 10 | No |
| Public Utils | 3 | No |
| Credential Validation | 1 | Yes |
| Agent Management | 6 | Yes |
| Agent Functions | 5 | Yes |
| Authorisations | 5 | Yes |
| Secrets | 2 | Yes |
| Documents | 6 | Yes |
| Entities | 6 | Yes |
| Folders | 6 | Yes |
| Chats | 5 | Yes |
| Prompts | 5 | Yes |
| Members | 4 | Yes |
| Channels | 5 | Yes |
| Connections | 3 | Yes |
| Benchmarks | 5 | Yes |
| Hooks | 5 | Yes |
| Scheduled Jobs | 5 | Yes |
| Sites | 4 | Yes |
| Dictionary | 2 | Yes |
| Request Logs | 2 | Yes |
| Settings | 4 | Yes |
| Billing | 1 | Yes |
| Embeddings | 1 | Yes |
| Total | 105 |
Authentication Parameters
Only SDK tools (the 85 tools that perform workspace operations) require these parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
api_key | string | Yes | ToothFairyAI API key from Admin > API Integration |
workspace_id | string | Yes | Your workspace UUID |
region | string | No | API 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.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
query | string | Yes | - | Search query string |
limit | int | No | 10 | Maximum number of results |
source | string | No | None | Filter: "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.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
query | string | Yes | - | Search query (matches path, summary, description, tags) |
limit | int | No | 20 | Maximum 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
topic | string | Yes | Topic 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.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
section | string | No | None | Specific 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
version | string | Yes | Version number (e.g., "0.668.0", "v0.668.0", or "0.668") |
search_release_notes
Search release notes by keyword or phrase.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
query | string | Yes | - | Search query |
limit | int | No | 10 | Maximum 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.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
label | string | No | None | Filter by agent name |
description | string | No | None | Filter by description |
mode | string | No | None | Filter by mode (coder, retriever, etc.) |
department | string | No | None | Filter 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.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
api_key | string | Yes | - | ToothFairyAI API key |
workspace_id | string | Yes | - | Workspace UUID |
region | string | No | "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.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
api_key | string | Yes | - | API key |
workspace_id | string | Yes | - | Workspace UUID |
label | string | Yes | - | Human-readable agent name |
mode | string | Yes | - | Agent mode |
interpolation_string | string | Yes | - | System prompt |
goals | string | Yes | - | Agent objectives |
region | string | No | "au" | API region |
temperature | float | No | 0.3 | Response randomness (0.001-1.0) |
llmSeed | int | No | None | Seed for reproducible outputs |
max_tokens | int | No | 4096 | Maximum response length |
description | string | No | None | Agent description |
agentic_rag | bool | No | False | Enable multi-step RAG |
has_code | bool | No | False | Enable code execution |
allow_internet_search | bool | No | False | Enable 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
api_key | string | Yes | API key |
workspace_id | string | Yes | Workspace UUID |
agent_id | string | Yes | Agent UUID |
region | string | No | API region |
update_toothfairy_agent
Update an existing agent's configuration.
| Parameter | Type | Required | Description |
|---|---|---|---|
api_key | string | Yes | API key |
workspace_id | string | Yes | Workspace UUID |
agent_id | string | Yes | Agent UUID |
updates | dict | Yes | Fields to update |
region | string | No | API region |
Agent mode cannot be changed after creation.
delete_toothfairy_agent
Delete an agent permanently. WARNING: Irreversible.
| Parameter | Type | Required | Description |
|---|---|---|---|
api_key | string | Yes | API key |
workspace_id | string | Yes | Workspace UUID |
agent_id | string | Yes | Agent UUID |
region | string | No | API region |
list_toothfairy_agents
List all agents in a workspace.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
api_key | string | Yes | - | API key |
workspace_id | string | Yes | - | Workspace UUID |
region | string | No | "au" | API region |
limit | int | No | 100 | Maximum results |
search_toothfairy_agents
Search agents by label.
| Parameter | Type | Required | Description |
|---|---|---|---|
api_key | string | Yes | API key |
workspace_id | string | Yes | Workspace UUID |
search_term | string | Yes | Search query |
region | string | No | API 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.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
api_key | string | Yes | - | API key |
workspace_id | string | Yes | - | Workspace UUID |
name | string | Yes | - | Function name |
description | string | Yes | - | What the function does |
url | string | Yes | - | Endpoint URL |
region | string | No | "au" | API region |
request_type | string | No | "GET" | HTTP method |
authorisation_type | string | No | "none" | Auth type |
authorisation_id | string | No | None | Authorisation ID |
parameters | dict | No | None | JSON Schema format |
- Use
authorisation_type: "oauth"for OAuth APIs authorisation_idmust reference the ID fromcreate_toothfairy_authorisationparametersMUST use JSON Schema format