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

# Python SDK — tools

> Python SDK reference for Kataven tools — built-in tool catalog, custom Python tools, paginated listing with filters.

`ToolsClient` is reachable on every Kataven client as `client.tools`. Each method maps to one HTTP endpoint on the [Hub API](/api-reference/introduction); links to the underlying spec entry are inline below.

Browse the tool catalog and author custom tools. Tools are functions an agent can call mid-conversation.

## Methods at a glance

| Method   | HTTP                                  | Summary              |
| -------- | ------------------------------------- | -------------------- |
| `list`   | `GET /api/tools`                      | List tools           |
| `get`    | `GET /api/tools/{tool_id_or_name}`    | Get a single tool    |
| `create` | `POST /api/tools`                     | Create a custom tool |
| `update` | `PUT /api/tools/{tool_id_or_name}`    | Update a tool        |
| `delete` | `DELETE /api/tools/{tool_id_or_name}` | Delete a custom tool |

## Reference

### `client.tools.list(...)`

List tools

**HTTP** — `GET /api/tools` · [API reference →](/api-reference/introduction#tag/Tools/operation/getApiTools)

```python theme={null}
    def list(
        self,
        category: Optional[str] = None,
        type: Optional[str] = None,  # noqa: A002 — matches API param name
        search: Optional[str] = None,
        limit: int = 10,
        offset: int = 0,
    ) -> Dict[str, Any]:
```

pagination + category counts.

Returns the catalog of tools available in this account, paginated and filterable. Includes category counts for filter UIs.

### `client.tools.get(...)`

Get a single tool

**HTTP** — `GET /api/tools/{id}` · [API reference →](/api-reference/introduction#tag/Tools/operation/getApiToolsById)

```python theme={null}
    def get(self, tool_id_or_name: str) -> Dict[str, Any]:
```

Looks up the tool by uuid or by snake\_case name. Returns 404 if neither matches.

### `client.tools.create(...)`

Create a custom tool

**HTTP** — `POST /api/tools` · [API reference →](/api-reference/introduction#tag/Tools/operation/postApiTools)

```python theme={null}
    def create(
        self,
        name: str,
        category: str,
        description: str = "",
        schema: Optional[Dict[str, Any]] = None,
        implementation_type: str = "python",
        implementation_config: Optional[Dict[str, Any]] = None,
        implementation_code: str = "",
        tags: Optional[List[str]] = None,
    ) -> Dict[str, Any]:
```

### `client.tools.update(...)`

Update a tool

**HTTP** — `PUT /api/tools/{id}` · [API reference →](/api-reference/introduction#tag/Tools/operation/putApiToolsById)

```python theme={null}
    def update(self, tool_id_or_name: str, **kwargs) -> Dict[str, Any]:
```

Patches description / schema / implementation\_config / implementation\_code / tags. Default tools are flipped to modified\_from\_default=TRUE so re-seeds skip them.

### `client.tools.delete(...)`

Delete a custom tool

**HTTP** — `DELETE /api/tools/{id}` · [API reference →](/api-reference/introduction#tag/Tools/operation/deleteApiToolsById)

```python theme={null}
    def delete(self, tool_id_or_name: str) -> Dict[str, Any]:
```

Default (seeded) tools cannot be deleted — only custom ones. Returns 403 if the tool is default.