> For the complete documentation index, see [llms.txt](https://docs.workfx.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.workfx.ai/workfx-companion-agent-knowledge/developer-docs/api-reference/tools.md).

# Tools

Manage conversations between users and agents. These endpoints allow you to create, retrieve, update, and delete conversations, and retrieve their associated messages.

## List Tool Vendors

> Returns a paginated list of available tool vendors for the current tenant and unit.\
> \
> \- \*\*Note:\*\* This endpoint only returns metadata about the tool vendors (e.g., ID, name, mode, favorite status).\
> \- To retrieve detailed tool configurations or schema information, use the corresponding \`GET /tools/{mode}\_tools/{id}\` or related detail endpoints.

```json
{"openapi":"3.0.1","info":{"title":"workfx","version":"1.0.0"},"tags":[{"name":"Tool"}],"servers":[{"url":"https://api.workfx.ai","description":"Prod Env"}],"security":[],"paths":{"/admin/api/v2/tools":{"get":{"summary":"List Tool Vendors","deprecated":false,"description":"Returns a paginated list of available tool vendors for the current tenant and unit.\n\n- **Note:** This endpoint only returns metadata about the tool vendors (e.g., ID, name, mode, favorite status).\n- To retrieve detailed tool configurations or schema information, use the corresponding `GET /tools/{mode}_tools/{id}` or related detail endpoints.","operationId":"list_tool_vendors_admin_api_v2_tools_get","tags":["Tool"],"parameters":[{"name":"page_num","in":"query","description":"Current page number","required":false,"schema":{"type":"integer","description":"Current page number","default":1,"title":"Page Num"}},{"name":"page_size","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","description":"Number of items per page","default":14,"title":"Page Size"}},{"name":"is_favorite","in":"query","description":"Filter by favorite status","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by favorite status","title":"Is Favorite"}},{"name":"mode","in":"query","description":"Filter by mode, value is flow, builtin","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ToolType"},{"type":"null"}],"description":"Filter by mode, value is flow, builtin","title":"Mode"}},{"name":"order","in":"query","description":"order by: 'recent'(default) or 'oldest'","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"order by: 'recent'(default) or 'oldest'","default":"recent","title":"Order"}},{"name":"tenant_id","in":"query","description":"Tenant Id","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant Id","title":"Tenant Id"}},{"name":"tenant_unit_id","in":"query","description":"Tenant Unit ID","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant Unit ID","title":"Tenant Unit Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolListResponse"}}},"headers":{}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{}}}}}},"components":{"schemas":{"ToolType":{"type":"string","enum":["flow","builtin","mcp","api"],"title":"ToolType"},"ToolListResponse":{"properties":{"page_num":{"type":"integer","title":"Page Num","description":"Current page number"},"page_size":{"type":"integer","title":"Page Size","description":"Number of items per page"},"total_count":{"type":"integer","title":"Total Count","description":"Total number of tools"},"has_next_page":{"type":"boolean","title":"Has Next Page","description":"Whether there is a next page"},"data":{"items":{"type":"object","properties":{}},"type":"array","title":"Data","description":"List of tools"}},"type":"object","required":["page_num","page_size","total_count","has_next_page","data"],"title":"ToolListResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"type":"object","properties":{}},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}
```

## Get Tool Vendor By Id

> Retrieve common information and metadata for a single tool by its ID.

```json
{"openapi":"3.0.1","info":{"title":"workfx","version":"1.0.0"},"tags":[{"name":"Tool"}],"servers":[{"url":"https://api.workfx.ai","description":"Prod Env"}],"security":[],"paths":{"/admin/api/v2/tools/{tool_id}":{"get":{"summary":"Get Tool Vendor By Id","deprecated":false,"description":"Retrieve common information and metadata for a single tool by its ID.","operationId":"get_tool_vendor_by_id_admin_api_v2_tools__tool_id__get","tags":["Tool"],"parameters":[{"name":"tool_id","in":"path","description":"Tool id","required":true,"schema":{"type":"string","format":"uuid","description":"Tool ID to fetch","title":"Tool Id"}},{"name":"tenant_id","in":"query","description":"Tenant Id","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant Id","title":"Tenant Id"}},{"name":"tenant_unit_id","in":"query","description":"Tenant Unit ID","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant Unit ID","title":"Tenant Unit Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolVendorItem"}}},"headers":{}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{}}}}}},"components":{"schemas":{"ToolVendorItem":{"properties":{"icon_type":{"anyOf":[{"type":"string","enum":["emoji","file_id","url"]},{"type":"null"}],"title":"Icon Type","description":"Source type: 'emoji' or 'url'"},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon","description":"Raw icon value: emoji char, full URL, or gallery key"},"icon_background":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon Background","description":"Hex background color behind the icon","default":"#FFF"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Tool description","default":""},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Tool vendor ID"},"name":{"type":"string","title":"Name","description":"Tool vendor name"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name","description":"Tool vendor display name"},"mode":{"$ref":"#/components/schemas/ToolType","description":"Tool type, e.g., builtin, flow"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By","description":"User ID of creator"},"created_by_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By Name","description":"User name of creator"},"created_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created Time","description":"Timestamp of creation"},"updated_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By","description":"User ID of last updater"},"updated_by_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By Name","description":"User name of updater"},"updated_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated Time","description":"Timestamp of last update"},"is_favorite":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Favorite","description":"Indicates if the item is marked as favorite"},"icon_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon Url","readOnly":true}},"type":"object","required":["name","mode","icon_url"],"title":"ToolVendorItem"},"ToolType":{"type":"string","enum":["flow","builtin","mcp","api"],"title":"ToolType"},"HTTPValidationError":{"properties":{"detail":{"items":{"type":"object","properties":{}},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}
```

## Update Tool Vendor

> Update the common information and metadata for a tool by its ID.

```json
{"openapi":"3.0.1","info":{"title":"workfx","version":"1.0.0"},"tags":[{"name":"Tool"}],"servers":[{"url":"https://api.workfx.ai","description":"Prod Env"}],"security":[],"paths":{"/admin/api/v2/tools/{tool_id}":{"put":{"summary":"Update Tool Vendor","deprecated":false,"description":"Update the common information and metadata for a tool by its ID.","operationId":"update_tool_vendor_admin_api_v2_tools__tool_id__put","tags":["Tool"],"parameters":[{"name":"tool_id","in":"path","description":"Tool id","required":true,"schema":{"type":"string","title":"Tool Id"}},{"name":"tenant_id","in":"query","description":"Tenant Id","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant Id","title":"Tenant Id"}},{"name":"tenant_unit_id","in":"query","description":"Tenant Unit ID","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant Unit ID","title":"Tenant Unit Id"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolVendorUpdateRequest","description":"Payload containing fields to update for the tool"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolVendorItem"}}},"headers":{}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{}}}}}},"components":{"schemas":{"ToolVendorUpdateRequest":{"properties":{"icon_type":{"anyOf":[{"type":"string","enum":["emoji","file_id","url"]},{"type":"null"}],"title":"Icon Type","description":"Source type: 'emoji' or 'url'"},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon","description":"Raw icon value: emoji char, full URL, or gallery key"},"icon_background":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon Background","description":"Hex background color behind the icon","default":"#FFF"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Tool description","default":""},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Tool name"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name","description":"Tool name"}},"type":"object","title":"ToolVendorUpdateRequest"},"ToolVendorItem":{"properties":{"icon_type":{"anyOf":[{"type":"string","enum":["emoji","file_id","url"]},{"type":"null"}],"title":"Icon Type","description":"Source type: 'emoji' or 'url'"},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon","description":"Raw icon value: emoji char, full URL, or gallery key"},"icon_background":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon Background","description":"Hex background color behind the icon","default":"#FFF"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Tool description","default":""},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Tool vendor ID"},"name":{"type":"string","title":"Name","description":"Tool vendor name"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name","description":"Tool vendor display name"},"mode":{"$ref":"#/components/schemas/ToolType","description":"Tool type, e.g., builtin, flow"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By","description":"User ID of creator"},"created_by_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By Name","description":"User name of creator"},"created_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created Time","description":"Timestamp of creation"},"updated_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By","description":"User ID of last updater"},"updated_by_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By Name","description":"User name of updater"},"updated_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated Time","description":"Timestamp of last update"},"is_favorite":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Favorite","description":"Indicates if the item is marked as favorite"},"icon_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon Url","readOnly":true}},"type":"object","required":["name","mode","icon_url"],"title":"ToolVendorItem"},"ToolType":{"type":"string","enum":["flow","builtin","mcp","api"],"title":"ToolType"},"HTTPValidationError":{"properties":{"detail":{"items":{"type":"object","properties":{}},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}
```

## Delete Tool Vendor

> Delete a tool (common metadata) by its ID. No content is returned on success.

```json
{"openapi":"3.0.1","info":{"title":"workfx","version":"1.0.0"},"tags":[{"name":"Tool"}],"servers":[{"url":"https://api.workfx.ai","description":"Prod Env"}],"security":[],"paths":{"/admin/api/v2/tools/{tool_id}":{"delete":{"summary":"Delete Tool Vendor","deprecated":false,"description":"Delete a tool (common metadata) by its ID. No content is returned on success.","operationId":"delete_tool_vendor_admin_api_v2_tools__tool_id__delete","tags":["Tool"],"parameters":[{"name":"tool_id","in":"path","description":"Tool id","required":true,"schema":{"type":"string","title":"Tool Id"}},{"name":"tenant_id","in":"query","description":"Tenant Id","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant Id","title":"Tenant Id"}},{"name":"tenant_unit_id","in":"query","description":"Tenant Unit ID","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tenant Unit ID","title":"Tenant Unit Id"}}],"responses":{"204":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{}}}},"headers":{}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"type":"object","properties":{}},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.workfx.ai/workfx-companion-agent-knowledge/developer-docs/api-reference/tools.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.