1# Tools Index
2 
3Tools provide specific capabilities that agents can use to accomplish tasks.
4 
5## Tool Categories
6 
7### Evaluation Tools
8**Path**: `tools/evaluation/`
9 
10Tools for assessing LLM output quality.
11 
12| Tool | Purpose | Approval |
13|------|---------|----------|
14| `directScore` | Score response against criteria | No |
15| `pairwiseCompare` | Compare two responses | No |
16| `generateRubric` | Generate scoring rubric | No |
17| `extractCriteria` | Extract criteria from task | No |
18 
19---
20 
21### Research Tools
22**Path**: `tools/research/`
23 
24Tools for gathering and processing information.
25 
26| Tool | Purpose | Approval |
27|------|---------|----------|
28| `webSearch` | Search the web | No |
29| `readUrl` | Extract content from URL | No |
30| `extractClaims` | Identify claims in text | No |
31| `verifyClaim` | Cross-reference a claim | No |
32| `synthesize` | Combine findings | No |
33 
34---
35 
36### Orchestration Tools
37**Path**: `tools/orchestration/`
38 
39Tools for managing multi-agent workflows.
40 
41| Tool | Purpose | Approval |
42|------|---------|----------|
43| `delegateToAgent` | Route task to agent | No |
44| `parallelExecution` | Run tasks concurrently | No |
45| `waitForCompletion` | Wait for async tasks | No |
46| `synthesizeResults` | Combine agent outputs | No |
47| `handleError` | Manage failures | No |
48 
49## Tool Design Patterns
50 
51### Standard Tool Structure
52 
53```typescript
54export const toolName = tool({
55  description: "Clear description of what tool does",
56  
57  parameters: z.object({
58    // Required parameters first
59    requiredParam: z.string().describe("What this parameter is for"),
60    
61    // Optional parameters with defaults
62    optionalParam: z.number().default(10)
63      .describe("What this parameter controls")
64  }),
65  
66  // Approval for dangerous operations
67  needsApproval: false, // or true, or function
68  
69  // Strict mode for guaranteed schema compliance
70  strict: true,
71  
72  execute: async (input) => {
73    try {
74      const result = await performOperation(input);
75      return { success: true, data: result };
76    } catch (error) {
77      return {
78        success: false,
79        error: {
80          code: error.code ?? "UNKNOWN",
81          message: error.message,
82          retryable: isRetryable(error)
83        }
84      };
85    }
86  },
87  
88  // Optional: control what model sees
89  toModelOutput: (result) => ({
90    summary: result.data.summary,
91    truncated: result.data.full.length > 5000
92  })
93});
94```
95 
96### Error Response Pattern
97 
98```typescript
99interface ToolError {
100  code: string;       // Machine-readable error code
101  message: string;    // Human-readable message
102  retryable: boolean; // Whether retry might help
103  details?: object;   // Additional context
104}
105 
106interface ToolResult<T> {
107  success: boolean;
108  data?: T;
109  error?: ToolError;
110  metadata: {
111    executionTimeMs: number;
112    [key: string]: any;
113  };
114}
115```
116 
117## Adding New Tools
118 
1191. Determine category or create new: `tools/<category>/`
1202. Create tool file: `tools/<category>/<tool-name>.md`
1213. Define:
122   - Purpose and description
123   - Input parameters with Zod schema
124   - Output schema
125   - Error codes
126   - Usage examples
1274. Update this index
1285. Assign to relevant agents
129 
130## Tool Selection Guidelines
131 
132### When Agent Needs To...
133 
134| Action | Tool Category | Suggested Tools |
135|--------|---------------|-----------------|
136| Assess quality | Evaluation | directScore, pairwiseCompare |
137| Find information | Research | webSearch, readUrl |
138| Verify facts | Research | verifyClaim, extractClaims |
139| Coordinate work | Orchestration | delegateToAgent |
140| Wait for results | Orchestration | waitForCompletion |
141 
142