> ## Documentation Index
> Fetch the complete documentation index at: https://trytilde.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Give agents managed provider tools, MCP servers, your own tool servers, and tools bundled in their code, all authorized and audited by the gateway.

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](/docs/connections), checks the agent's [capabilities](/docs/iam), 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.

```typescript Tool server theme={"system"}
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.

```typescript bundled-tools.ts theme={"system"}
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](/docs/frameworks/overview) for each framework's helper.

<Warning>
  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.
</Warning>

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](#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](/docs/tools/management).
* **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](/docs/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](/docs/security/middleware) 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.

<Info>
  Sidecar agents currently receive channel tools only. Other tools need a direct or Lambda agent.
</Info>

## 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](/docs/sessions) tab, and their timing in [Tracing](/docs/traces). The audit trail records tool input after security middleware has screened it.