Tools overview

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/lvndry/jazz/llms.txt

Use this file to discover all available pages before exploring further.

​

Tool categories

• Filesystem - Read, write, search, and manipulate files and directories
• Git - Version control operations (status, commit, diff, log, etc.)
• Shell - Execute arbitrary shell commands with safety checks
• Web search - Search the web using multiple providers (Brave, Perplexity, Exa, etc.)
• HTTP - Make HTTP requests with full control over method, headers, and body
• MCP - Connect to Model Context Protocol servers and use their tools

​

Tool architecture

​

Base tool types

1. Standard tools - Execute immediately when called
2. Approval tools - Require user confirmation before execution

​

Approval tools

• Approval request - Shows the user what will happen and waits for confirmation
• Execution - Performs the actual operation after approval

• File write operations (write_file, edit_file)
• Git modifications (git_add, git_commit, git_push)
• Shell command execution (execute_command)

​

Tool validation

• Type safety at runtime
• Clear error messages for invalid inputs
• Automatic parameter documentation

​

Effect-based execution

• Composable error handling
• Dependency injection
• Type-safe side effects
• Testability

​

Tool naming conventions

• Filesystem tools use action names: read_file, write_file, ls, grep, find
• Git tools are prefixed: git_status, git_commit, git_diff
• Shell tool: execute_command
• Web search: web_search
• HTTP: http_request
• MCP tools are prefixed with server name: mcp_<server>_<tool>

​

Security features

​

Input validation

const parameters = z
  .object({
    path: z.string().min(1).describe("File path to read"),
    startLine: z.number().int().positive().optional(),
    endLine: z.number().int().positive().optional(),
  })
  .strict();

​

Command filtering

• System modification (rm -rf, sudo, shutdown)
• Code execution via pipes (curl | bash)
• Process manipulation (kill -9, pkill)
• File permission changes (chmod 777)

​

Path resolution

• Path traversal attacks
• Access outside working directory
• Symlink exploitation

​

Resource limits

• File reads: Max 512KB per read
• Search results: Default 200, cap 2000
• Diff output: Default 500 lines, cap 2000
• Command timeout: Default 15 minutes
• HTTP timeout: Default 15 seconds
• HTTP response size: Default 1MB, cap 5MB

​

Error handling

export class FileNotFoundError extends Data.TaggedError("FileNotFoundError")<{
  readonly path: string;
}> {
  override get message() {
    return `File does not exist: ${this.path}`;
  }
}

• Programmatic error discrimination
• Type-safe error matching
• Rich error context
• Actionable error messages

​

Tool registration

import { fs } from "./tools/fs";
import { git } from "./tools/git";

// Register read-only tools
yield* registerTool(fs.read());
yield* registerTool(git.status());

// Register approval tools (both approval and execute)
const writeTools = fs.write();
yield* registerTool(writeTools.approval);
yield* registerTool(writeTools.execute);

​

Creating custom tools

import { defineTool } from "@/core/agent/tools/base-tool";
import { z } from "zod";

export function createMyTool() {
  return defineTool({
    name: "my_tool",
    description: "Does something useful",
    tags: ["custom"],
    parameters: z.object({
      input: z.string().describe("Input parameter"),
    }).strict(),
    handler: (args, context) =>
      Effect.gen(function* () {
        // Tool implementation
        return {
          success: true,
          result: { output: "result" },
        };
      }),
  });
}

​

Next steps