Tools Index

Tools provide specific capabilities that agents can use to accomplish tasks.

Tool Categories

Evaluation Tools

Path: tools/evaluation/

Tools for assessing LLM output quality.

Research Tools

Path: tools/research/

Tools for gathering and processing information.

Orchestration Tools

Path: tools/orchestration/

Tools for managing multi-agent workflows.

Tool Design Patterns

Standard Tool Structure

export const toolName = tool({
  description: "Clear description of what tool does",
  
  parameters: z.object({
    // Required parameters first
    requiredParam: z.string().describe("What this parameter is for"),
    
    // Optional parameters with defaults
    optionalParam: z.number().default(10)
      .describe("What this parameter controls")
  }),
  
  // Approval for dangerous operations
  needsApproval: false, // or true, or function
  
  // Strict mode for guaranteed schema compliance
  strict: true,
  
  execute: async (input) => {
    try {
      const result = await performOperation(input);
      return { success: true, data: result };
    } catch (error) {
      return {
        success: false,
        error: {
          code: error.code ?? "UNKNOWN",
          message: error.message,
          retryable: isRetryable(error)
        }
      };
    }
  },
  
  // Optional: control what model sees
  toModelOutput: (result) => ({
    summary: result.data.summary,
    truncated: result.data.full.length > 5000
  })
});

Error Response Pattern

interface ToolError {
  code: string;       // Machine-readable error code
  message: string;    // Human-readable message
  retryable: boolean; // Whether retry might help
  details?: object;   // Additional context
}

interface ToolResult<T> {
  success: boolean;
  data?: T;
  error?: ToolError;
  metadata: {
    executionTimeMs: number;
    [key: string]: any;
  };
}

Adding New Tools

1. Determine category or create new: tools/<category>/
2. Create tool file: tools/<category>/<tool-name>.md
3. Define:

• Purpose and description
• Input parameters with Zod schema
• Output schema
• Error codes
• Usage examples

1. Update this index
2. Assign to relevant agents

Tool Selection Guidelines

When Agent Needs To...