ts ai tool

Show, update, or delete one AI tool — an action a model is allowed to invoke. ts ai tools lists them all.

Usage

ts ai tools [--csv] [--no-trunc]
ts ai tool <name>
ts ai tool set <name> <property> <value> [--workspace=WS]
ts ai tool delete <name> [--force]

Description

A tool is one capability exposed to a model: something implemented in the server, a prompt template, an HTTP endpoint, a Turbo app, or a tool discovered from an MCP server.

ts ai tools lists every tool the server holds, disabled ones included, which is the point — a tool that exists but is disabled is a common and otherwise invisible reason a model refuses to do something. Rows are alphabetical by name. KIND is one of Platform, Llm, Http, App, or Mcp. IMPLEMENTATION is the implementation key, the stable internal name the server dispatches on; it does not change when a tool is renamed, so it is the value to match on in scripts rather than the display name. ORIGIN is local for a tool defined on this server, or the federation sync state — Synced, Conflicted, Unsupported — for a tool that arrived from an upstream source.

ts ai tool <name> prints one tool's name, id, description, and enabled state. Pass the name the listing shows, or the tool's id. A name that two tools share is refused rather than resolved to one of them; pass the id in that case.

Tools that call an external provider can carry an API key. The key is write-only — the server returns only a configured flag and a last-four cue, never the key — and neither appears in the table or in the single-tool view. If you need to know whether a tool's secret is set, run ts ai tools --format=json and read secretConfigured and secretLast4.

Changing One

set writes one property per invocation, in kebab-case: name, description, api-key, enabled. true and false go out as booleans. A property that is not on that list is refused before anything is written.

api-key rotates the tool's provider key. Nothing reads it back, so the write is the whole interaction.

Kind and implementation key are immutable — a tool never changes what it is, only its settings. On a tool that arrived by federation, name and description are immutable too: the server accepts the request and silently keeps the upstream values, because the upstream definition owns them. enabled and api-key are the two properties that always take effect. If a rename appears not to stick, check the ORIGIN column.

delete soft-deletes, and prompts first unless you pass --force. Run non-interactively without --force and it fails rather than guessing.

Global Enablement Versus --workspace

These are two different states, not two ways of saying the same thing.

set <name> enabled true|false with no --workspace writes the tool's global row. Disabled globally means off everywhere, in every workspace, no matter what any per-workspace row says.

set <name> enabled true|false --workspace=<ws> writes that one workspace's assignment instead, and leaves the global row alone. Those per-workspace rows are default-deny in their own right: a workspace with no assignment for a tool does not get the tool. So enabling globally does not hand the tool to anybody — it makes the tool eligible, and each workspace still has to be enabled explicitly.

Put together: a tool is usable in a workspace only when it is enabled globally and enabled for that workspace. --workspace applies only to enabled; combine it with any other property and the command refuses. The workspace can be given as its id (the short name in URLs, such as acme) or its GUID.

Updates, deletes, and workspace enablement changes are recorded in the audit log as AgentToolUpdated, AgentToolDeleted, and AgentToolWorkspaceEnablementChanged.

Options

Flag	Description	Default/Values	Notes
--workspace	Narrow an enabled write to this workspace's assignment.	Workspace id or GUID	set … enabled only; refused with any other property.
--force, -f	Delete without confirming.		delete only.
--csv	Tab-separated output, nothing truncated.		ts ai tools only.
--no-trunc	Do not truncate columns.		ts ai tools only.

Examples

# What can the AI surface do on this server?
ts ai tools

# Full implementation keys and ids
ts ai tools --no-trunc

# The only way to see whether a tool's API key is set
ts ai tools --format=json

# One tool, by name
ts ai tool "Ticket lookup"

# Turn a tool off everywhere at once
ts ai tool set "Ticket lookup" enabled false

# Grant an already-enabled tool to one workspace
ts ai tool set "Search repos" enabled true --workspace=acme

# Rotate the key a tool calls its provider with
ts ai tool set "Ticket lookup" api-key hd_live_…

# Remove a tool for good
ts ai tool delete "Ticket lookup" --force

# Compare the tool set between two servers
ts ai tools --csv > tools-prod.tsv
ts --server=https://turbo.staging.example.net ai tools --csv > tools-staging.tsv

# These are different states. The first turns the tool off for everyone;
# the second only revokes one workspace's assignment and leaves the tool
# live elsewhere.
ts ai tool set "Search repos" enabled false
ts ai tool set "Search repos" enabled false --workspace=acme

# A tool listed as enabled here can still be unavailable in a workspace —
# per-workspace assignment is default-deny and this table does not show it.
ts ai tools

Output

ts ai tools:

NAME            KIND      IMPLEMENTATION       ENABLED  ORIGIN  ID
Search repos    Platform  turbo.repo.search    yes      local   9c0f2b73-...
Ticket lookup   Http      helpdesk.ticket.get  no       local   2a55e1d8-...

ts ai tool <name>:

Name:         Search repos
Id:           9c0f2b73-4a18-4de2-8f70-c1b5e3a09d62
Description:  Search repository metadata
Enabled:      True
Origin:

The Origin line is blank in this view — the single-tool response does not carry it. Read ORIGIN from ts ai tools, or federated and federationState from --format=json.

Exit Codes

0 on success, including when no tools are configured — the command says so rather than printing an empty table. -1 when the property is not settable, when --workspace is combined with a property other than enabled, when the name matches more than one tool, when the server rejects the write, or when you decline the delete prompt. -2 when set is given fewer than three positionals. -3 when the server cannot be reached. -4 when no account is signed in or the ticket has expired. -5 when the account is not a Server Administrator. -6 when no tool has that name or id, or when --workspace names a workspace that does not exist.

Related Commands

• ts ai — The rest of the namespace.
• ts ai connectors — MCP servers, which is where Mcp tools come from.
• ts ai endpoints — The model endpoints that invoke these tools.
• ts ai transcripts — What models actually did, call by call.
• ts workspace — The workspaces tools are enabled for.
• ts audit — Tool updates, deletes, and workspace enablement changes.