Tools

Tools extend LLM capabilities by allowing models to execute actions and retrieve information.

Built-in Tools

The SDK includes 6 built-in tools for common operations:

import { getBuiltinTools } from '@agentic-work/sdk/tools';

const tools = getBuiltinTools();
// [shellTool, readFileTool, writeFileTool, listFilesTool, deleteFileTool, searchTool]

Shell Tool

Execute shell commands:

import { shellTool } from '@agentic-work/sdk/tools';

// Tool definition
// name: 'shell'
// args: { command: string, workDir?: string }
// returns: stdout/stderr output

Read File Tool

Read file contents:

import { readFileTool } from '@agentic-work/sdk/tools';

// name: 'read_file'
// args: { path: string, encoding?: string }
// returns: file content as string

Write File Tool

Write or create files:

import { writeFileTool } from '@agentic-work/sdk/tools';

// name: 'write_file'
// args: { path: string, content: string }
// returns: success message with line count
// note: creates parent directories automatically

List Files Tool

List directory contents:

import { listFilesTool } from '@agentic-work/sdk/tools';

// name: 'list_files'
// args: { path?: string, recursive?: boolean }
// returns: file listing (max 100 files when recursive)

Delete File Tool

Delete files:

import { deleteFileTool } from '@agentic-work/sdk/tools';

// name: 'delete_file'
// args: { path: string }
// returns: deletion confirmation

Search Tool

Search files with regex:

import { searchTool } from '@agentic-work/sdk/tools';

// name: 'search'
// args: { pattern: string, path?: string, filePattern?: string }
// returns: grep-style results (max 10000 chars)

Creating Custom Tools

With Zod Schema

import { z } from 'zod';
import type { Tool } from '@agentic-work/sdk';

const weatherTool: Tool = {
  name: 'get_weather',
  description: 'Get current weather for a location',
  inputSchema: z.object({
    city: z.string().describe('City name'),
    units: z.enum(['celsius', 'fahrenheit']).default('celsius')
  }),
  execute: async (args, context) => {
    const { city, units } = args as { city: string; units: string };

    // Fetch weather data
    const response = await fetch(`https://api.weather.com/${city}`);
    const data = await response.json();

    return JSON.stringify({
      city,
      temperature: data.temp,
      units,
      conditions: data.conditions
    });
  }
};

With JSON Schema

const databaseTool: Tool = {
  name: 'query_database',
  description: 'Execute a SQL query',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'SQL query to execute' },
      database: { type: 'string', description: 'Database name' }
    },
    required: ['query']
  },
  execute: async (args) => {
    const { query, database } = args as { query: string; database?: string };
    // Execute query...
    return JSON.stringify({ rows: [], affected: 0 });
  }
};

Tool Interface

interface Tool extends ToolDefinition {
  execute: ToolExecutor;
}

interface ToolDefinition {
  name: string;
  description: string;
  inputSchema: z.ZodType<unknown> | Record<string, unknown>;
}

type ToolExecutor = (
  args: Record<string, unknown>,
  context: ToolContext
) => Promise<string>;

Tool Context

The execution context provides useful utilities:

interface ToolContext {
  workingDirectory: string;   // Current working directory
  signal: AbortSignal;        // For cancellation support
  onProgress?: (output: string) => void;  // Report progress
}

Using Context

const myTool: Tool = {
  name: 'long_task',
  description: 'A long-running task',
  inputSchema: z.object({ input: z.string() }),
  execute: async (args, context) => {
    // Check for cancellation
    if (context.signal.aborted) {
      throw new Error('Task cancelled');
    }

    // Report progress
    context.onProgress?.('Starting task...');
    await doStep1();

    context.onProgress?.('Step 1 complete, processing...');
    await doStep2();

    // Use working directory for file operations
    const outputPath = path.join(context.workingDirectory, 'output.txt');

    return 'Task complete';
  }
};

MCP Tools from Platform

Access platform MCP tools:

const aw = new AgenticWork({
  apiEndpoint: 'https://api.agenticwork.io',
  authToken: process.env.AGENTICWORK_TOKEN
});

await aw.init();

// Get all MCP tools
const mcpTools = aw.getMCPTools();

// Get MCP servers
const servers = await aw.getMCPServers();

// Execute a specific MCP tool directly
const result = await aw.executeMCPTool(
  'awp_web',      // server name
  'search',       // tool name
  { query: 'AI news' }  // arguments
);

Tool Result Format

Tools should return strings. For structured data, use JSON:

execute: async (args) => {
  const result = {
    success: true,
    data: { /* ... */ },
    metadata: { /* ... */ }
  };
  return JSON.stringify(result, null, 2);
}

Error Handling in Tools

Return errors as structured responses:

execute: async (args) => {
  try {
    // Tool logic...
    return JSON.stringify({ success: true, data: result });
  } catch (error) {
    return JSON.stringify({
      success: false,
      error: error.message
    });
  }
}

Or throw errors to be caught by the agent:

execute: async (args) => {
  if (!isValid(args)) {
    throw new Error('Invalid arguments provided');
  }
  // Tool logic...
}

Best Practices

1. Clear descriptions - Help the LLM understand when to use the tool

2. Typed schemas - Use Zod for runtime validation

3. Descriptive parameters - Add .describe() to Zod fields

4. Handle cancellation - Check context.signal.aborted for long tasks

5. Report progress - Use context.onProgress for visibility

6. Return JSON - Structure outputs for easy parsing

7. Handle errors gracefully - Return meaningful error messages