Custom Tools

Custom tools are a beta surface. Validate them in the sandbox before assigning them to production agents.

A custom tool is a TypeScript module that default-exports defineTool. Its name must match ^[a-z][a-z0-9_]*$ and an agent must list that exact name in allowedTools. For the example below, configure an API Connector named billing with the service origin, credential attachment, and permission to POST /invoices. Create its Connection and grant create_invoice to the selected agent.

create_invoice.ts

import { defineTool } from "@polpo-ai/tools";
import { Type } from "@sinclair/typebox";

export default defineTool({
  name: "create_invoice",
  description: "Create an invoice for a customer",
  parameters: Type.Object({
    customerId: Type.String(),
    amount: Type.Number(),
  }),
  connections: {
    billing: { provider: "billing", mode: "gateway", scopes: ["invoices:write"] },
  },
  async execute(ctx, params) {
    const response = await ctx.connections.require("billing").request<{ id: string }>({
      method: "POST",
      path: "/invoices",
      body: params,
    });
    if (response.status >= 400) throw new Error(`Invoice API returned ${response.status}`);
    const invoice = response.body;
    return `Created invoice ${invoice.id}`;
  },
});

execute returns a string or a ToolResult.

Execution context

Field	Description
`ctx.fs`	Filesystem rooted in the project workspace
`ctx.shell`	Shell capability for workspace commands
`ctx.connections`	Declared Connection capabilities authorized for this tool call
`ctx.invocation`	Immutable request, run, session, user, surface, and trusted metadata snapshot
`ctx.bindings`	Validated server-only values mapped from `ctx.invocation`
`ctx.env`	Safe environment variables with platform secrets removed
`ctx.workDir`	Absolute workspace directory
`ctx.data`	Optional host-scoped database capability: `list`, `describe`, `execute` and provider-dependent `query`; current agent grants apply to every call
`ctx.polpo`	Optional project-scoped Polpo SDK client
`ctx.signal`	Abort signal for this call
`ctx.onUpdate`	Callback for partial tool updates

Custom tools receive only their declared, authorized Connection capabilities; there is no ambient project account inventory. Slots are separate from model-facing parameters. Two execution modes coexist:

gateway: call ctx.connections.require(slot).request(...) with a provider-relative path. The host selects the account, checks current grants, and attaches credentials outside the sandbox. getToken, getKey, and getHeaders are unavailable on a gateway slot.
legacy_credentials: use getToken, getKey, or getHeaders when Git, HMAC, an SDK or another native operation needs a credential. An omitted mode retains this compatibility meaning. Cloud also requires explicit operator consent for the exact credential slot; the tool declaration cannot authorize itself.

For example, a repository_checkout tool can declare a github slot with mode: "legacy_credentials". An administrator separately grants it access:

polpo connections grant-slot "$CONNECTION_ID" \
  --agent leo --tool repository_checkout --scope repo --credential-slot github

# Remove only credential export consent, preserving the active grant's policy.
polpo connections grant-slot "$CONNECTION_ID" \
  --agent leo --tool repository_checkout --clear-credential-access

Clearing credential consent does not rewrite the tool to use the gateway. A subsequent direct credential request is denied until consent is granted again. There is no fallback from a denied gateway request to credential export. Direct tool code must keep credentials out of results, logs and model arguments. The exported credential retains its provider permissions; Polpo slot scopes and HTTP gateway policy cannot constrain requests made with an already copied token. Revocation prevents future credential delivery but cannot recall a copied token. A key-only record remains useful for this explicitly authorized direct mode; define its API destination and request policy before using it through a gateway. Agent-level Vault compatibility is a separate surface and remains available.

site_update.ts

export default defineTool({
  name: "site_update",
  description: "Update the current site",
  parameters: Type.Object({ title: Type.String() }),
  connections: {
    siteApi: {
      provider: "sitoinchat",
      mode: "gateway",
      scopes: ["site:read", "site:write"],
    },
  },
  async execute(ctx, params) {
    const siteApi = ctx.connections.require("siteApi");
    const response = await siteApi.request({
      method: "PATCH",
      path: "/site",
      body: params,
    });
    if (response.status >= 400) throw new Error(`Site API returned ${response.status}`);
    return "Site updated";
  },
});

Strict slots fail closed when no Connection matches, more than one matches, the grant is missing, or required scopes are unavailable. They never fall back to an arbitrary project Connection. A capability is valid only during the current tool invocation.

Trusted invocation bindings

