List Tools

Returns all tools for the authenticated user's agency from the local agency_tools database table. Supports filtering by tool type, category, and active status.

Endpoint

Property	Value
Function Name	tools-list
HTTP Method	GET
Authentication	Supabase JWT (Bearer token)
Required Role	Any authenticated agency user

Request

Headers

Authorization: Bearer <supabase_jwt_token>

Query Parameters

Field	Type	Required	Description
tool_type	string	No	Filter by tool type. Possible values: http, client, dataConnection
category	string	No	Filter by category
active_only	string	No	If "false", include inactive tools. Defaults to "true"

Response

Success (200)

{
  "tools": [
    {
      "id": "local-uuid",
      "ultravox_tool_id": "ultravox-tool-uuid",
      "name": "my-tool",
      "description": "Tool description",
      "tool_type": "http",
      "ownership": "user",
      "created_at_ultravox": "2025-01-01T00:00:00Z",
      "definition": { },
      "http_base_url": "https://api.example.com/endpoint",
      "http_method": "POST",
      "dynamic_parameters": [],
      "static_parameters": [],
      "category": "general",
      "tags": ["tag1", "tag2"],
      "icon": "wrench",
      "is_active": true,
      "managed_by_virsyn": false,
      "last_synced_at": "2025-01-15T12:00:00Z",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-15T12:00:00Z"
    }
  ],
  "total": 1,
  "last_synced_at": "2025-01-15T12:00:00Z",
  "sync_recommended": false
}

The sync_recommended field is true when the tools list is empty or the last sync was more than 24 hours ago.

Error Responses

Status	Condition
401	Missing or invalid authorization header
403	User is not an agency user
405	HTTP method is not GET
500	Database query failed

Behavior

• Authenticates the user via Supabase JWT and verifies they belong to an agency
• Queries the agency_tools table filtered by the user's agency_id, ordered by name
• Applies optional filters for tool_type, category, and is_active (active-only by default)
• Returns all matching tool records with their full field set
• Checks the last_synced_at timestamp and sets sync_recommended: true if the data is empty or older than 24 hours

Database Tables Read

Table	Operation	Purpose
users	Read	Resolve agency membership
agency_tools	Read	Retrieve tools for the agency

Related Functions

• Get Tool -- Retrieve a single tool by ID with optional refresh from Ultravox
• Sync Tools -- Sync all tools from Ultravox into the local database