1# Agent Tool Design Skill
2 
3## Overview
4 
5Tools are the foundation of an agent's capabilities. An agent's ability to take meaningful actions depends entirely on how reliably it can generate valid tool inputs, how well those inputs align with user intent, and how effectively tool outputs inform next steps.
6 
7## Design Principles
8 
9### 1. Single Responsibility
10 
11Each tool should do one thing well. Complex operations should be composed from multiple tools.
12 
13```typescript
14// Bad: Tool does too much
15const analyzeAndSummarizeAndSend = { ... }
16 
17// Good: Separate concerns
18const analyzeDocument = { ... }
19const summarizeContent = { ... }
20const sendEmail = { ... }
21```
22 
23### 2. Clear Input Schemas
24 
25Use explicit, validated schemas with descriptive field names and constraints.
26 
27```typescript
28const searchTool = tool({
29  description: "Search for documents by semantic similarity",
30  parameters: z.object({
31    query: z.string().describe("Natural language search query"),
32    limit: z.number().min(1).max(100).default(10)
33      .describe("Maximum number of results to return"),
34    filters: z.object({
35      dateAfter: z.string().optional()
36        .describe("ISO date string, only return docs after this date"),
37      source: z.enum(["internal", "external", "all"]).default("all")
38    }).optional()
39  }),
40  execute: async (input) => { ... }
41});
42```
43 
44### 3. Predictable Output Structure
45 
46Return consistent, typed output that the model can reliably parse.
47 
48```typescript
49interface ToolResult<T> {
50  success: boolean;
51  data?: T;
52  error?: {
53    code: string;
54    message: string;
55    retryable: boolean;
56  };
57  metadata: {
58    executionTimeMs: number;
59    source?: string;
60  };
61}
62```
63 
64### 4. Graceful Error Handling
65 
66Tools should never throw unhandled exceptions. Always return structured errors.
67 
68```typescript
69execute: async (input) => {
70  try {
71    const result = await performAction(input);
72    return { success: true, data: result };
73  } catch (error) {
74    return {
75      success: false,
76      error: {
77        code: error.code ?? "UNKNOWN_ERROR",
78        message: error.message,
79        retryable: isRetryable(error)
80      }
81    };
82  }
83}
84```
85 
86## Tool Categories
87 
88### Read-Only Tools
89- Database queries
90- API fetches
91- File reads
92- Search operations
93 
94Safe to execute without approval. Return data but don't mutate state.
95 
96### State-Modifying Tools
97- Database writes
98- File modifications
99- API POST/PUT/DELETE
100- System configuration changes
101 
102May require human approval. Consider `needsApproval` flag.
103 
104### Dangerous Tools
105- File deletion
106- Payment processing
107- Production deployments
108- Sending external communications
109 
110Should always require approval and audit logging.
111 
112## AI SDK 6 Tool Features
113 
114### Tool Execution Approval
115```typescript
116const deleteTool = tool({
117  description: "Delete a file from the system",
118  parameters: z.object({
119    path: z.string()
120  }),
121  needsApproval: true, // Requires human approval
122  execute: async ({ path }) => { ... }
123});
124 
125// Dynamic approval based on input
126const commandTool = tool({
127  description: "Execute a shell command",
128  parameters: z.object({
129    command: z.string()
130  }),
131  needsApproval: ({ command }) => {
132    return command.includes("rm") || command.includes("delete");
133  },
134  execute: async ({ command }) => { ... }
135});
136```
137 
138### Strict Mode
139Enable native strict mode for guaranteed schema compliance:
140```typescript
141const strictTool = tool({
142  description: "...",
143  parameters: schema,
144  strict: true, // Enable strict mode
145  execute: async (input) => { ... }
146});
147```
148 
149### Input Examples
150Help the model understand expected input format:
151```typescript
152const complexTool = tool({
153  description: "Create a calendar event",
154  parameters: eventSchema,
155  inputExamples: [
156    {
157      title: "Team Standup",
158      date: "2024-01-15",
159      time: "09:00",
160      duration: 30,
161      attendees: ["[email protected]", "[email protected]"]
162    }
163  ],
164  execute: async (input) => { ... }
165});
166```
167 
168### toModelOutput
169Control what gets sent back to the model:
170```typescript
171const readFileTool = tool({
172  description: "Read file contents",
173  parameters: z.object({ path: z.string() }),
174  execute: async ({ path }) => {
175    const content = await fs.readFile(path, 'utf-8');
176    return { path, content, size: content.length };
177  },
178  toModelOutput: (result) => {
179    // Only send truncated content to model
180    return {
181      path: result.path,
182      content: result.content.slice(0, 5000),
183      truncated: result.content.length > 5000
184    };
185  }
186});
187```
188 
189## Best Practices
190 
1911. **Descriptive Names**: Tool names should clearly indicate their function
1922. **Comprehensive Descriptions**: Include usage examples in tool descriptions
1933. **Reasonable Defaults**: Provide sensible defaults for optional parameters
1944. **Idempotency**: Design tools to be safely re-executable when possible
1955. **Timeout Handling**: Implement timeouts for external operations
1966. **Rate Limiting**: Protect against runaway tool execution
1977. **Logging**: Log all tool invocations for debugging and audit
198 
199