Use trusted bindings when a tool must receive application identity or authorization data that the model must not supply. Binding fields are separate from parameters, are not included in the model-facing tool schema, and are resolved immediately before execution.

site_context_get.ts

import { defineTool } from "@polpo-ai/tools";
import { Type } from "@sinclair/typebox";

export default defineTool({
  name: "site_context_get",
  description: "Read the current site context",
  parameters: Type.Object({}, { additionalProperties: false }),
  bindingsSchema: Type.Object({
    externalUserId: Type.String(),
    tenantId: Type.String(),
    siteId: Type.String(),
    workingCopyId: Type.String(),
    grant: Type.String(),
  }, { additionalProperties: false }),
  serverBindings: {
    externalUserId: { $context: "invocation.user" },
    tenantId: { $context: "invocation.metadata.tenantId" },
    siteId: { $context: "invocation.metadata.siteId" },
    workingCopyId: { $context: "invocation.metadata.workingCopyId" },
    grant: { $context: "invocation.metadata.grant" },
  },
  async execute(ctx) {
    const { tenantId, siteId, workingCopyId, grant } = ctx.bindings;
    // Authorize and read only the bound tenant/site scope.
    // Use grant only in the trusted operation; never return it to the model.
    return JSON.stringify({ tenantId, siteId, workingCopyId });
  },
});

Supported binding roots are invocation.requestId, invocation.runId, invocation.sessionId, invocation.user, invocation.surface, and nested invocation.metadata.* JSON values. A missing or schema-invalid required value fails the tool before execute runs. Model arguments cannot override a binding with the same name. For durable loop resumes, trusted values are not restored from a persisted private snapshot. The host must re-authorize them through the invocation resolver; a missing or changed identity fails closed.

Dependencies and bundling

Cloud detects imported npm packages, installs them with lifecycle scripts disabled, and bundles the tool with esbuild for Node 22. Pure JavaScript dependencies are supported. Native addons containing .node binaries or binding.gyp are rejected; choose a pure JavaScript alternative. From 0.15.66, a tool entrypoint may import relative TypeScript, JavaScript, TSX, or JSON modules in the same source directory. The CLI resolves the static local graph and uploads one versioned artifact. Cycles and literal dynamic imports are supported. Computed dynamic imports, symlinks, files outside the tool directory, path traversal, and unsupported paths fail before upload. @polpo-ai/tools and @sinclair/typebox are runtime externals and do not need to be bundled.

Manage tools

polpo tools push .polpo/tools/create_invoice.ts
polpo tools list
polpo tools get create_invoice
polpo tools run create_invoice --args '{"customerId":"c_1","amount":4200}'
polpo tools rm create_invoice

polpo deploy also synchronizes .polpo/tools/*.ts. The Agent API exposes the same registry:

Method	Path	Description
`POST`	`/v1/tools`	Save `{ name, source }` or `{ name, artifact }`
`POST`	`/v1/tools/{name}/deploy`	Bundle with progress events
`GET`	`/v1/tools`	List tools
`GET`	`/v1/tools/{name}`	Read source and metadata
`POST`	`/v1/tools/{name}/run`	Run with `{ args }`
`POST`	`/v1/tools/{name}/generate`	Generate test inputs
`POST`	`/v1/tools/{name}/example`	Generate an example
`DELETE`	`/v1/tools/{name}`	Delete a tool

{
  "name": "billing-agent",
  "allowedTools": ["read", "write", "create_invoice"]
}

Saving source and deploying a bundle are distinct API operations. The CLI and dashboard perform both steps for you.

Application databases

Use ctx.data for structured records or scoped SQL on Databases. The host supplies it only when Data is configured and enabled. Check availability; query is optional for providers without SQL. Never accept provider credentials, project identity or extra grants from model arguments.

if (!ctx.data?.query) throw new Error("SQL database access is unavailable");
const result = await ctx.data.query("crm", {
  sql: "SELECT count(*) AS total FROM contacts WHERE email = $1",
  params: [args.email],
});

execute runs atomic structured batches. query supports one scoped SQL statement; mutations require mode: "write" and a write grant. Use an idempotency key when retrying writes. Database creation and migrations are administrative API/SDK/CLI operations.

Getting Started

Platform

Agents

Orchestration

Custom Tools

Execution context

Trusted invocation bindings

Dependencies and bundling

Manage tools

Application databases

​Execution context

​Trusted invocation bindings

​Dependencies and bundling

​Manage tools

​Application databases

Execution context

Trusted invocation bindings

Dependencies and bundling

Manage tools

Application databases