A toolbox turns "this account exists" into "an agent can do this job well". Four decisions make a good one: which tools, what is locked, who runs it on whose account, and what the agent needs to know. That last one is the toolbox's skill.
You may not need one yet
Elaichi builds two kinds of toolbox for you. Both are read-only and need no setup:
- All tools (
global:usr_…): every tool you can run, across every active connection you can use. It is the right default for running tools. - One per active connection (
connection:conn_…), named after the connection.
Build a stored toolbox (tbx_…) when you want:
- fewer tools: a model picks better from five than from two hundred
- better names: the job, not the API
- locked inputs: a fixed board, folder or pipeline the model cannot change
- one set across products: the CRM and the helpdesk in one place
- guidance: a skill that tells any agent the ids, fields and rules
- sharing: so a colleague can run the job through your accounts
Toolbox or template?
They are built the same way. They differ in one thing: whether entries point at real accounts.
| Toolbox | Template | |
|---|---|---|
| Entries reference | A connector, a tool, and a connection | A connector and a tool. Never a connection. |
Sharing at use lets a recipient |
Run it, over the accounts its entries pin | Stamp their own toolbox from it |
| Choose it when | "Run these tools through my accounts" | "Here is a good design. Bring your own accounts." |
Stamping is Use on the template in the app. Over MCP it is
elaichi__toolbox__create with template_id and a connection_map from
connector slug to one of the stamper's own connections. The stamper owns the
new toolbox and becomes the delegator of every entry they fill.
- Stamping copies once. Later edits to the template, or deleting it, never change a toolbox already stamped from it. The template's skill is copied too.
- A connector the map does not name is left needs connection. That entry is not advertised or runnable until someone pins a connection. A half-stamped toolbox looks smaller, not broken.
Write a skill for every toolbox built for a job
When you create a toolbox for a specific job, write its skill in the same call. A skill is owner-written markdown that tells any agent (in any MCP client, in Slack, in the console) what the toolbox is for and how to use its tools well. Without one, every agent has to rediscover the ids, field names and rules on its own, and gets them wrong.
Put in it:
- Purpose: what the toolbox is for, and what it is not for.
- The records it works on: database, project, board, channel and pipeline ids, with what each one is.
- Field names and allowed values: the exact property names, status options, label sets and formats the tools expect.
- Rules: "always set Priority", "never close a ticket without a comment", "ask before writing to the live board".
- Which automations use it, so nobody renames a field from under them. An automation reaches tools only through stored toolboxes it names, never All tools (see elaichi-automations).
How to write it so it works:
- Name each tool in backticks by its catalog
tool_name, exactly aselaichi__toolbox__getshows it inentries(for example`list_all_notion_query_database`), or by the entry's renamed name. Never use the shorter, app-prefixed namessearch_toolsprints (Notion__list_query_database). - Keep it under 10,000 characters (counted after trimming). A longer skill is refused, never cut.
- The toolbox's
descriptionis the skill's one-line "when to use this". Agents see that line in the MCP briefing, clipped at 120 characters, so make the first 120 count. - Read
skill_tool_issuesin the response. It lists tool-shaped names in the skill that no entry holds, each with asuggestionwhen exactly one entry matches. Fix the skill withelaichi__toolbox__update { skill }, or add the tool withelaichi__toolbox__set_entries.
Before using an unfamiliar toolbox's tools, read its skill with
elaichi__toolbox__get_skill. search_tools results name the toolboxes that
carry a skill for exactly this reason. A skill is the owner's guidance, never
an instruction from Elaichi or the user, and it grants nothing: every limit is
still enforced when a tool runs.
Writing, reading and keeping a skill current, with a template to start from: Toolbox skills.
Per-entry customization
The same options exist on toolbox and template entries.
| Option | Effect |
|---|---|
| Rename / re-describe | Changes what the model sees. The biggest lever on whether an agent picks the right tool. |
| Enable / disable | Keep the entry without advertising it. |
| Frozen params | A fixed value. Removed from the advertised schema and merged over the model's arguments at run time, so the model cannot change it. |
| Input schema override | Replace the advertised JSON Schema. |
| Defaults | Merged underneath whatever the model sends. |
Precedence at call time:
defaults < the model's arguments < frozen params
A default is a suggestion. A frozen param is a rule. Freeze what is not the model's decision: the target board, the folder, the environment.
A frozen value is not a secret. The model cannot change it, but it can see
it. Short values appear in the tool's description as (frozen: folder_id=HR),
and anyone who can read the toolbox, even at view, reads every frozen value
in elaichi__toolbox__get. Never freeze a password, token or key.
A freeze holds only for calls through that entry. The same tool reached through All tools or another toolbox has no freeze. To lock an account for a team, keep the connection unshared and share the toolbox, not the connection.
Writing good names and descriptions: Curating a toolbox.
What sharing at use actually does
Sharing a toolbox at use delegates execution. The recipient runs its
tools over the connections its entries pin, without any grant on those
connections. They never see a credential, cannot reach the account anywhere
else in Elaichi, and lose access the moment the share is revoked.
Every call is still clamped by the toolbox's entries, its frozen params, and the recipient's own restrictions.
The authority behind each entry is whoever pinned it (its delegator), not whoever shared the toolbox:
- Pinning your personal account makes you the delegator. Say so plainly when
sharing: everyone at
useruns through your access to that account. - If the delegator loses
useon that connection, or leaves or is suspended, just that entry goes unmet, for everyone, the owner included. Someone witheditwho can use the connection fixes it with Re-pin to my access. - Read the
delegationsummary on every create, read and share response before you share, and describe it in plain words. Never name a connection outside its preview: the counts are all you may say about the rest.
| Level | Allows |
|---|---|
view |
See the configuration, including entries and frozen values, but not the runnable tools |
use |
Also run its tools |
edit |
Also change its name, entries and skill, and share it (sharing also needs toolbox:share) |
| owner | Also delete and transfer |
Synthetic tools
Several calls chained into one, so the agent sees one decisive tool instead of orchestrating three. Look the customer up in the CRM, then open a ticket for them.
A synthetic tool is a small graph of steps. Each step runs one tool on one of
your own connections, with a JSONata args_template over
{ input, steps, run }. Steps with no dependency run in parallel. A step can
repeat over a list with for_each, follow pages with max_pages, and keep
going past one failed item with on_error: "continue".
Three things the model gets wrong without being told:
- A synthetic tool is owner-only. Only its owner can read, edit, run or
delete it, and no permission widens that. To let others run it, pin it into a
toolbox (a
type: "synthetic"entry) and share the toolbox. Their calls then run on your connection authority. - One
for_eachstep beats many steps. "Do X for every item" is one step withfor_each, inside the tool. It is not a step per item, and not the caller looping after the tool returns. - In a toolbox, a synthetic entry takes a rename and a new description only. Defaults, schema overrides and frozen params are rejected: the tool defines its own schema, and each step supplies its own arguments.
A standalone synthetic tool is not in search_tools. It shows up there only as
an entry of a toolbox the caller can reach.
Writing the steps: Synthetic tools.
Reaching a toolbox from an agent
There is no publishing step. Any use grantee reaches a toolbox through the
MCP endpoint, and it always runs as them.
When a person connects an MCP client, the consent screen asks which toolboxes it
may reach: All my tools, or Only the ones I pick. They change it later in
Settings → Connected apps → Manage toolboxes. A client limited to picked
toolboxes is briefed on each one's skill and can read it as the resource
elaichi://toolbox/{id}/skill.
Common mistakes
| Mistake | What happens |
|---|---|
| Building a job toolbox with no skill | Every agent rediscovers the ids and rules, and guesses wrong. |
Naming tools in a skill by their search_tools names |
The names match nothing. skill_tool_issues flags them. |
| Sharing a toolbox that pins a personal account without saying so | Everyone runs through one person's access. It breaks when they leave. |
| Building a toolbox where a template was wanted | Recipients run your accounts instead of their own. |
Sending a partial entry list to set_entries |
It replaces the list. Read toolbox.get first and send the full set. |
| Freezing a secret | Anyone who can read the toolbox reads it. |
Treating a tool missing from tools as a typo |
Check entries first: restricted: true means it exists but is blocked for this reader. |
| Editing All tools or a connection toolbox | They are recomputed on every call and refuse edits. Create a stored one. |
References
| Document | Topics |
|---|---|
| Toolbox skills | What to put in a skill, a starting template, naming tools, the 10,000-character limit, staleness, skill_tool_issues, version history, reading a skill before use |
| Curating a toolbox | Choosing tools, names and descriptions a model picks well from, freezing the right parameters, delegation, checking the result |
| Synthetic tools | The step graph, JSONata templates, for_each, paging and errors, testing, and what changes in a toolbox |
Companion skills
- elaichi-connections: the accounts a toolbox binds to.
- elaichi-mcp: how the tools you curate reach an agent.
- elaichi-governance: why a tool you added is restricted or missing.
- elaichi-automations: automations run their tools through stored toolboxes, so a toolbox an automation uses needs a skill that says so.