Tools API

The Tools API provides access to the specialized tools and capabilities available to agents. Agents use tools to interact with external systems, process data, and deliver results.

Base URL

https://api.do/agents/tools

Overview

Agent tools include:

Development Tools - IDEs, version control, CI/CD
Data Tools - Databases, analytics, visualization
Communication Tools - Email, Slack, calendars
Research Tools - Web search, knowledge bases
Creative Tools - Design, editing, generation
Integration Tools - APIs, webhooks, connectors

Endpoints

List Available Tools

Get a list of all available tools.

GET /agents/tools

Query Parameters

Parameter	Type	Required	Description
`category`	string	No	Filter by category
`agentId`	string	No	Filter by agent access
`search`	string	No	Search by name or description
`limit`	number	No	Max results (default: 50)
`offset`	number	No	Pagination offset

Example Request

curl -X GET "https://api.do/agents/tools?category=development" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "tools": [
      {
        "id": "github",
        "name": "GitHub",
        "category": "development",
        "description": "Version control, code review, CI/CD",
        "capabilities": ["clone-repository", "create-pr", "review-code", "manage-issues", "run-actions"],
        "agents": ["tom", "cody", "quinn"],
        "authentication": "oauth",
        "documentation": "https://docs.do/tools/github"
      },
      {
        "id": "docker",
        "name": "Docker",
        "category": "development",
        "description": "Containerization and deployment",
        "capabilities": ["build-image", "run-container", "push-registry", "compose-services"],
        "agents": ["tom", "dev", "cody"],
        "authentication": "api-key",
        "documentation": "https://docs.do/tools/docker"
      }
    ],
    "total": 87,
    "categories": ["development", "data", "communication", "research", "creative", "integration"]
  },
  "metadata": {
    "requestId": "req_tools123",
    "timestamp": "2024-10-27T18:00:00Z"
  }
}

Get Tool Details

Get detailed information about a specific tool.

GET /agents/tools/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Tool identifier

Example Request

curl -X GET "https://api.do/agents/tools/github" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "id": "github",
    "name": "GitHub",
    "category": "development",
    "description": "Complete GitHub integration for code management, collaboration, and CI/CD",
    "capabilities": [
      {
        "id": "clone-repository",
        "name": "Clone Repository",
        "description": "Clone a repository locally",
        "parameters": [
          { "name": "url", "type": "string", "required": true },
          { "name": "branch", "type": "string", "required": false }
        ]
      },
      {
        "id": "create-pr",
        "name": "Create Pull Request",
        "description": "Create a new pull request",
        "parameters": [
          { "name": "repo", "type": "string", "required": true },
          { "name": "title", "type": "string", "required": true },
          { "name": "description", "type": "string", "required": false },
          { "name": "base", "type": "string", "required": true },
          { "name": "head", "type": "string", "required": true }
        ]
      },
      {
        "id": "review-code",
        "name": "Review Code",
        "description": "Review code changes and provide feedback",
        "parameters": [
          { "name": "repo", "type": "string", "required": true },
          { "name": "pr", "type": "number", "required": true },
          { "name": "comments", "type": "array", "required": false }
        ]
      }
    ],
    "agents": [
      { "agentId": "tom", "proficiency": "expert" },
      { "agentId": "cody", "proficiency": "expert" },
      { "agentId": "quinn", "proficiency": "advanced" }
    ],
    "authentication": {
      "type": "oauth",
      "scopes": ["repo", "workflow", "write:discussion"]
    },
    "rateLimit": {
      "requests": 5000,
      "period": "hour"
    },
    "documentation": "https://docs.do/tools/github",
    "pricing": {
      "model": "usage",
      "free": 1000,
      "overage": 0.01
    }
  },
  "metadata": {
    "requestId": "req_tools124",
    "timestamp": "2024-10-27T18:00:00Z"
  }
}

Invoke Tool

Invoke a tool directly (for testing or direct use).

POST /agents/tools/:id/invoke

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Tool identifier

Request Body

Field	Type	Required	Description
`capability`	string	Yes	Capability to invoke
`parameters`	object	Yes	Capability parameters
`agentId`	string	No	Agent invoking (for permissions)

Example Request

curl -X POST "https://api.do/agents/tools/github/invoke" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "create-pr",
    "parameters": {
      "repo": "org/platform",
      "title": "Add new feature",
      "description": "Implements feature X with tests",
      "base": "main",
      "head": "feature/new-feature"
    },
    "agentId": "tom"
  }'

Example Response

{
  "success": true,
  "data": {
    "result": {
      "pr": {
        "number": 1234,
        "url": "https://github.com/org/platform/pull/1234",
        "title": "Add new feature",
        "state": "open",
        "createdAt": "2024-10-27T18:00:00Z"
      }
    },
    "usage": {
      "toolId": "github",
      "capability": "create-pr",
      "cost": 0.01,
      "duration": "1.2s"
    }
  },
  "metadata": {
    "requestId": "req_tools125",
    "timestamp": "2024-10-27T18:00:00Z"
  }
}

Get Agent Tool Access

Get tools available to a specific agent.

GET /agents/tools/access/:agentId

Path Parameters

Parameter	Type	Required	Description
`agentId`	string	Yes	Agent identifier

Example Request

curl -X GET "https://api.do/agents/tools/access/tom" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "agentId": "tom",
    "agentName": "Tom",
    "tools": [
      {
        "id": "github",
        "name": "GitHub",
        "proficiency": "expert",
        "capabilities": ["clone-repository", "create-pr", "review-code"]
      },
      {
        "id": "docker",
        "name": "Docker",
        "proficiency": "expert",
        "capabilities": ["build-image", "run-container", "push-registry"]
      },
      {
        "id": "postgresql",
        "name": "PostgreSQL",
        "proficiency": "advanced",
        "capabilities": ["query", "design-schema", "optimize"]
      }
    ],
    "totalTools": 23
  },
  "metadata": {
    "requestId": "req_tools126",
    "timestamp": "2024-10-27T18:00:00Z"
  }
}

Grant Tool Access

Grant an agent access to a tool.

POST /agents/tools/access

Request Body

Field	Type	Required	Description
`agentId`	string	Yes	Agent identifier
`toolId`	string	Yes	Tool identifier
`proficiency`	string	No	Proficiency level
`capabilities`	string[]	No	Allowed capabilities

Example Request

curl -X POST "https://api.do/agents/tools/access" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "amy",
    "toolId": "tableau",
    "proficiency": "advanced",
    "capabilities": ["create-dashboard", "analyze-data", "export-report"]
  }'

Revoke Tool Access

Revoke an agent's access to a tool.

DELETE /agents/tools/access/:agentId/:toolId

Path Parameters

Parameter	Type	Required	Description
`agentId`	string	Yes	Agent identifier
`toolId`	string	Yes	Tool identifier

Tool Categories

Development Tools

Git/GitHub - Version control and collaboration

Docker - Containerization and deployment

CI/CD - Continuous integration and deployment

IDE - Integrated development environments

Testing Frameworks - Unit, integration, E2E testing

Data Tools

PostgreSQL - Relational database

MongoDB - NoSQL database

Redis - In-memory cache

SQL - Database queries

Pandas - Data analysis (Python)

Excel - Spreadsheet analysis

Tableau - Data visualization

Communication Tools

Email - Send and receive email

Slack - Team messaging

Calendar - Schedule meetings

Zoom - Video conferencing

Twilio - SMS/voice

Research Tools

Web Search - Google, Bing search

Knowledge Base - Internal knowledge

Wikipedia - General knowledge

Research Papers - Academic databases

News APIs - Current events

Creative Tools

Figma - Design and prototyping

Photoshop - Image editing

Video Editing - Video production

