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.

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(),
  }),
  async execute(ctx, params) {
    const key = ctx.connections.getToken("billing");
    if (!key) throw new Error("Missing billing credential");

    const response = await fetch("https://api.example.com/invoices", {
      method: "POST",
      headers: {
        authorization: `Bearer ${key}`,
        "content-type": "application/json",
      },
      body: JSON.stringify(params),
    });
    if (!response.ok) throw new Error(`Invoice API returned ${response.status}`);
    const invoice = await response.json();
    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`	Project Connections resolved 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.polpo`	Optional project-scoped Polpo SDK client
`ctx.signal`	Abort signal for this call
`ctx.onUpdate`	Callback for partial tool updates

There are no ambient platform credentials. Custom tools read external secrets through ctx.connections; tokens are resolved server-side from project Connections and injected only for the tool call.

const token = ctx.connections.getToken("github"); // provider id, connection id, or unique connection name
const headers = ctx.connections.getHeaders("linear-mcp");
const available = ctx.connections.list(); // non-secret metadata only

The methods above are the legacy project-scoped contract. For multi-user or multi-resource applications, declare a logical Connection slot instead. The slot is not part of the model-facing parameters, and the runtime selects one Connection from immutable invocation identity and metadata.

site_update.ts

export default defineTool({
  name: "site_update",
  description: "Update the current site",
  parameters: Type.Object({ title: Type.String() }),
  connections: {
    siteApi: {
      provider: "sitoinchat",
      scopes: ["site:read", "site:write"],
    },
  },
  async execute(ctx, params) {
    const siteApi = ctx.connections.require("siteApi");
    const response = await fetch("https://api.example.com/site", {
      method: "PATCH",
      headers: {
        ...siteApi.getHeaders(),
        "content-type": "application/json",
      },
      body: JSON.stringify(params),
    });
    if (!response.ok) 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.
    return JSON.stringify({ tenantId, siteId, workingCopyId, grant });
  },
});

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.

Getting Started

Platform

Agents

Orchestration

Custom Tools

Execution context

Trusted invocation bindings

Dependencies and bundling

Manage tools

​Execution context

​Trusted invocation bindings

​Dependencies and bundling

​Manage tools

Execution context

Trusted invocation bindings

Dependencies and bundling

Manage tools