Tools

The Agent SDK provides built-in tools for common agent capabilities and a defineTool() helper for creating custom tools with full TypeScript type inference.

Built-in Tools

All built-in tools are enabled by default and can be toggled via features in AgentConfig.

Memory Tools

Store and recall user-specific information across conversations.

Memory entries are persisted in the user's workspace and automatically injected into the system prompt. Secret entries are hidden from debug output.

features: {
	memory: true;
} // default

Artifact Tool

Create files and send them to the user.

Files are stored under {userId}/{filename} in the FILES binding.

features: {
	artifacts: true;
} // default

Scheduling Tool

Schedule tasks for future execution.

When the scheduled time arrives, the SDK triggers a new workflow run with the task description injected as a user message.

features: {
	scheduling: true;
} // default

MCP Tool

Call tools provided by installed MCP (Model Context Protocol) servers.

Only available when at least one MCP server is installed in the user's workspace. See Commands for how users install MCP servers.

features: {
	mcp: true;
} // default

Custom Tools with defineTool()

defineTool() creates a type-safe tool definition where the execute function's args parameter is automatically typed from the JSON Schema parameters object.

Basic Example

import { defineTool } from "@meetploy/agent-sdk";

const searchTool = defineTool({
	name: "search",
	description: "Search for information",
	parameters: {
		type: "object",
		properties: {
			query: { type: "string", description: "Search query" },
			limit: { type: "number", description: "Max results" },
		},
		required: ["query"],
	},
	async execute(args, ctx) {
		// args.query: string (required)
		// args.limit?: number (optional -- not in required array)
		const results = await doSearch(args.query, args.limit ?? 10);
		return JSON.stringify(results);
	},
});

Type Inference

defineTool() uses TypeScript's const generic inference to map JSON Schema types to TypeScript types:

Properties listed in required are required; all others are optional (?).

ToolContext

The ctx parameter in execute provides access to user context and platform bindings:

interface ToolContext {
	userId: string; // Current user ID
	chatId: string; // Current chat ID
	env: PloyEnv; // Full Ploy environment bindings
	state: StateManager; // Key-value state (get/set/delete/getJSON/setJSON)
	messenger: Messenger; // Platform messenger
}

Using ToolDefinition Directly

If you prefer to type args manually instead of using defineTool(), use ToolDefinition<T>:

import type { ToolDefinition } from "@meetploy/agent-sdk";

const myTool: ToolDefinition<{ city: string; units?: string }> = {
	name: "get_weather",
	description: "Get weather for a city",
	parameters: {
		type: "object",
		properties: {
			city: { type: "string" },
			units: { type: "string" },
		},
		required: ["city"],
	},
	async execute(args, ctx) {
		// args is { city: string; units?: string }
		return `Weather in ${args.city}`;
	},
};

Next Steps

• createAgent() -- Pass tools via the tools config option
• Hooks -- React when tools create artifacts or schedule tasks
• State & Workspaces -- Access state from within tool execute functions