Skip to main content

​
Tools & toolsets

Tools are functions that extend the agent’s capabilities, organized into logical toolsets that can be enabled or disabled per platform and per specialist. Headmaster ships with a broad built-in tool registry — over 60 tools across 10+ categories.

​
Available tool categories

CategoryToolsDescription
Webweb_search, web_extractSearch the web and extract page content as markdown
X (Twitter) searchx_searchSearch X/Twitter — gated on xAI credentials, off by default
Terminal & filesterminal, process, read_file, patch, write_file, search_filesExecute commands, read/write/edit files, search file contents
Browserbrowser_navigate, browser_snapshot, browser_click, browser_type, browser_visionInteractive browser automation — text and vision based
Mediavision_analyze, image_generate, text_to_speechAnalyze images, generate images, convert text to speech audio
Agent orchestrationtodo, clarify, execute_code, delegate_taskPlanning, clarification, code execution, subagent delegation
Memory & recallmemory, session_searchPersistent memory and cross-session search
Automation & deliverycronjob, send_messageScheduled tasks and outbound messaging to channels
IntegrationsHome Assistant, MCP server tools, Spotify, DiscordSmart home, external tools, music, chat platforms
Code executionexecute_codeRun Python scripts that call Headmaster tools programmatically
Delegationdelegate_taskSpawn isolated subagents for parallel workstreams
Advanced reasoningmixture_of_agentsRoute a hard problem through multiple LLMs collaboratively

​
Enabling and disabling tools

​
Per specialist

  1. Open Settings → Specialists and pick a specialist.
  2. Go to the Tools section.
  3. Toggle toolsets on or off with checkboxes.
  4. Save.
A toolset toggled off is not loaded — the agent won’t see those tools or try to use them.

​
Per platform

Tools can be configured per platform (desktop, Telegram, Discord, etc.). This lets you give the desktop agent full tool access while restricting the Telegram agent to safe tools only.
  1. Open Settings → Headmaster’s Library → Advanced → Toolsets.
  2. Pick a platform.
  3. Toggle toolsets on or off for that platform.
  4. Save.

​
Platform presets

Headmaster has built-in platform presets that define sensible tool defaults:
PresetTools included
DesktopAll tools — full power
TelegramWeb, terminal, file, memory, skills, cron, messaging (no destructive tools)
DiscordWeb, terminal, file, memory, skills, cron, messaging
CLIAll tools — same as desktop
SafeWeb, memory, skills, clarify, todo (no terminal, no file write, no code execution)

​
Bundled tools

Some tools — web search, image generation, text-to-speech, and browser automation — can be enabled with a single bundled configuration instead of separate API keys for each service. Check the Headmaster site for current availability. When the bundle is configured:
  • Web search works out of the box — no Firecrawl or SerpAPI key needed.
  • Image generation works — no separate FAL or OpenAI images key needed.
  • Text-to-speech works — no OpenAI TTS key needed.
  • Browser automation works — no separate browser service needed.
Prefer your own keys? Each tool can also be configured individually with your own API credentials.

​
Using tools from chat

You don’t need to explicitly call tools — the agent picks the right tool based on your request. But you can guide it: 
Search the web for the latest Python release notes and summarize the key changes.
The agent uses web_search and web_extract automatically. 
Run `git status` in my project folder.
The agent uses terminal to run the command. 
Take a screenshot of https://example.com.
The agent uses browser_navigate and browser_vision. 
Generate an image of a mountain landscape at sunset.
The agent uses image_generate.

​
Tool call display

Every tool call appears in the chat as an expandable block: 
🔧 web_search("latest Python release notes")
→ 5 results found
→ Extracting content from python.org...
→ 3,200 characters extracted
Click the block to expand it and see the full tool input and output. This is your audit trail — every tool call is logged.

​
execute_code — programmatic tool calling

The execute_code tool lets the agent run Python scripts that call other Headmaster tools programmatically. This collapses multi-step pipelines into a single inference call. Instead of the agent calling web_search 5 times in sequence, it can write a Python script that calls web_search 5 times in a loop, processes the results, and returns a single summary. This is faster, cheaper, and more reliable. 
Search for the top 5 Python testing frameworks, extract their docs, and compare their features in a table.
The agent writes a Python script that:
  1. Calls web_search for each framework.
  2. Calls web_extract on each result.
  3. Parses the content.
  4. Builds a comparison table.
  5. Returns the table.
All in one tool call instead of 10+.

​
mixture_of_agents — collaborative reasoning

The mixture_of_agents tool routes a hard problem through multiple frontier LLMs collaboratively. It makes 5 API calls (4 reference models + 1 aggregator) with maximum reasoning effort. Use it for:
  • Complex math or algorithms.
  • Multi-step analytical reasoning.
  • Problems that benefit from diverse perspectives.
The agent decides when to use it — you don’t need to explicitly request it. It’s used sparingly because it’s expensive (5 API calls per use).

​
Tool configuration

Configure tools in Settings → Headmaster’s Library → Advanced → Tools:
SettingWhat it controls
Web searchEnable/disable, choose backend (bundled or your own API key)
Image generationEnable/disable, choose model
Text-to-speechEnable/disable, choose voice and provider
Browser automationEnable/disable, choose backend
TerminalEnable/disable, choose backend (see Terminal backends)
X (Twitter) searchEnable/disable, requires xAI credentials
Home AssistantEnable/disable, requires HA URL and token
SpotifyEnable/disable, requires Spotify credentials
DiscordEnable/disable, requires bot token