Skip to main content
A running server can register hundreds of tools — your own functions, mounted MCP servers, the standard toolbox, presets, and Babelfish flows. Tool organization is the layer that makes that namespace navigable: an editable overlay of folders, display names, tags, visibility, and informational capability badges that sits beside every tool without touching what the tool does.

​
The overlay

The overlay is an unversioned organizational layer, keyed by tool name and kept separate from any tool’s behavior. It applies to any tool in the namespace — a native plugin tool, a preset, a flow — never a preset-only concern. It has two parts:
  • Folders — real folder entities forming a tree. A folder has a name and an optional parent; nesting is endless through the parent chain.
  • A per-tool row — for each tool that has one: its display name, the folder it is filed in, its user tags, and its visibility. Most tools never own a row — a tool with no row simply renders under its own name, unfiled, with only its native tags.
Because it is unversioned by design, editing the overlay never appends a tool version or rebinds anything. It is metadata about the tool, not part of the tool’s behavior, so it rides no version history: a display-name change or a folder move takes effect immediately and is not something you roll back through the versioning spine.

​
Display names

A per-tool row may set a display_name that overrides the label a UI renders. When set, surfaces show the display name; when absent, they fall back to the tool name. The real tool name stays identifiable — most surfaces render it beside the display name, and where a compact surface shows the display name bare the raw name is one picker or edit surface away — so a display name is a friendlier label, never a rename. The name a caller invokes is unchanged. The display name follows a tool everywhere the Studio lists one to choose: the preset create form, agent composition, schedule creation, extension apply, and the Connectors page’s MCP config each label a tool Display Name (raw_name), with the raw name alone as the fallback. Agent composition’s selected-tool chips are the compact exception — they carry the bare display name, with the raw name one picker or edit surface away. A plugin’s own surfaces label the same way. A display name is distinct from a tool’s description (its LLM-facing docstring) — the description is the tool’s own behavioral text, while the display name is purely a human label in the overlay.

​
Folders

Folders are entity-backed, not a string on each tool. You create a folder (at the root or under a parent), rename it, move it to a new parent, and delete it. The store enforces the tree’s integrity:
  • Sibling names are unique within a parent (root folders share the empty parent), so no two folders in the same place collide.
  • A move that would form a cycle is refused — a folder can never become its own ancestor.
  • A delete requires the folder empty of both subfolders and tool rows — you cannot orphan its contents by removing it.
A UI renders folders as a current-directory explorer with a breadcrumb: the current folder’s subfolders first, then the tools filed directly in it, with unfiled tools living at the root.

​
Tags: two sources, one merged view

A tool can carry tags from two independent sources, and UIs show them merged:
  • Plugin-native tags are code-owned and read-only. A plugin declares them on the tool itself (for example, tags={"acme"} on a tool registration), so they ship with the tool and cannot be edited from a UI.
  • User tags are the overlay’s editable set. You add or replace them on a tool’s overlay row, and they persist independently of the plugin’s own tags.
A tool’s effective tag set is the union of the two. Grouping and filtering a tool list works over that merged set, so a tool declared acme by its plugin and tagged reviewed by you appears under both.

​
Capability badges: informational, never enforced

Alongside tags, a tool can carry capability badges — short labels that flag what a tool touches or does, meant purely to inform the human scanning a tool list. Like tags, badges come from two independent sources and UIs show them merged:
  • Plugin-declared badges are code-owned. A plugin declares them on the tool itself (Acme’s acme_probe declares network, for example), so they ship with the tool.
  • Operator-overlay badges are the overlay’s editable set, stored on a tool’s overlay row and managed from the CLI or API.
A tool’s displayed badges are the union of the two.
Badges are declarative and informational only — never an enforcement boundary. A badge such as network or storage-write describes a tool for a human reader; it grants and gates nothing. Never treat a badge as a permission — reach for access control to actually constrain what a tool can do.
Badges are free-form: there is no fixed, enforced list. Any label from the same charset the tag vocabulary uses is accepted — lowercase alphanumerics, hyphens, and underscores (so no slashes; use the hyphen form like storage-read). To keep badges legible across a deployment, a small suggested generic vocabulary is worth standardizing on — as guidance, not a rule: Coin your own beyond these whenever a deployment needs a finer signal — the list above is only a starting point, never a closed set.

​
Visibility: hidden is not security

The overlay’s visibility flag is tri-state:
  • Default (no user opinion) — the plugin-declared visibility applies. A plugin may ship a tool hidden by default (Acme’s acme_probe does), and with no overlay opinion that declaration stands.
  • Shown — force the tool visible, overriding a plugin’s hidden default.
  • Hidden — force the tool hidden.
Hidden is UI visibility only — never a security boundary. A hidden tool is merely kept out of the lists; it stays fully registered and callable through the API. Never hide a tool expecting it to be unreachable — reach for access control for that. A hidden tool has no reveal affordance in any UI; unhide it by setting its visibility to Shown from the CLI or API (tai tool-meta set <tool> --visibility shown).

​
Lifecycle

An overlay row is keyed by tool name, so the platform keeps it in step with the tools it describes:
  • A preset delete cascades its overlay row away — deleting the preset removes the row keyed on its name.
  • A preset rename re-keys the row to the new name, so the organization you gave a preset survives the rename that rebinds its tool.
  • A plugin uninstall keeps the row. The tool it described is gone, so a UI hides the now-dangling entry; reinstalling the plugin brings the tool back under the same name and the row applies again.

​
Managing the overlay

Edit the overlay from the CLI with tai tool-meta — folders and per-tool rows:
set is a merge-patch — only the flags you pass are sent, so omitting a field leaves it unchanged. In the Studio the Tools screen carries the full per-tool edit dialog (display name, tags, folder, and the three-way visibility control) plus folder navigation; hidden tools are excluded from the screen outright, so unhiding is a CLI/API operation (set visibility Shown). The Presets screen and the Babelfish Flows page edit the display name, tags, and folder of the tools they list (hide management is centralized on the Tools screen).

​
See also

  • tai tool-meta reference — the full folder and overlay command set.
  • The screens — the Tools screen’s folders and edit dialog.
  • Presets — a preset’s own record carries no organization; it rides this overlay like any tool.
  • Babelfish — flows organize through the same overlay from the Flows page.