Tools

Tools extend what your agents can do beyond conversation. With tools, agents can remember information, make calculations, call APIs, and integrate with external services.

What Are Tools?

Tools are capabilities you give to agents. When an agent decides it needs to use a tool, it:

1. Decides which tool to use
2. Provides the required inputs
3. Receives the tool's output
4. Uses that output to respond

User: "What's 15% tip on $84.50?"

Agent thinks: "I should use the calculator tool"
[Tool: calculator, Input: "84.50 * 0.15"]
[Tool Output: 12.675]

Agent: "A 15% tip on $84.50 would be $12.68."

Built-in Tools

Deeployd provides several built-in tools:

Memory

Store and retrieve information across conversations.

// Enable memory tool
await client.agents.update({
  agentId: 'agent-123',
  tools: ['memory']
});

Capabilities:

• memory.get(key) - Retrieve stored value
• memory.set(key, value) - Store value
• memory.search(query) - Find relevant memories
• memory.delete(key) - Remove value

Example interaction:

User: "Remember that my laptop is a MacBook Pro M3"
Agent: [Tool: memory.set, Key: "user_laptop", Value: "MacBook Pro M3"]
       "Got it! I've noted that you use a MacBook Pro M3."

[Later conversation]
User: "What laptop do I use?"
Agent: [Tool: memory.get, Key: "user_laptop"]
       [Result: "MacBook Pro M3"]
       "You use a MacBook Pro M3."

Calculator

Perform mathematical calculations.

await client.agents.update({
  agentId: 'agent-123',
  tools: ['calculator']
});

Capabilities:

• Basic arithmetic: +, -, *, /
• Advanced: sqrt(), pow(), log(), sin(), cos()
• Constants: PI, E

Example:

User: "What's the compound interest on $10,000 at 5% for 3 years?"
Agent: [Tool: calculator, Input: "10000 * pow(1.05, 3)"]
       [Result: 11576.25]
       "The compound amount would be $11,576.25"

Current Time

Get the current date and time.

await client.agents.update({
  agentId: 'agent-123',
  tools: ['current_time']
});

Capabilities:

• Get current timestamp
• Specify timezone

Example:

User: "What time is it in Tokyo?"
Agent: [Tool: current_time, Timezone: "Asia/Tokyo"]
       [Result: "2024-01-15T22:30:00+09:00"]
       "It's currently 10:30 PM in Tokyo."

HTTP Request

Make HTTP requests to external APIs.

await client.agents.update({
  agentId: 'agent-123',
  tools: ['http_request'],
  toolConfig: {
    http_request: {
      allowedDomains: ['api.weather.com', 'api.acme.com'],
      timeout: 10000,
      maxRetries: 3
    }
  }
});

Capabilities:

• GET, POST, PUT, DELETE, PATCH
• Custom headers
• Request body (JSON)
• Response parsing

Example:

User: "What's the weather in San Francisco?"
Agent: [Tool: http_request
        Method: GET
        URL: "api.weather.com/v1/current?city=san-francisco"]
       [Result: { temp: 65, condition: "partly cloudy" }]
       "It's currently 65°F and partly cloudy in San Francisco."

Integration Tools

Google Workspace Admin

Manage Google Workspace users and groups.

await client.agents.update({
  agentId: 'agent-123',
  tools: [
    'google_admin_create_user',
    'google_admin_list_users',
    'google_admin_create_group',
    'google_admin_add_to_group',
    'google_admin_list_skus',
    'google_admin_assign_license',
    'google_admin_revoke_license'
  ]
});

Example:

User: "Create a new user for John Smith in the Sales department"
Agent: [Tool: google_admin_create_user
        Email: "john.smith@acme.com"
        FirstName: "John"
        LastName: "Smith"
        OrgUnit: "/Sales"]
       "I've created a Google Workspace account for John Smith
        (john.smith@acme.com) in the Sales department."

Microsoft 365 Admin

Manage Microsoft 365 users, groups, and licenses.

await client.agents.update({
  agentId: 'agent-123',
  tools: [
    'ms_admin_create_user',
    'ms_admin_list_users',
    'ms_admin_create_group',
    'ms_admin_add_to_group',
    'ms_admin_list_licenses',
    'ms_admin_assign_license',
    'ms_admin_revoke_license',
    'ms_admin_get_user_licenses'
  ]
});

Platform Tools

Interact with the Deeployd platform itself.

await client.agents.update({
  agentId: 'agent-123',
  tools: [
    'platform_list_agents',
    'platform_create_agent',
    'platform_list_templates',
    'platform_create_tool',
    'platform_get_workspace_info',
    'platform_get_user_context',
    'platform_list_tasks',
    'platform_create_task',
    'platform_run_task'
  ]
});

Example:

User: "Create a new agent for handling billing questions"
Agent: [Tool: platform_create_agent
        Name: "Billing Support"
        SystemPrompt: "You are a billing support agent..."]
       "I've created a new Billing Support agent. Would you like
        me to configure its tools and integrations?"

Custom Tools

Create tools that call your own APIs.

Creating a Custom Tool

