Tools allow your prompts to call external functions — web searches, calculations, API calls, and more. Agents use tools across multiple LLM calls to solve complex tasks.
Creating Tools
Tools are defined using the AI SDK’s tool() function. Each tool includes a description, a Zod schema for parameters, and an execute function:
import { tool } from "ai";
import { z } from "zod";
const calculateTool = tool({
description: "Performs basic arithmetic calculations",
parameters: z.object({
expression: z.string().describe("The mathematical expression to evaluate"),
}),
execute: async ({ expression }) => {
const result = Function(`"use strict"; return (${expression})`)();
return { result };
},
});
Passing Tools to the Client
Pass tools to createAgentMarkClient via the tools option — a plain object keyed by name:
import { createAgentMarkClient, VercelAIModelRegistry } from "@agentmark-ai/ai-sdk-v5-adapter";
import { openai } from "@ai-sdk/openai";
import { tool } from "ai";
import { z } from "zod";
const modelRegistry = new VercelAIModelRegistry();
modelRegistry.registerModels(["gpt-4o"], (name: string) => {
return openai(name);
});
const calculateTool = tool({
description: "Performs basic arithmetic calculations",
parameters: z.object({
expression: z.string().describe("The mathematical expression to evaluate"),
}),
execute: async ({ expression }) => {
const result = Function(`"use strict"; return (${expression})`)();
return { result };
},
});
const agentmark = createAgentMarkClient({
modelRegistry,
tools: {
calculate: calculateTool,
},
});
Tool Configuration in Frontmatter
Reference tools by name in your prompt’s frontmatter. The tool names must match the keys in your tools object:
---
name: calculator
text_config:
model_name: gpt-4
tools:
- calculate
---
<System>
You are a math tutor that can perform calculations. Use the calculate tool when you need to compute something.
</System>
<User>What's 235 * 18 plus 42?</User>
MCP Tools in Frontmatter
Reference Model Context Protocol tools directly using mcp://{server}/{tool}:
---
name: mcp-example
text_config:
model_name: gpt-4
tools:
- mcp://docs/web-search
- summarize
---
<System>
Use the web-search tool to look up relevant documentation when needed.
Use the summarize tool to condense content into a short summary.
</System>
<User>
Find the page that explains MCP integration and summarize it in 2 sentences.
</User>
mcp://docs/web-search resolves to the MCP server named docs, tool web-searchsummarize is a tool provided via the tools option in createAgentMarkClient- Use
mcp://docs/* to include every tool exported by a server
See MCP Integration for details on configuring MCP servers.
Agents
Enable multi-step agent workflows by setting max_calls. The SDK automatically handles multiple LLM calls, passing tool results back until the task is complete:
---
name: travel-agent
text_config:
model_name: gpt-4
max_calls: 3
tools:
- search_flights
- check_weather
---
<System>
You are a helpful travel assistant that can search flights and check weather conditions.
When helping users plan trips:
1. Search for available flights
2. Check the weather at the destination
3. Make recommendations based on both flight options and weather
</System>
<User>
I want to fly from San Francisco to New York next week. Can you help me plan my trip?
</User>
Testing Agents in the Dashboard
Run agents directly in the Dashboard to see how they use tools in real time:
View configured tools and their schemas:
Best Practices
- Keep tools focused on a single responsibility
- Provide clear descriptions to help the LLM use tools appropriately
- Handle errors gracefully and return informative error messages
- Use descriptive parameter names and include helpful descriptions
Have Questions?
We’re here to help! Choose the best way to reach us:
