Tools

Built-in tools cover connection calls, stores, knowledge, skills, and chat controls. Custom tools in amodal/tools/<name>/ run your own code. A custom tool takes one of two layouts:

amodal/tools/
├── summarize_ticket/
│   └── tool.ts            ← metadata and handler in one module
└── review_request/
    ├── tool.json          ← metadata
    ├── handler.ts         ← default export (params, ctx) => result
    ├── package.json       ← (optional) npm dependencies
    └── requirements.txt   ← (optional) Python dependencies

When tool.ts exists, the directory uses that layout and ignores any tool.json. Composition (ctx.callTool, ctx.callSubagent), durable execution, triggers, the env allowlist, and UI labels require the tool.json layout.

Tool code ships with the agent repository. Commit, deploy, and read the build logs for TypeScript, dependency, and validation errors. See Deployment API.

Built-in Tools

A tool is "in scope" in unscoped chat, or when a named agent lists it in tools. In default chat, file tools come from the tools declared by agents/main/agent.json.

A skill added through propose_source_change reaches a named agent that lists its skills in agent.json only after someone adds it to that list.

Web Tools

{
  "webTools": {
    "provider": "google",
    "apiKey": "env:GOOGLE_API_KEY"
  }
}

"webTools": true is shorthand for the Google provider with env:GOOGLE_GENERATIVE_AI_API_KEY. google is the only provider. Both tools use Gemini grounding regardless of the agent's model. Set model to a Gemini model that supports Search and urlContext grounding, or omit it for the runtime default.

• web_search({query, max_results}) returns a synthesized answer with cited source URLs. max_results defaults to 5, maximum 10.
• fetch_url({url, prompt}) fetches and summarizes a public page through urlContext, and falls back to a local fetch with Readability extraction. The local fetch has a 10-second timeout and a 1 MB body cap. Each hostname is limited to 10 requests per 60 seconds.
• Under amodal dev, private-network URLs (localhost, RFC 1918, .local) use the local fetch. A hosted runtime refuses private-network and other non-public addresses.

Single-file Tools

amodal/tools/<name>/tool.ts holds the metadata and the handler:

export default {
  id: 'summarize_ticket',
  exposure: { kind: 'open' },
  base: {
    name: 'summarize_ticket',
    description: 'Load a support ticket and return a concise operator summary.',
    parametersJsonSchema: {
      type: 'object',
      properties: { ticket_id: { type: 'string' } },
      required: ['ticket_id'],
    },
  },
  async handle(ctx) {
    const { ticket_id } = ctx.input;
    const ticket = await ctx.request('support-api', `/tickets/${encodeURIComponent(ticket_id)}`);
    const needsVerification = ticket.category === 'account_access' && ticket.identity_verified !== true;
    return {
      ticket_id: ticket.id,
      status: ticket.status,
      needs_verification: needsVerification,
    };
  },
};

The default export must have a handle(ctx) function. Parameters arrive in ctx.input.

A tool.ts tool has a fixed 30-second timeout and an empty env allowlist, so ctx.env() returns undefined.

Tool Metadata

tool.json holds the metadata, and handler.ts default-exports (params, ctx) => result:

{
  "description": "Classify support ticket priority from category, impact, and age.",
  "parameters": {
    "type": "object",
    "properties": {
      "category": { "type": "string" },
      "affected_users": { "type": "number" }
    },
    "required": ["category", "affected_users"]
  },
  "timeout": 10000,
  "env": ["PRIORITY_RULES_URL"],
  "runningLabel": "Classifying {{category}} ticket",
  "completedLabel": "Classified ticket"
}

export default async function (params, ctx) {
  const broad = params.affected_users >= 10;
  return { priority: params.category === 'account_access' && broad ? 'high' : broad ? 'medium' : 'normal' };
}

The tool name is the directory name, which must be snake_case.

The loader accepts enabled, internal, responseShaping, and sandbox in tool.json but does not apply them. A tool.json tool cannot require approval: use tool.ts with exposure.kind: "requires-confirmation" for that, or gate the action inside a durable tool.

Handler Context

Durable tools also get ctx.requestInput, ctx.waitForApproval, ctx.sleepUntil, ctx.step, ctx.now, and ctx.random. See Durable Tools.

ctx.request rules

ctx.request resolves the connection's base URL and attaches its credentials. It does not evaluate policy.json permissions, field restrictions, or confirmation, and it does not retry. Enforce authorization in the tool or the downstream API.

The call's intent defaults to write for POST, PUT, PATCH, and DELETE, and to read otherwise. A read-only tool (exposure.kind: "open" in tool.ts, or confirm: false in tool.json) throws on write-intent calls. Pass intent: 'read' for a read-only POST, such as a search endpoint:

const report = await ctx.request('analytics', 'properties/123:runReport', {
  method: 'POST',
  intent: 'read',
  data: { metrics: [{ name: 'eventCount' }] },
});

Naming

Tool names must be snake_case: lowercase letters, digits, and underscores, starting with a letter.