const tool = await client.tools.create({
  name: 'lookup_order',
  description: 'Look up order details by order ID',
  parameters: {
    type: 'object',
    properties: {
      orderId: {
        type: 'string',
        description: 'The order ID to look up'
      }
    },
    required: ['orderId']
  },
  endpoint: {
    url: 'https://api.acme.com/orders/{orderId}',
    method: 'GET',
    headers: {
      'Authorization': 'Bearer {{env.ACME_API_KEY}}'
    }
  }
});

// Add to agent
await client.agents.update({
  agentId: 'agent-123',
  tools: ['lookup_order']
});

Tool Parameters

Define what inputs the tool accepts:

parameters: {
  type: 'object',
  properties: {
    email: {
      type: 'string',
      description: 'Customer email address',
      format: 'email'
    },
    status: {
      type: 'string',
      description: 'Order status filter',
      enum: ['pending', 'shipped', 'delivered', 'cancelled']
    },
    limit: {
      type: 'integer',
      description: 'Maximum results to return',
      default: 10,
      minimum: 1,
      maximum: 100
    }
  },
  required: ['email']
}

Tool Responses

Transform API responses for better agent understanding:

const tool = await client.tools.create({
  name: 'get_inventory',
  // ... other config
  responseTransform: {
    // Map API response to agent-friendly format
    template: `
      Product: {{product_name}}
      In Stock: {{quantity}}
      Location: {{warehouse}}
      Status: {{#if (gt quantity 0)}}Available{{else}}Out of Stock{{/if}}
    `
  }
});

Tool Configuration

Allowed Domains

Restrict which URLs tools can access:

toolConfig: {
  http_request: {
    allowedDomains: [
      'api.acme.com',
      '*.acme.com',  // Wildcard subdomain
      'api.stripe.com'
    ],
    blockedDomains: [
      'internal.acme.com'  // Block specific subdomain
    ]
  }
}

Authentication

Inject credentials into tool calls:

toolConfig: {
  http_request: {
    defaultHeaders: {
      'Authorization': 'Bearer {{env.API_KEY}}',
      'X-Tenant-ID': '{{tenant.id}}'
    }
  }
}

Rate Limiting

Control how often tools can be called:

toolConfig: {
  http_request: {
    rateLimit: {
      maxRequests: 10,
      windowSeconds: 60
    }
  }
}

Timeouts

Set execution time limits:

toolConfig: {
  http_request: {
    timeout: 10000,  // 10 seconds
    maxRetries: 3,
    retryDelay: 1000  // 1 second between retries
  }
}

Tool Selection

The agent decides when to use tools based on context:

Good Tool Selection

User: "What's the square root of 144?"
Agent: [Uses calculator tool] → "The square root of 144 is 12."

User: "Remember my employee ID is E12345"
Agent: [Uses memory tool] → "I've saved your employee ID."

Guiding Tool Selection

Help the agent know when to use tools:

In your system prompt:

When to use the calculator tool:
- Any mathematical calculations
- Currency conversions
- Percentage calculations

When to use the lookup_order tool:
- When user asks about order status
- When user provides an order number
- When troubleshooting delivery issues

When NOT to use tools:
- Simple greetings and conversation
- Questions you can answer from knowledge
- Clarifying questions to the user

Error Handling

Tool Failures

Handle when tools don't work:

// In system prompt:
If a tool fails:
- Acknowledge the issue to the user
- Try an alternative approach if available
- Offer to create a ticket for manual resolution
- Never make up data or guess

Graceful Degradation

User: "What's my order status for #12345?"
Agent: [Tool: lookup_order, OrderId: "12345"]
       [Error: API timeout]

       "I'm having trouble looking up that order right now.
        Let me create a ticket so our team can check on it
        and get back to you. In the meantime, you can check
        status at orders.acme.com/track"

Best Practices

1. Minimal Tools

Only enable tools the agent needs:

// ❌ Bad: Every tool enabled
tools: ['memory', 'calculator', 'http_request', 'google_admin',
        'ms_admin', 'platform_tools', ...]

// ✅ Good: Only what's needed
tools: ['memory', 'lookup_order', 'create_ticket']

2. Clear Descriptions

Write tool descriptions the agent can understand:

// ❌ Bad
description: 'Gets order'

// ✅ Good
description: 'Retrieves detailed information about a customer order including status, items, shipping details, and delivery estimate. Use when a customer asks about their order.'

3. Secure Configuration

Never expose sensitive data:

// ❌ Bad: Hardcoded secrets
headers: { 'Authorization': 'Bearer sk_live_abc123' }

// ✅ Good: Environment variables
headers: { 'Authorization': 'Bearer {{env.STRIPE_API_KEY}}' }

4. Test Thoroughly

Test tools in isolation and integrated:

// Test tool directly
const result = await client.tools.test({
  toolId: 'lookup_order',
  input: { orderId: 'TEST-123' }
});

// Test via agent
const response = await client.agents.chat({
  agentId: 'agent-123',
  message: 'What is the status of order TEST-123?'
});

---

Next: Learn about Conversations to understand how agents maintain dialogue context.