Tools Foundations

Purpose and Scope

Tools in the AI SDK are the bridge between language-model reasoning and concrete application behavior. The foundations documentation frames them as actions that a model can invoke when text generation alone is not enough, such as fetching weather, performing calculations, reading files, or calling an external service. This page explains the shared mental model before you move into advanced tool calling, agents, harnesses, approvals, or UI rendering. It focuses on the common contract: a model sees a named capability with a description and schema, emits a structured call, and receives a structured result that can influence the next response.

Sources: content/docs/02-foundations/04-tools.mdx

A tool is passed into core generation through the tools setting of text-generation APIs, specifically the documented generateText and streamText flows. The important point is that tool use is still part of the model conversation, not an unrelated side channel. The model chooses whether to call a tool, supplies arguments that are checked against the declared schema, and the SDK can run host-side implementations when an execute function is present. The returned tool result becomes new information available to the model, which is what enables multi-step answers that combine reasoning with real data or application actions.

Sources: content/docs/02-foundations/04-tools.mdx

Relevant Source Files

• content/docs/02-foundations/04-tools.mdx — Defines the general AI SDK tool concept, the three core tool properties, automatic execution, tool results, multi-step calls, and the documented categories of function, dynamic, provider-defined, and provider-executed tools.
• content/docs/03-ai-sdk-harnesses/03-tools.mdx — Extends the tool model to harnesses by describing built-in runtime tools, host-executed AI SDK tools, filtering through active or inactive tool sets, execution denial, and sandbox access during tool execution.

Core Primitives

Every ordinary AI SDK tool is described by three properties. The description tells the model what the capability does and can affect when the model selects it. The input schema describes the accepted arguments and is consumed by the model while also serving as validation for generated tool calls. The optional execute function is the host-side implementation that receives validated arguments and returns the result. The foundations page explicitly allows schemas from Zod or JSON Schema, which makes the contract usable both for TypeScript-first application code and for tools described dynamically or externally.

Sources: content/docs/02-foundations/04-tools.mdx

The simplest tool shape is a function tool: the application author defines the description, schema, and optional implementation. Function tools are the portable default because they are not tied to a specific provider feature. Dynamic tools keep the same overall behavior but relax static typing because their exact inputs and outputs are not known when the program is written. That matters for tools loaded from MCP servers, user-defined registries, databases, or other runtime sources where the SDK can still validate and route calls without giving the developer compile-time knowledge of every tool signature.

Sources: content/docs/02-foundations/04-tools.mdx

Provider-defined tools occupy a middle ground. The provider supplies the schema and description, while the application supplies execution. The documentation calls these client tools because the call still runs on your side, even though the model has provider-specific training or affordances for using it. Anthropic bash and text editing tools are examples in the docs. This category is useful when a model provider has invested in a known tool interface, but you still need application-level control over what actually happens, where it happens, and what result is sent back.

Sources: content/docs/02-foundations/04-tools.mdx

Execution Flow

The runtime sequence starts when you pass a tool map to generation. The model receives tool descriptions and schemas as part of the request, then may return a tool call instead of, or in addition to, normal text. The SDK validates the call arguments against the schema before execution. If an execute function exists, the SDK invokes it automatically and wraps the returned value as a tool result object. With multi-step generation, that result can be fed back into the model so the next step can produce a final answer or decide to call another tool.

Sources: content/docs/02-foundations/04-tools.mdx

This flow is intentionally explicit about responsibilities. The model proposes the call, the schema constrains the arguments, and the host implementation performs real work. That separation is important for safety and portability. Descriptions should help the model choose correctly, schemas should be narrow enough to reject malformed or ambiguous calls, and execute functions should still treat tool input as untrusted business input. Validation proves that the shape matches the schema; it does not prove that the requested operation is safe, authorized, affordable, or appropriate for the current user and environment.

Sources: content/docs/02-foundations/04-tools.mdx

import { tool } from 'ai';
import { z } from 'zod';
 
const weather = tool({
  description: 'Get the current temperature for a city.',
  inputSchema: z.object({
    city: z.string(),
  }),
  execute: async ({ city }) => {
    return { city, celsius: 20 };
  },
});

Harness Tool Behavior

Harnesses add a second tool surface on top of the general AI SDK model. The harness tools documentation distinguishes built-in tools exposed by the runtime from AI SDK tools supplied to HarnessAgent. Built-ins include common capabilities such as read, write, edit, bash, grep, glob, and webSearch, although individual runtimes may also expose native names. These calls are executed by the harness runtime rather than by the application process, and stream parts can indicate that the provider or runtime already performed the call through a providerExecuted marker.

Sources: content/docs/03-ai-sdk-harnesses/03-tools.mdx

Host-executed harness tools use the same tool definitions you would pass to a normal tool-loop agent. You create a tool with a description, input schema, and execute function, then pass it in the HarnessAgent tools setting. When the harness runtime asks for that host tool, HarnessAgent runs it in the host process and submits the result back to the runtime. This lets a coding-agent harness combine native file, shell, and search actions with application-specific capabilities such as weather lookup, internal APIs, issue trackers, or project metadata.

Sources: content/docs/03-ai-sdk-harnesses/03-tools.mdx

Harnesses also document filtering because a combined tool set can include powerful built-ins and user-defined host actions. activeTools acts as an allowlist, while inactiveTools acts as a denylist, and the settings should not be combined. The documentation states that the TypeScript settings type prevents that combination and HarnessAgent also throws at runtime if both are specified. For host-executed tools, inactive entries are not passed to the runtime; if the runtime still tries to call one, HarnessAgent returns an execution-denied tool result. Built-in filtering depends on adapter support and may be enforced through approval denial.

Sources: content/docs/03-ai-sdk-harnesses/03-tools.mdx

const agent = new HarnessAgent({
  harness: claudeCode,
  sandbox: createVercelSandbox({
    runtime: 'node24',
    ports: [4000],
  }),
  tools: { weather },
  activeTools: ['weather'],
});

System-to-Code Mapping

Implementation Guidance and Next Steps

Start with function tools when you own the behavior and want provider portability. Reach for dynamic tools when the available capabilities are discovered at runtime and exact TypeScript types are unavailable. Consider provider-defined tools when a provider offers a trained interface but you still need local execution control. In all cases, write narrow schemas, keep descriptions specific, and design execute functions as secure application entry points. If you are building coding-agent or harness workflows, also decide which built-in tools should be exposed, which host tools are necessary, and whether filtering or approval should protect high-impact operations.

Sources: content/docs/02-foundations/04-tools.mdx, content/docs/03-ai-sdk-harnesses/03-tools.mdx

After this page, read the tool-calling guide for multi-step loops, tool choice, active tools during individual steps, repair behavior, and approval patterns. For agent systems, continue to loop control and tool approvals so you can decide when a model may keep iterating and when a human or policy must intervene. For harness systems, treat tool filtering and sandbox access as part of your runtime boundary. The foundational idea remains the same everywhere: a tool is a structured, validated action channel that lets model output become useful work without hiding responsibility from your application.