@agentskit/tools

Profile: major-package

Give your agents real-world capabilities without writing a single integration.

Tags: ai · agents · llm · agentskit · ai-agents · function-calling · tool-use · mcp · web-search · filesystem

Verified proof

• Package metadata and tests live under packages/tools/.
• Package guide: https://www.agentskit.io/docs/reference/packages/tools
• Stability map: docs/STABILITY.md

How this fits the ecosystem

@agentskit/tools gives agents useful hands: web fetch, search, filesystem, shell, SQLite, integrations, and MCP-friendly tool definitions.

• AgentsKit: compose it with the other packages in this repo to build agents from small, swappable parts.
• Registry: look for ready agents and templates that already use this layer at registry.agentskit.io.
• Playbook: learn the production patterns behind this layer at playbook.agentskit.io.

Docs: package guide · agent handoff

Why tools

• Save days of integration work — web search, filesystem read/write, shell execution, and directory listing are ready to drop in; no wiring required
• Safe by default — filesystem tools are sandboxed to a basePath, shell commands require an explicit allowlist, so agents can't escape their boundaries
• Composable with any runtime — tools are just objects with a schema; they work with @agentskit/runtime, useChat, or any custom ReAct loop
• Extend without friction — author custom tools with @agentskit/templates and register them the same way as built-ins

Install

npm install @agentskit/tools

Quick example

import { createRuntime } from '@agentskit/runtime'
import { openai } from '@agentskit/adapters'
import { webSearch, filesystem, shell } from '@agentskit/tools'

const runtime = createRuntime({
  adapter: openai({ apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o' }),
  tools: [
    webSearch(),
    ...filesystem({ basePath: './workspace' }),
    shell({ timeout: 10_000, allowed: ['ls', 'cat', 'grep'] }),
  ],
})

const result = await runtime.run('Find the README and summarize it')
console.log(result.content)

With useChat (browser)

Tools are plain ToolDefinition values — register them in useChat the same way as in createRuntime.

Authoring tools with defineZodTool

If you use Zod, @agentskit/tools ships defineZodTool — a factory that:

• Types execute args from a Zod schema (full TypeScript inference)
• Validates args at runtime via schema.parse before calling your function
• Converts the Zod schema to JSON Schema for the adapter via a user-supplied toJsonSchema callback

Zod and zod-to-json-schema are consumer-owned optional dependencies. They are not package peers because defineZodTool accepts a structural schema and a consumer-supplied JSON-Schema converter.

npm install zod zod-to-json-schema

import { z } from 'zod'
import { zodToJsonSchema } from 'zod-to-json-schema'
import { defineZodTool } from '@agentskit/tools'
import type { JSONSchema7 } from 'json-schema'

const lookupUser = defineZodTool({
  name: 'lookup_user',
  description: 'Look up a user by ID.',
  schema: z.object({
    userId: z.string().uuid(),
    includeProfile: z.boolean().optional(),
  }),
  toJsonSchema: (s) => zodToJsonSchema(s) as JSONSchema7,
  async execute(args) {
    // args.userId         → string  (UUID-validated by Zod at runtime)
    // args.includeProfile → boolean | undefined
    return await db.users.findById(args.userId, { profile: args.includeProfile })
  },
})

For tools without Zod, use defineTool from @agentskit/core with a JSON Schema as const.

Features

Built-ins (6)

• webSearch() — live web search with Serper, Tavily, DuckDuckGo, or a custom provider.
• fetchUrl() — safe HTTP GET with JSON / text handling, size cap, boilerplate stripping.
• filesystem({ basePath }) — sandboxed read, write, and list operations.
• shell({ allowed }) — shell execution with command allow-list + timeout.
• sqliteQueryTool({ path }) — read-only SQL against a local SQLite file. Optional peer dep on better-sqlite3. Note: never feed unvalidated user prompts straight into the sql field — wrap with input filtering or use parameterized helpers if exposing it to untrusted input.
• slackTool({ webhookUrl }) — post to a Slack Incoming Webhook. For Bearer-token features (search, channel listing), use the slack() integration.

Safe outbound requests

safeFetch(input, init?, policy?) defaults to denying non-public hosts and re-checks every redirect hop. Address classification comes from @agentskit/net, so reserved, unspecified, multicast, CGNAT, IPv4-mapped private, and other non-unicast ranges are blocked as well as private, loopback, and link-local addresses. Hostname checks use Node DNS and fail closed if any result is non-public or lookup fails.

isPrivateIPv4 and isPrivateHost keep their legacy decimal handling for zero-padded dotted quads (010.0.0.1 means 10.0.0.1). safeFetch first applies WHATWG URL canonicalization; avoid ambiguous numeric URL forms.

For a vetted internal target, pass an exact allowedHosts entry or set allowPrivateHosts: true; redirects still pass through the selected policy. The DNS preflight does not pin the resolved address to the later connection, so it does not prevent DNS rebinding. webSearch() also reads provider responses through @agentskit/net with a 2 MiB default byte limit; set maxResponseBytes to change it.

Integrations (20+)

github, linear, slack, notion, discord, gmail, googleCalendar, stripe, postgres, s3, firecrawl, reader, documentParsers (PDF / DOCX / XLSX), openaiImages, elevenlabs, whisper, deepgram, maps, weather, coingecko, browserAgent (Puppeteer). Each integration exports granular sub-tools (e.g. githubCreateIssue, stripeCreatePaymentIntent) alongside the bundled set.

Authoring + composition

• defineZodTool — Zod-based factory with runtime validation + type inference.
• For composition, use composeTool and wrapToolWithSelfDebug from @agentskit/core.
• For execution policy, use createMandatorySandbox from @agentskit/sandbox.

MCP bridge

• createMcpClient + toolsFromMcpClient — consume any MCP server's tools.
• createMcpServer — publish AgentsKit tools to an MCP host that supports the documented 2024-11-05 tools bridge. Tools marked requiresConfirmation fail closed unless authorizeToolCall returns an explicit approval. Pass validateArgs (for example, createAjvValidator()) to enforce advertised schemas before execution; remote errors are sanitized unless exposeErrors: true is explicitly enabled for trusted development.
• Stdio + in-memory transports. HTTP/SSE adapters are host-owned.

McpToolDefinition (from @agentskit/tools/mcp) extends the core tool shape with optional title and annotations: title, readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. Server listing and client import preserve these fields, including explicit false hints. Imported titles use the existing maxDescriptionBytes UTF-8 limit; malformed metadata is rejected. Hints remain untrusted advisory data and never grant confirmation or alter execution policy.

These fields follow the MCP tool metadata specification. They are optional descriptor extensions on the existing 2024-11-05 bridge; older clients may ignore unknown fields. This does not add negotiation or other features from newer protocol revisions.

Supported MCP protocol matrix

The client and server fail closed when initialize.params.protocolVersion is not 2024-11-05. Hosts that need an omitted capability must provide it around the injected transport; the bridge does not imply support or isolation that it does not implement.

All tools honor the ToolDefinition contract (ADR 0002) — parallel tool calling works with any adapter, @agentskit/runtime, useChat, or a custom loop.

Subpaths

Ecosystem

Contributors

License

MIT — see LICENSE.

Docs

Full documentation · GitHub

Maturity and compatibility

• Stability: beta — see docs/STABILITY.md
• Node.js 20+ and TypeScript strict mode
• Published as @agentskit/tools

Contributing

See CONTRIBUTING.md and the monorepo LICENSE.