Tools

Manage tools that agents can use during conversations.

Tools define functions that agents can call to perform actions like searching knowledge, processing data, or integrating with external systems.

Base URL: /tools

Endpoints

Method	Endpoint	Description
GET	`/tools`	List tools
POST	`/tools`	Create a new tool
GET	`/tools/{tool_id}`	Get tool by ID
PUT	`/tools/{tool_id}`	Update a tool
DELETE	`/tools/{tool_id}`	Delete a tool

List Tools

GET /tools

Retrieve all tools for the authenticated account.

Authentication: Required

Query Parameters:

skip (integer): Pagination offset (default: 0)
limit (integer): Results per page (default: 50, max: 200)

Response:

json

{
  "data": [
    {
      "id": 1,
      "name": "Knowledge Search",
      "identifier": "knowledge-search",
      "description": "Search the knowledge base for relevant information",
      "tool_type": "function",
      "configuration": {
        "max_results": 10,
        "threshold": 0.7
      },
      "created_at": "2024-01-10T09:00:00Z",
      "updated_at": "2024-01-15T11:20:00Z",
      "account_id": 42
    }
  ],
  "pagination": { "total": 15, "skip": 0, "limit": 50, "has_more": false }
}

Example:

bash

curl -X GET "https://api.gnosari.com/api/v1/tools" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Create Tool

POST /tools

Create a new tool for the authenticated account.

Authentication: Required

Request:

json

{
  "name": "Knowledge Search",
  "identifier": "knowledge-search",
  "description": "Search the knowledge base for relevant information",
  "tool_type": "function",
  "configuration": {
    "max_results": 10,
    "threshold": 0.7
  }
}

Status: 201 Created

Response: Created tool object

Example:

bash

curl -X POST "https://api.gnosari.com/api/v1/tools" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Knowledge Search",
    "identifier": "knowledge-search",
    "tool_type": "function"
  }'

Get Tool

GET /tools/{tool_id}

Retrieve a specific tool by ID.

Authentication: Required

Response: Tool object

Error Responses:

404 Not Found: Tool does not exist
403 Forbidden: Tool belongs to another account

Update Tool

PUT /tools/{tool_id}

Update a tool's properties.

Authentication: Required

Request (partial update supported):

json

{
  "description": "Updated description",
  "configuration": {
    "max_results": 20,
    "threshold": 0.8
  }
}

Response: Updated tool object

Delete Tool

DELETE /tools/{tool_id}

Permanently delete a tool.

Authentication: Required

Response: No response body (204 No Content)

Warning: Deleting a tool does NOT remove it from agents using it. Agents with deleted tools may fail at runtime.

Tool Fields

Field	Type	Description
`id`	integer	Unique tool ID
`name`	string	Tool name (required)
`identifier`	string	Unique identifier within account (required)
`description`	string	Tool purpose and usage
`tool_type`	string	Tool type (e.g., "function", "api", "mcp")
`configuration`	object	Tool-specific configuration (JSON)
`created_at`	datetime	Creation timestamp
`updated_at`	datetime	Last update timestamp
`account_id`	integer	Account ID (set automatically)

Base URL: /tools