> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plaisolutions.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> API endpoints for managing tools that extend agent capabilities

## List Tools

<api-endpoint method="GET" path="/tools" />

List all tools available in the current project.

### Response

<ResponseField name="tools" type="array">
  Array of tool objects

  <Expandable title="Tool Object">
    <ResponseField name="id" type="string">
      Tool unique identifier
    </ResponseField>

    <ResponseField name="name" type="string">
      Tool name
    </ResponseField>

    <ResponseField name="name_slug" type="string">
      URL-friendly tool name
    </ResponseField>

    <ResponseField name="type" type="string">
      Tool type (BROWSER, HTTP, PERPLEXITY, EXTERNAL\_DATASOURCE, REMOTE\_MCP\_SERVER)
    </ResponseField>

    <ResponseField name="description" type="string">
      Tool description
    </ResponseField>

    <ResponseField name="config" type="object">
      Tool-specific configuration settings
    </ResponseField>

    <ResponseField name="project_id" type="string">
      ID of the project this tool belongs to
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the tool was created (ISO 8601 format)
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      When the tool was last updated (ISO 8601 format)
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request GET 'https://api.plaisolutions.com/tools' \
  --header 'Authorization: Bearer YOUR_TOKEN'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.plaisolutions.com/tools', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    }
  });

  const tools = await response.json();
  console.log(tools);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.plaisolutions.com/tools"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
  }

  response = requests.get(url, headers=headers)
  tools = response.json()
  print(tools)
  ```
</CodeGroup>

***

## Create Tool

<api-endpoint method="POST" path="/tools" />

Create a new tool to extend agent capabilities.

### Request Body

<ParamField body="name" type="string" required>
  Tool name
</ParamField>

<ParamField body="type" type="string" required>
  Tool type:

  * `BROWSER` - Web browsing and interaction capabilities
  * `HTTP` - HTTP API requests and integrations
  * `PERPLEXITY` - Perplexity AI search integration
  * `EXTERNAL_DATASOURCE` - External data source connections
  * `REMOTE_MCP_SERVER` - Model Context Protocol server integration
</ParamField>

<ParamField body="description" type="string" optional>
  Tool description (default: "")
</ParamField>

<ParamField body="config" type="object" optional>
  Tool-specific configuration (default: {})
</ParamField>

### Response

Returns the created tool object.

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request POST 'https://api.plaisolutions.com/tools' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Web Search Tool",
    "type": "HTTP",
    "description": "Tool for searching the web and retrieving information",
    "config": {
      "base_url": "https://api.search.example.com",
      "api_key_required": true,
      "rate_limit": 100
    }
  }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.plaisolutions.com/tools', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: "Web Search Tool",
      type: "HTTP",
      description: "Tool for searching the web and retrieving information",
      config: {
        base_url: "https://api.search.example.com",
        api_key_required: true,
        rate_limit: 100
      }
    })
  });

  const tool = await response.json();
  console.log(tool);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.plaisolutions.com/tools"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
  }
  data = {
      "name": "Web Search Tool",
      "type": "HTTP",
      "description": "Tool for searching the web and retrieving information",
      "config": {
          "base_url": "https://api.search.example.com",
          "api_key_required": True,
          "rate_limit": 100
      }
  }

  response = requests.post(url, headers=headers, json=data)
  tool = response.json()
  print(tool)
  ```
</CodeGroup>

***

## Get Tool

<api-endpoint method="GET" path="/tools/{id}" />

Get detailed information about a specific tool.

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the tool
</ParamField>

### Response

