Skip to main content
Tools in AgentMark allow you to extend your prompts with custom functionality, such as web searching, calculation, API calls, and more.

​
Creating tools

Tools are defined using the AI SDK’s native tool() function. Each tool includes a description, a Zod schema for its 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 }) => {
    // Note: This is a simple example. Use a safe math parser in production.
    const result = Function(`"use strict"; return (${expression})`)();
    return { result };
  },
});

​
Passing tools to the client

You pass tools directly to createAgentMarkClient via the tools option. There is no separate registry step — tools are 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 your prompt’s frontmatter, you reference tools by name using a simple string array. The tool names must match the keys you provided in the tools object when creating the client. Example:
calculator.prompt.mdx
---
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>
The actual tool implementation — including its description, parameter schema, and execute function — is defined in your TypeScript code when creating the client, not in the frontmatter.

​
MCP tools in frontmatter

You can reference Model Context Protocol (MCP) tools directly in your prompt frontmatter using mcp://{server}/{tool}. These tools are resolved at runtime from the MCP servers configured in your adapter client.
mcp-example.prompt.mdx
---
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-search.
  • summarize is a tool provided via the tools option in createAgentMarkClient.
To include every tool exported by a server, use the wildcard *: 
---
text_config:
  tools:
    - mcp://docs/*
---
If any MCP tool names collide with tools you defined in the client, the later-added tool overwrites the earlier one. Note: MCP server configuration (URL/SSE or stdio) is set when creating your AgentMark client via the mcpServers option. See MCP Integration for details.

​
Agents

When setting max_calls, your LLM can make multiple calls to solve complex agentic tasks. Tools are referenced by name in your prompt’s frontmatter and resolved from the tools you passed to the client: To enable agents:
  1. Add max_calls to your model settings
  2. List the tools your agent needs by name
  3. The SDK will automatically handle multiple LLM call communication
travel-agent.prompt.mdx
---
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 (2024-04-20). Can you help me plan my trip?
</User>

​
Best practices

  1. Keep tools focused on a single responsibility
  2. Provide clear descriptions in your tool definitions to help the LLM use tools appropriately
  3. Handle errors gracefully and return informative error messages
  4. Use descriptive parameter names and include helpful descriptions

​
Have Questions?

We’re here to help! Choose the best way to reach us: