@minded-ai/mindedjs 1.0.19

package/docs/core-concepts/tools.md

@@ -0,0 +1,205 @@
+# Tools
+
+Tools are reusable functions that agents can call to perform specific actions like processing payments, sending emails, or updating databases.
+
+## Tool Structure
+
+Every tool must implement the `Tool` interface:
+
+```ts
+interface Tool<Input extends z.ZodSchema, Memory> {
+  name: string;           // Unique tool identifier
+  description: string;    // What the tool does (used by LLM)
+  input: Input;          // Zod schema for input validation
+  isGlobal?: boolean;    // Optional: available across all nodes
+  execute: ({ input, memory }) => Promise<{ memory?, result? }>;
+}
+```
+
+## Basic Tool Example
+
+Here's a simple refund processing tool:
+
+```ts
+import { z } from 'zod';
+import { Tool } from 'mindedjs/src/types/Tools.types';
+import memorySchema from '../schema';
+
+type Memory = z.infer<typeof memorySchema>;
+
+const schema = z.object({
+  orderId: z.string(),
+  customerName: z.string(),
+});
+
+const refundOrderTool: Tool<typeof schema, Memory> = {
+  name: 'refundOrder',
+  description: 'Process a customer refund for their order',
+  input: schema,
+  execute: async ({ input, memory }) => {
+    // Your business logic here
+    console.log(`Processing refund for order ${input.orderId}`);
+    
+    // Call external API, update database, etc.
+    const refundAmount = await processRefundInSystem(input.orderId);
+    
+    return {
+      memory: {
+        orderId: input.orderId,
+        customerName: input.customerName,
+        issue: `Refund processed: $${refundAmount}`,
+      },
+    };
+  },
+};
+
+export default refundOrderTool;
+```
+
+## Tool Registration
+
+### Global Tools
+
+Mark tools as global if you want them to be available in all LLM calls.
+
+```ts
+const auditLogTool: Tool<typeof auditSchema, Memory> = {
+  name: 'auditLog',
+  description: 'Log user action for compliance',
+  isGlobal: true, // Available in all flows
+  input: z.object({
+    action: z.string(),
+    details: z.string(),
+  }),
+  execute: async ({ input, memory }) => {
+    await auditService.log({
+      userId: memory.userId,
+      action: input.action,
+      details: input.details,
+      timestamp: new Date(),
+    });
+  },
+};
+```
+
+## Memory Management
+
+Tools can read and update memory state:
+
+```ts
+const updateProfileTool: Tool<typeof profileSchema, Memory> = {
+  name: 'updateProfile',
+  description: 'Update customer profile information',
+  input: z.object({
+    field: z.string(),
+    value: z.string(),
+  }),
+  execute: async ({ input, memory }) => {
+    // Read current memory
+    console.log(`Current customer: ${memory.customerName}`);
+    
+    // Update external system
+    await profileService.update(memory.customerId, {
+      [input.field]: input.value
+    });
+    
+    // Return updated memory
+    return {
+      memory: {
+        ...memory,
+        [`${input.field}Updated`]: true,
+      },
+    };
+  },
+};
+```
+
+## Error Handling
+
+Handle errors gracefully in tools:
+
+```ts
+const paymentTool: Tool<typeof paymentSchema, Memory> = {
+  name: 'processPayment',
+  description: 'Process customer payment',
+  input: z.object({
+    amount: z.number(),
+    cardToken: z.string(),
+  }),
+  execute: async ({ input, memory }) => {
+    try {
+      const result = await paymentService.charge({
+        amount: input.amount,
+        cardToken: input.cardToken,
+        customerId: memory.customerId,
+      });
+      
+      return {
+        result: `Payment successful: ${result.transactionId}`,
+        memory: { lastPaymentId: result.transactionId },
+      };
+    } catch (error) {
+      console.error('Payment failed:', error);
+      return {
+        result: 'Payment failed. Please try again or contact support.',
+        memory: { paymentError: error.message },
+      };
+    }
+  },
+};
+```
+
+## Best Practices
+
+1. **Clear Descriptions**: Write descriptions that help the LLM understand when to use the tool
+2. **Input Validation**: Use Zod schemas to validate all inputs
+3. **Memory Updates**: Update memory with relevant information for future tool calls
+4. **Error Handling**: Always handle errors gracefully and provide meaningful messages
+5. **Async Operations**: Use async/await for external API calls and database operations
+6. **Logging**: Log important actions for debugging and auditing
+
+## Tool Nodes
+
+Tool nodes force execution of specific tools at defined points in your flow, bypassing LLM decision-making.
+
+### Configuration
+
+```yaml
+nodes:
+  - name: 'Force Refund Processing'
+    type: 'tool'
+    toolName: 'refundOrder'
+```
+
+### Tool Node vs Automatic Tool Calls
+
+| Feature       | Tool Nodes                      | Automatic Tool Calls                |
+| ------------- | ------------------------------- | ----------------------------------- |
+| **Execution** | Guaranteed when node is reached | Only when LLM decides to call       |
+| **Control**   | Explicit flow control           | LLM-driven decision                 |
+| **Use Case**  | Required business logic steps   | Flexible, context-dependent actions |
+
+### Example
+
+```yaml
+nodes:
+  - name: 'Customer Support Start'
+    type: 'prompt'
+    prompt: 'How can I help you today?'
+  - name: 'Log Interaction'
+    type: 'tool'
+    toolName: 'auditLog'
+
+edges:
+  - source: 'Customer Support Start'
+    target: 'Log Interaction'
+    type: 'always'
+```
+
+### Best Practices
+
+1. **Strategic Placement**: Use for critical business logic that must always execute
+2. **Clear Context**: Ensure conversation provides context for parameter extraction
+3. **Error Handling**: Handle errors gracefully since they bypass LLM error recovery
+
+Tool parameters are automatically extracted from conversation context and memory state using an internal LLM agent.