Returns the tool object with all configuration details.

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request GET 'https://api.plaisolutions.com/tools/tool_123' \
  --header 'Authorization: Bearer YOUR_TOKEN'
  ```

  ```javascript JavaScript theme={null}
  const toolId = 'tool_123';
  const response = await fetch(`https://api.plaisolutions.com/tools/${toolId}`, {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    }
  });

  const tool = await response.json();
  console.log(tool);
  ```

  ```python Python theme={null}
  import requests

  tool_id = "tool_123"
  url = f"https://api.plaisolutions.com/tools/{tool_id}"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
  }

  response = requests.get(url, headers=headers)
  tool = response.json()
  print(tool)
  ```
</CodeGroup>

***

## Update Tool

<api-endpoint method="PATCH" path="/tools/{id}" />

Update tool properties and configuration.

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the tool
</ParamField>

### Request Body

All fields are optional and only provided fields will be updated.

<ParamField body="name" type="string" optional>
  Updated tool name
</ParamField>

<ParamField body="description" type="string" optional>
  Updated tool description
</ParamField>

<ParamField body="config" type="object" optional>
  Updated tool configuration
</ParamField>

### Response

Returns the updated tool object.

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request PATCH 'https://api.plaisolutions.com/tools/tool_123' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Enhanced Web Search Tool",
    "description": "Advanced web search with filtering capabilities",
    "config": {
      "base_url": "https://api.search.example.com/v2",
      "api_key_required": true,
      "rate_limit": 200,
      "filters_enabled": true
    }
  }'
  ```

  ```javascript JavaScript theme={null}
  const toolId = 'tool_123';
  const response = await fetch(`https://api.plaisolutions.com/tools/${toolId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: "Enhanced Web Search Tool",
      description: "Advanced web search with filtering capabilities",
      config: {
        base_url: "https://api.search.example.com/v2",
        api_key_required: true,
        rate_limit: 200,
        filters_enabled: true
      }
    })
  });

  const tool = await response.json();
  console.log(tool);
  ```

  ```python Python theme={null}
  import requests

  tool_id = "tool_123"
  url = f"https://api.plaisolutions.com/tools/{tool_id}"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
  }
  data = {
      "name": "Enhanced Web Search Tool",
      "description": "Advanced web search with filtering capabilities",
      "config": {
          "base_url": "https://api.search.example.com/v2",
          "api_key_required": True,
          "rate_limit": 200,
          "filters_enabled": True
      }
  }

  response = requests.patch(url, headers=headers, json=data)
  tool = response.json()
  print(tool)
  ```
</CodeGroup>

***

## Delete Tool

<api-endpoint method="DELETE" path="/tools/{id}" />

Delete a tool. This will also remove it from any agents that are currently using it.

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the tool to delete
</ParamField>

### Response

Returns a 204 status code on successful deletion.

<Warning>
  Deleting a tool will:

  * Remove it from all agents that are using it
  * Disable any functionality that depends on this tool
  * This action cannot be undone
</Warning>

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request DELETE 'https://api.plaisolutions.com/tools/tool_123' \
  --header 'Authorization: Bearer YOUR_TOKEN'
  ```

  ```javascript JavaScript theme={null}
  const toolId = 'tool_123';
  const response = await fetch(`https://api.plaisolutions.com/tools/${toolId}`, {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    }
  });

  console.log('Tool deleted:', response.status === 204);
  ```

  ```python Python theme={null}
  import requests

  tool_id = "tool_123"
  url = f"https://api.plaisolutions.com/tools/{tool_id}"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
  }

  response = requests.delete(url, headers=headers)
  print(f"Tool deleted: {response.status_code == 204}")
  ```
</CodeGroup>

***

## Tool Types and Configuration

Each tool type has specific configuration options and capabilities:

### BROWSER Tools

<AccordionGroup>
  <Accordion title="Configuration Options">
    ```json theme={null}
    {
      "headless": true,
      "viewport": {"width": 1280, "height": 720},
      "timeout": 30000,
      "user_agent": "PLai Browser Bot 1.0",
      "enable_javascript": true,
      "enable_images": false
    }
    ```
  </Accordion>

  <Accordion title="Capabilities">
    * Navigate to web pages
    * Click elements and fill forms
    * Take screenshots
    * Extract page content
    * Handle JavaScript interactions
    * Manage cookies and sessions
  </Accordion>

  <Accordion title="Use Cases">
    * Web scraping and automation
    * Form filling and submissions
    * Interactive web testing
    * Content extraction from dynamic sites
  </Accordion>
</AccordionGroup>

### HTTP Tools

<AccordionGroup>
  <Accordion title="Configuration Options">
    ```json theme={null}
    {
      "base_url": "https://api.example.com",
      "headers": {
        "User-Agent": "PLai HTTP Tool",
        "Accept": "application/json"
      },
      "timeout": 30,
      "retry_count": 3,
      "rate_limit": 100
    }
    ```
  </Accordion>

  <Accordion title="Capabilities">
    * Make GET, POST, PUT, DELETE requests
    * Handle authentication (API keys, OAuth)
    * Process JSON, XML, and other formats
    * Custom headers and parameters
    * Error handling and retries
  </Accordion>

  <Accordion title="Use Cases">
    * API integrations
    * Data retrieval from services
    * Webhook interactions
    * Third-party service connections
  </Accordion>
</AccordionGroup>

### PERPLEXITY Tools

<AccordionGroup>
  <Accordion title="Configuration Options">
    ```json theme={null}
    {
      "model": "llama-3.1-sonar-small-128k-online",
      "max_tokens": 1000,
      "temperature": 0.2,
      "search_domain_filter": ["example.com"],
      "return_citations": true
    }
    ```
  </Accordion>

  <Accordion title="Capabilities">
    * Real-time web search
    * Up-to-date information retrieval
    * Cited sources and references
    * Domain-specific searches
    * Multiple search models
  </Accordion>

  <Accordion title="Use Cases">
    * Current events and news
    * Research and fact-checking
    * Market intelligence
    * Technical documentation lookup
  </Accordion>
</AccordionGroup>

### EXTERNAL\_DATASOURCE Tools

<AccordionGroup>
  <Accordion title="Configuration Options">
    ```json theme={null}
    {
      "connection_string": "postgresql://user:pass@host:port/db",
      "query_timeout": 30,
      "max_results": 1000,
      "read_only": true,
      "connection_pool_size": 5
    }
    ```
  </Accordion>

  <Accordion title="Capabilities">
    * Connect to external databases
    * Execute queries and retrieve data
    * Support multiple database types
    * Connection pooling and optimization
    * Security and access control
  </Accordion>

  <Accordion title="Use Cases">
    * Customer data lookup
    * Inventory management
    * Reporting and analytics
    * Legacy system integration
  </Accordion>
</AccordionGroup>

### REMOTE\_MCP\_SERVER Tools

<AccordionGroup>
  <Accordion title="Configuration Options">
    ```json theme={null}
    {
      "server_url": "https://mcp.example.com",
      "authentication": {
        "type": "bearer",
        "token": "your-token-here"
      },
      "timeout": 60,
      "retry_policy": "exponential"
    }
    ```
  </Accordion>

  <Accordion title="Capabilities">
    * Connect to MCP-compatible servers
    * Execute remote tool functions
    * Handle complex workflows
    * Cross-system integrations
    * Protocol-level communication
  </Accordion>

  <Accordion title="Use Cases">
    * Enterprise system integration
    * Custom tool development
    * Workflow automation
    * Multi-service orchestration
  </Accordion>
</AccordionGroup>

***

## Best Practices

<Steps>
  <Step title="Tool Design">
    Create tools with single, well-defined purposes rather than complex multi-function tools
  </Step>

  <Step title="Configuration">
    Use clear configuration schemas and provide sensible defaults
  </Step>

  <Step title="Error Handling">
    Implement robust error handling and provide meaningful error messages
  </Step>

  <Step title="Security">
    Store sensitive configuration (API keys, credentials) securely
  </Step>

  <Step title="Testing">
    Test tools thoroughly before assigning them to production agents
  </Step>
</Steps>

### Tool Naming Convention

<CardGroup cols={2}>
  <Card title="Good Names" icon="check">
    * "Web Search Tool"
    * "Customer Database Lookup"
    * "Email Sender"
    * "PDF Generator"
  </Card>

  <Card title="Avoid" icon="x">
    * "Tool1"
    * "My API Thing"
    * "Utility"
    * "Helper"
  </Card>
</CardGroup>

### Configuration Management

<Note>
  Tool configurations should be environment-specific. Use different configurations for development, staging, and production environments.
</Note>

<Tip>
  Start with simple tool configurations and gradually add complexity as needed. Tools can be updated without recreating agent assignments.
</Tip>

### Security Considerations

<Warning>
  * Never store plain-text credentials in tool configurations
  * Use environment variables or secure key management systems
  * Implement proper access controls and audit logging
  * Regularly rotate API keys and tokens
</Warning>