Tools

Tools let an agent act: read a repository, send an email, query a CRM. In Tilde, the gateway executes most tool calls on the agent’s behalf. It injects the credential from a connection, checks the agent’s capabilities, and records the call. The agent never holds a provider credential. It receives tool definitions, and it calls them with its short-lived invocation token.

Types of tools

Tilde supports five kinds of tools. You can mix them on one agent.

Type	Where the code runs	Who holds credentials	Choose it when
Managed tools	Tilde	Tilde, encrypted in a connection	The provider is in the Tilde catalog, such as GitHub, Google Workspace, Slack, or Stripe.
MCP servers	The upstream MCP server	Tilde, encrypted in a connection	You want to use an existing third-party or internal MCP server.
Tilde tool servers	Your own process or AWS Lambda function	Tilde, if the server needs credentials	The tool should run apart from the agent, and be reusable across agents.
Bundled tools	The agent process	You	The tool needs in-process state, or belongs to the agent’s own code.
Built-in tools	Tilde	Tilde	The agent needs to message other agents, search its thread, or find tools on demand.

Managed tools

Managed tools are integrations that ship with Tilde. The catalog includes Google Workspace, GitHub, Slack, Sentry, PostHog, Firecrawl, Stripe, Tavily, E2B, Modal, AWS, and more. You connect an account once, and Tilde keeps the credential encrypted. It injects the credential only when it runs the selected tool. Some chat providers, such as GitHub, Slack, and WhatsApp, serve chat and tools from one connection.

MCP servers

An MCP server connection reaches an existing Streamable HTTP MCP server. The upstream server runs the tools. Tilde holds the OAuth, API key, or bearer credential, and stands between the agent and the server. The catalog includes curated servers such as Notion, Linear, HubSpot, Vercel, Neon, and Salesforce. An administrator can also add any other server by URL. Use this for internal MCP servers too. Your agents then reach them through one audited path, rather than each holding a credential. Tilde discovers a server’s tools when a connection first lists them, and again when you refresh them. Agents only receive the tools that Tilde discovered for their connection.

Tilde tool servers

A Tilde tool server is your own tool backend, written with the Tilde SDK. It runs in one of two ways:

Self-hosted. Your process dials out to the gateway with a tool server token, publishes its tools, and answers calls. Like an agent, it exposes no endpoint.
AWS Lambda. The gateway invokes your function by its ARN, with Tilde’s AWS credentials.

A tool server that needs credentials declares its own sign-in, such as an API key or OAuth with your own client. Each account a person connects is an instance of the server. Tilde verifies the credentials with your server, stores them encrypted, and sends them with every call on that instance.

Tool server

import * as z from "zod";
import { createToolHost, defineAuth } from "@trytilde/sdk/tool-host";

const auth = defineAuth({
  provider: { id: "example-crm", name: "Example CRM" },
  methods: {
    api_key: {
      name: "API key",
      schema: z.object({ api_key: z.string().min(1) }),
    },
  },
  async verify({ api_key }) {
    return { accountLabel: await lookUpWorkspace(api_key) };
  },
});

// Dials out with TILDE_TOOL_HOST_TOKEN. Nothing calls this process.
createToolHost({
  auth,
  tools: {
    search_customers: auth.tool({
      description: "Find customers whose name or email contains the query.",
      summary: "Searched customers",
      inputSchema: z.object({ query: z.string() }),
      annotations: { readOnly: true },
      // `ctx.auth` holds the credentials of the instance the agent called.
      run: ({ query }, ctx) => searchCustomers(ctx.auth.api_key, query),
    }),
  },
});

The Python SDK provides the same API in tilde.tool_hosts.

Bundled tools

Bundled tools are tools you write in the agent’s own code, with your framework’s native tool type. They run in the agent process, and Tilde never executes them. Tilde still knows about them. You declare them with defineTools, and tilde deploy registers them with each deployment. The agent’s Tools tab then lists them before the agent first runs, and Tilde records every call.

bundled-tools.ts

import { defineTools } from "@trytilde/sdk";
import { tool } from "ai";
import { z } from "zod";

