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

# Custom Tools

> How to create custom tools with Hymalaia.

First, navigate to the Admin console, and go to the **Tools** tab. Click the New **Tool button**.

Next, specify a OpenAPI 3.0 or OpenAPI 3.1 schema that defines the APIs that you want to make available as part of this tool.

Hymalaia provides dynamic context variables that can be utilized within your OpenAPI definition, enhancing the functionality and context-awareness of your custom tools. These variables are:

* `CHAT_SESSION_ID` : Replaced with the chat session ID in which the tool call was made.

* `CHAT_MESSAGE_ID` : Replaced with the chat message ID which triggered the tool call.

For example: `/persona/CHAT_SESSION_ID/messages/CHAT_MESSAGE_ID` with `CHAT_SESSION_ID = 20` and `CHAT_MESSAGE_ID = 10` would become `/persona/20/messages/10`

***

## ✅ Tips for Schema Optimization

To ensure smooth integration and performance:

* Add **summaries** for each operation
* Use descriptive **operationIds**
* Add **parameter descriptions**

***

## 🔧 Example Tool Definition

Here’s an example of a tool schema that enables assistants to **fetch and create assistants** within Hymalaia:

```json theme={null}
{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "Assistants API",
    "description": "An API for managing assistants within Hymalaia"
  },
  "servers": [
    { "url": "http://localhost:8080" }
  ],
  "paths": {
    "/persona": {
      "get": {
        "summary": "Get a specific Assistant",
        "operationId": "getAssistant",
        "parameters": [
          {
            "name": "assistant_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ]
      },
      "post": {
        "summary": "Create a new Assistant",
        "operationId": "createAssistant",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "description": { "type": "string" },
                  "num_chunks": { "type": "number" },
                  "llm_relevance_filter": { "type": "boolean" },
                  "is_public": { "type": "boolean" },
                  "llm_filter_extraction": { "type": "boolean" },
                  "recency_bias": {
                    "type": "string",
                    "enum": ["favor_recent", "base_decay", "no_decay", "auto"]
                  },
                  "prompt_ids": {
                    "type": "array",
                    "items": { "type": "integer" }
                  },
                  "document_set_ids": {
                    "type": "array",
                    "items": { "type": "integer" }
                  },
                  "tool_ids": {
                    "type": "array",
                    "items": { "type": "integer" }
                  },
                  "llm_model_provider_override": {
                    "type": "string",
                    "nullable": true
                  },
                  "llm_model_version_override": {
                    "type": "string",
                    "nullable": true
                  },
                  "starter_messages": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "role": { "type": "string" },
                        "content": { "type": "string" }
                      }
                    },
                    "nullable": true
                  },
                  "users": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "nullable": true
                  },
                  "groups": {
                    "type": "array",
                    "items": { "type": "integer" },
                    "nullable": true
                  }
                },
                "required": [
                  "name", "description", "num_chunks", "llm_relevance_filter",
                  "is_public", "llm_filter_extraction", "recency_bias",
                  "prompt_ids", "document_set_ids", "tool_ids"
                ]
              }
            }
          }
        }
      }
    }
  }
}
```

***

🔐 Security Note
Make sure that any external API you expose via a custom tool:

* Has proper authentication/authorization controls

* Limits the assistant to only the operations you’ve defined

* Avoids exposing sensitive or destructive endpoints unintentionally

***