Content Generation - AI writing tools

Integration Tools

Stripe - Payments

Salesforce - CRM

HubSpot - Marketing automation

Zapier - Workflow automation

Webhooks - Event notifications

REST APIs - General API access

TypeScript SDK Example

import { $ } from 'sdk.do'

// List available tools
const tools = await $.Tool.list({
  category: 'development',
})

// Get tool details
const github = await $.Tool.get('github')

// Invoke tool directly
const pr = await $.Tool.invoke({
  toolId: 'github',
  capability: 'create-pr',
  parameters: {
    repo: 'org/platform',
    title: 'Add new feature',
    base: 'main',
    head: 'feature/new',
  },
  agentId: 'tom',
})

// Get agent's tools
const tomTools = await $.Tool.getAgentAccess('tom')

// Grant access
await $.Tool.grantAccess({
  agentId: 'amy',
  toolId: 'tableau',
  proficiency: 'advanced',
})

// Revoke access
await $.Tool.revokeAccess('amy', 'tableau')

Python SDK Example

from do_sdk import Tool

# List available tools
tools = Tool.list(category='development')

# Get tool details
github = Tool.get('github')

# Invoke tool
pr = Tool.invoke(
    tool_id='github',
    capability='create-pr',
    parameters={
        'repo': 'org/platform',
        'title': 'Add new feature',
        'base': 'main',
        'head': 'feature/new'
    },
    agent_id='tom'
)

# Get agent's tools
tom_tools = Tool.get_agent_access('tom')

CLI Example

# List tools
do tool list --category development

# Get tool details
do tool get github

# Invoke tool
do tool invoke github create-pr \
  --repo org/platform \
  --title "Add feature" \
  --base main \
  --head feature/new

# Get agent tools
do tool access tom

# Grant access
do tool grant amy tableau --proficiency advanced

# Revoke access
do tool revoke amy tableau

Best Practices

1. Use Appropriate Tools

Match tools to task requirements:

// Good: Use GitHub for code work
const task = await $.Task.create({
  task: 'Review pull request',
  agentId: 'tom',
  context: {
    tools: ['github'],
  },
})

// Good: Use data tools for analysis
const task = await $.Task.create({
  task: 'Analyze sales data',
  agentId: 'amy',
  context: {
    tools: ['postgresql', 'excel', 'tableau'],
  },
})

2. Verify Agent Proficiency

Check agent's tool proficiency before assignment:

const agentTools = await $.Tool.getAgentAccess('tom')
const githubTool = agentTools.tools.find((t) => t.id === 'github')

if (githubTool && githubTool.proficiency === 'expert') {
  // Tom is expert with GitHub, safe to assign complex tasks
  await $.Task.create({
    task: 'Complex GitHub workflow automation',
    agentId: 'tom',
  })
}

3. Handle Tool Errors

Implement error handling for tool invocations:

try {
  const result = await $.Tool.invoke({
    toolId: 'github',
    capability: 'create-pr',
    parameters: {
      /* ... */
    },
  })
} catch (error) {
  if (error.code === 'RATE_LIMIT_EXCEEDED') {
    // Wait and retry
    await new Promise((resolve) => setTimeout(resolve, 60000))
    // Retry...
  } else if (error.code === 'AUTHENTICATION_FAILED') {
    // Re-authenticate
  }
}

4. Monitor Tool Usage

Track tool usage for cost control:

const usage = await $.Tool.getUsage({
  toolId: 'github',
  period: 'month',
})

console.log(`GitHub API calls: ${usage.calls}`)
console.log(`Cost: $${usage.cost}`)

if (usage.calls > usage.limit * 0.8) {
  console.warn('Approaching rate limit!')
}

Agents API Overview - Complete API overview
Named Agents - Individual agents
Tasks API - Task management
Integrations - External integrations

Support

Documentation - docs.do
API Status - status.do
Community - Discord
Support - support@do

Tools API

On this page