export const bundledTools = defineTools({
  roll_dice: tool({
    description: "Roll dice and add them up.",
    inputSchema: z.object({ count: z.number().int().optional() }),
    // Shown in the session instead of the raw call.
    metadata: { tilde: { summary: "Rolled dice" } },
    execute: async ({ count = 1 }) => rollDice(count),
  }),
});

Export the value from your entry module, and pass it to your framework adapter on each invocation. See Framework integrations for each framework’s helper.

Bundled tools execute in the agent process. Tilde does not proxy them, so their credentials and other sensitive inputs remain your responsibility. Prefer managed tools, MCP servers, or tool servers for anything that touches a secret.

If you remove every bundled tool from your code, the removed tools stop running from the next invocation.

Built-in tools

Tilde offers a small set of built-in tools, each only when the agent’s capabilities allow it:

agents.list, agents.message, and agents.wait let an agent find other agents and talk to them.
thread.participants and thread.search let an agent read its conversation.
tools.search, tools.schemas, and tools.execute let an agent find and call tools on demand. See Tool discovery.
tools.result returns the result of a background tool call.

Use tools in an agent

Your framework adapter merges every tool the agent can use into the framework’s own tool list. That includes the channel’s tools, such as sendMessage, the tools you chose for the agent, and its bundled tools. Each call to a remote tool runs through the gateway. To use tools without an adapter, read ctx.tools inside run. It holds the agent’s tools with their schemas.

Tool names

A tool from a connection or tool server has a catalog name: the source’s slug, a dot, and the tool name, such as github.create_issue. The slug is fixed when you add the source to the agent. Models accept tool names of up to 64 characters, from a limited character set. The SDK gives each longer or unusual name a stable alias for the model, and maps calls back to the catalog tool.

Tool discovery

Each agent uses one of two discovery modes:

Listed directly. The agent receives every tool’s schema up front. This suits agents with a few dozen tools.
Found by search. The agent receives tools.search, tools.schemas, and tools.execute. It searches for tools and loads their schemas on demand, which keeps its context small.

We recommend search for agents with many tools. Set the mode on the agent’s Tools tab. It applies from the next run.

Background tools

Mark a tool as Background when it takes a long time. The agent receives a ticket straight away, and keeps working. The result arrives as new input, or through tools.result. Tilde aborts a background call that nobody collects after one hour.

Use another agent as a tool

Any registered agent can talk to another. The built-in agents.message tool sends a message, and agents.wait waits for the response. Grant the calling agent the agents.invoke capability for the target agent.

Control tool access

Tool access is deny by default.

Tool selection. An agent gets only the tools switched on for it on its Tools tab. See Manage tools.
Capabilities. An agent can invoke only the tools named in its tools.invoke capability. Set it to none, all, or a selected list in the agent’s Capabilities tab. See IAM.
Personal tools. A chat user can connect their own account, for example their own Google account. The agent can use those tools only while it serves that user, and only with the tools.personal capability.
Security middleware. In Tilde Enterprise, text an agent sends through a channel tool passes through response guards first.

Tilde builds an agent’s tool list once per invocation, and caches it for at most 15 minutes. Changes apply from the next invocation. Tilde checks credentials and tool server health on every call.

Sidecar agents currently receive channel tools only. Other tools need a direct or Lambda agent.

Audit tool calls

Tilde records every tool call against the invocation that made it, including calls to bundled tools. Review calls in the agent’s Sessions tab, and their timing in Tracing. The audit trail records tool input after security middleware has screened it.

Get started

Platform

Framework integrations

Security

Observability

Deployment

Types of tools

Managed tools

MCP servers

Tilde tool servers

Bundled tools

Built-in tools

Use tools in an agent

Tool names

Tool discovery

Background tools

Use another agent as a tool

Control tool access

Audit tool calls

​Types of tools

​Managed tools

​MCP servers

​Tilde tool servers

​Bundled tools

​Built-in tools

​Use tools in an agent

​Tool names

​Tool discovery

​Background tools

​Use another agent as a tool

​Control tool access

​Audit tool calls

Types of tools

Managed tools

MCP servers

Tilde tool servers

Bundled tools

Built-in tools

Use tools in an agent

Tool names

Tool discovery

Background tools

Use another agent as a tool

Control tool access

Audit tool calls