# Create tool > POST https://api.nabrah.ai/api/ext/tool Group: Tools. Page: https://www.nabrah.ai/en/docs/api-reference/tools/create-tool Create a new function-calling tool in the current project. A tool is an HTTP webhook the agent can call during a conversation; the agent decides when to invoke it based on the name and description, then sends the configured parameters to your url. The response returns the full tool record including its generated id (the tool_id). After creating a tool you typically link it to one or more agents with POST /api/ext/tool/link before it can be used in a call. ## Request fields Describe the webhook the agent should call and the parameters it may pass. - **Tool definition**: name and description tell the model what the tool does and when to use it — write them clearly because the agent selects tools from these. url is the endpoint Nabrah calls; method is the HTTP verb (GET, POST, etc.). timeout_seconds bounds how long Nabrah waits for your endpoint. Fields: `name`, `description`, `url`, `method`, `timeout_seconds`. - **parameters[]**: Defines each value sent with the call. name is the parameter key. location is where it is placed (query, header, path, or body). parameter_type is either constant (a fixed value you supply in value) or inferred from the conversation by the model. data_type is the JSON type (string, number, boolean, etc.). description guides the model when it must fill the value. required marks whether the agent must provide it. value holds the fixed value for constant parameters; default_value is used when no value is supplied. Fields: `name`, `location`, `parameter_type`, `data_type`, `description`, `required`, `value`, `default_value`. ## Next step: linking Creating a tool does not attach it to any agent. Take the id from the response and call POST /api/ext/tool/link with that tool_id plus an agent_id to make the tool available during the agent's conversations. ## Delivery and retries How Nabrah calls your endpoint during a call or chat. - **One attempt per use**: Each time the agent uses the tool, Nabrah calls your endpoint once and waits up to `timeout_seconds`. There is no automatic retry or backoff, and no request ID is sent. Fields: `timeout_seconds`. - **Errors**: Your status code and response body are passed back to the agent, which decides what to tell the caller. On a timeout or connection error the agent is told the tool failed. The agent may call the tool again in the same conversation, so make booking-style endpoints idempotent, for example by keying them on your own appointment ID. ## Authorization - `X-API-Key` (string, header, required): your workspace API key. ## Body (application/json) ### Example: Get weather (query params) A GET webhook with two query parameters: a constant API token and a model-filled city name. ```json { "name": "get_weather", "description": "Look up the current weather for a city. Call this when the caller asks about weather conditions.", "url": "https://api.example.com/weather", "method": "GET", "timeout_seconds": 5, "parameters": [ { "name": "api_token", "location": "header", "parameter_type": "constant", "data_type": "string", "description": "Service API token", "required": true, "value": "secret-token-123", "default_value": "" }, { "name": "city", "location": "query", "parameter_type": "inferred", "data_type": "string", "description": "The city the caller is asking about", "required": true, "value": "", "default_value": "Riyadh" } ] } ``` ## Response ### 200 Successful Response Content type: `application/json` ```json { "name": "string", "description": "string", "url": "string", "method": "GET", "id": "00000000-0000-4000-8000-000000000000", "project_id": "00000000-0000-4000-8000-000000000000", "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:00:00.000Z", "timeout_seconds": 5, "parameters": [ { "name": "string", "location": "query", "parameter_type": "constant", "data_type": "string", "description": "string", "tool_id": "00000000-0000-4000-8000-000000000000", "required": false, "value": "string", "default_value": "string" } ], "link_id": "00000000-0000-4000-8000-000000000000" } ``` ### 422 Validation Error Content type: `application/json` ```json { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } ``` ## Request examples ### cURL ```bash curl --request POST \ --url 'https://api.nabrah.ai/api/ext/tool' \ --header 'X-API-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "name": "get_weather", "description": "Look up the current weather for a city. Call this when the caller asks about weather conditions.", "url": "https://api.example.com/weather", "method": "GET", "timeout_seconds": 5, "parameters": [ { "name": "api_token", "location": "header", "parameter_type": "constant", "data_type": "string", "description": "Service API token", "required": true, "value": "secret-token-123", "default_value": "" }, { "name": "city", "location": "query", "parameter_type": "inferred", "data_type": "string", "description": "The city the caller is asking about", "required": true, "value": "", "default_value": "Riyadh" } ] }' ``` ### Python ```python import requests url = "https://api.nabrah.ai/api/ext/tool" headers = { "X-API-Key": "", } payload = { "name": "get_weather", "description": "Look up the current weather for a city. Call this when the caller asks about weather conditions.", "url": "https://api.example.com/weather", "method": "GET", "timeout_seconds": 5, "parameters": [ { "name": "api_token", "location": "header", "parameter_type": "constant", "data_type": "string", "description": "Service API token", "required": True, "value": "secret-token-123", "default_value": "" }, { "name": "city", "location": "query", "parameter_type": "inferred", "data_type": "string", "description": "The city the caller is asking about", "required": True, "value": "", "default_value": "Riyadh" } ] } response = requests.post(url, headers=headers, json=payload) response.raise_for_status() print(response.json()) ``` ### JavaScript ```javascript const response = await fetch("https://api.nabrah.ai/api/ext/tool", { method: "POST", headers: { "X-API-Key": "", "Content-Type": "application/json", }, body: JSON.stringify({ "name": "get_weather", "description": "Look up the current weather for a city. Call this when the caller asks about weather conditions.", "url": "https://api.example.com/weather", "method": "GET", "timeout_seconds": 5, "parameters": [ { "name": "api_token", "location": "header", "parameter_type": "constant", "data_type": "string", "description": "Service API token", "required": true, "value": "secret-token-123", "default_value": "" }, { "name": "city", "location": "query", "parameter_type": "inferred", "data_type": "string", "description": "The city the caller is asking about", "required": true, "value": "", "default_value": "Riyadh" } ] }), }); const data = await response.json(); console.log(data); ``` ### Go ```go package main import ( "fmt" "io" "net/http" "strings" ) func main() { payload := strings.NewReader(`{ "name": "get_weather", "description": "Look up the current weather for a city. Call this when the caller asks about weather conditions.", "url": "https://api.example.com/weather", "method": "GET", "timeout_seconds": 5, "parameters": [ { "name": "api_token", "location": "header", "parameter_type": "constant", "data_type": "string", "description": "Service API token", "required": true, "value": "secret-token-123", "default_value": "" }, { "name": "city", "location": "query", "parameter_type": "inferred", "data_type": "string", "description": "The city the caller is asking about", "required": true, "value": "", "default_value": "Riyadh" } ] }`) req, _ := http.NewRequest("POST", "https://api.nabrah.ai/api/ext/tool", payload) req.Header.Set("X-API-Key", "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() out, _ := io.ReadAll(res.Body) fmt.Println(string(out)) } ```