Designing Your Own Toolset

+15 Mana ✨
Hermes Configuration Guide(DOCUMENTATION)

Introduction

The shipped toolsets cover most cases, but sometimes you need a custom shape: a research bot that has memory but no browser, a deploy bot that has terminal but locked to a specific working directory, a coding partner that has patch but not write_file. Custom toolsets are how you encode those constraints in config rather than discipline.

Key Concepts

  • Custom toolset: A toolset you compose from individual tools rather than picking a built-in bundle.
  • Composition by listing tools: Toolsets in config.yaml can list specific tools to load, in addition to or instead of named bundles.
  • Minimal toolset: The smallest set that lets the agent accomplish the surface's job. This is the right starting point.

Real World Context

A team running Hermes inside their CI pipeline wants the agent to be able to read code, search the web for docs, and run tests, but never to mutate the repo. Their toolset is file (read-only effective use), web, terminal, with the patch and write_file tools either omitted from the file toolset or blocked at the permission layer. That is a custom shape no built-in archetype matches exactly.

Deep Dive

Four principles for designing your own:

  1. Start from the job, not the tools. What does this agent need to do? Answer questions about our docs and manage our smart home need very different toolsets.
  2. Minimize first, expand only when needed. It is far easier to add a tool when a workflow requires it than to remove one after the agent has been using it.
  3. Prefer named bundles over individual tool lists. web is clearer than web_search, web_extract. Mix in individual tools only when you genuinely want a subset.
  4. Document the shape in a comment. Six months from now you (or a teammate) will look at the config and ask why these particular tools are loaded. A one-line comment is worth the time.

A worked example: a docs-question-answering bot.

yaml
# Docs Q&A bot: searches the web, reads pages, no local filesystem,
# no terminal, no code execution. Memory is on so it can remember
# repeated questions and cache answers across sessions.
toolsets:
  - web         # web_search, web_extract
  - memory      # persistent cross-session memory
  - vision      # vision_analyze in case docs include screenshots

This is a tighter set than safe (no image_generate), because the bot does not need to make images. The smaller the set, the better the selection and the smaller the blast radius.

Common Pitfalls

  1. Adding tools speculatively: we might want image_generate later becomes the bot keeps offering to draw things when users ask for help. Add when the workflow needs it, not before.
  2. Forgetting the platform preset: If you are configuring a Telegram bot, do not start from scratch. Start from hermes-telegram and remove what you do not want.

Best Practices

  1. Use comments to explain intent: # read-only docs bot next to the toolsets list is more useful than the list itself.
  2. Review the toolset when the agent surprises you: Most agent surprises trace back to a tool being available when it should not be.

Summary

  • Custom toolsets compose named bundles plus individual tools.
  • Start from the agent's job, not from the registry.
  • Minimize first, expand when a real workflow requires it.
  • Document the shape so the next reader knows the intent.

Code Examples

yaml
# Custom toolset for a smart-home assistant on Telegram
# - homeassistant lets it control devices
# - memory persists user preferences across sessions
# - tts delivers responses as voice messages
# - web for occasional lookups
# Notably absent: file, terminal, code_execution, browser.
toolsets:
  - hermes-telegram     # baseline platform preset
  - homeassistant
  - memory
  - tts
  - web
✓ Completed