Re:PREZIO
Knowledge & behaviour

Custom Tools (Webhooks)

With Custom Tools (in the dashboard "Custom Tools") you give your AI agent the ability to query or trigger your own systems during a conversation — for example, fetching the order status from your shop, checking an appointment in your industry-specific system, or creating a record in your own software. Here you only describe which functions exist and what information the agent needs to gather for them; the tools are executed via a so-called webhook — an internet address of your application that our platform calls automatically.

You will find this area in the agent menu under "Custom Tools". At the top of the card you will see the note: "Functions the agent can call. On invocation, the backend POSTs to your tool_webhook_url." This means: as soon as the agent uses a tool, Prezio sends the gathered information to the webhook address you have stored, and your application responds with the result.

Important upfront — two separate places: On this page you create the tools themselves (name, description, parameters). The webhook address (tool_webhook_url) to which all tools of this agent are sent is entered elsewhere: in the agent's "Channels" area under the Tool webhook URL field. Without this address the tools are still defined, but there is no recipient to execute them. See the note at the end of this section for more.

Creating a tool

Step 1 — Add a tool. Click "Add tool" at the top right (or, with an empty list, the same button in the "No custom tools yet" notice box). A highlighted editing area opens.

Step 2 — Assign a tool name. In the "Tool name" field, enter a short, technical name, e.g. lookup_order (as in the pre-filled example text). Note: - The name serves as the AI's technical identifier for the function — write it in lowercase and make it descriptive (e.g. check_order, appointment_free_slots, create_lead). - Spaces are automatically replaced with underscores as you type. So "lookup order" becomes lookup_order. This is intended and not an error. - The name is mandatory: the "Save tool" button stays greyed out as long as the name field is empty. - Default: empty. Recommendation: a unique, clearly attributable identifier without special characters.

Step 3 — Write a description. In the "Description" field you explain when the agent should call this tool (which is exactly what the note below the field says too: "Tell the agent when to call this tool."). This description is decisive, because the AI decides solely on the basis of the text whether a tool fits the current customer query. - Example (pre-filled placeholder): "Retrieve the status and shipping details of a customer order by order ID." - Phrase it from the trigger's point of view: "Use this tool when the customer asks about the status of their order and provides an order number." - Default: empty. Recommendation: one or two clear sentences with the concrete trigger. Vague descriptions cause the tool to be called too rarely or too often.

Step 4 — Define parameters. Parameters are the pieces of information the agent gathers from the customer and passes to your webhook (e.g. the order number). Click "Param" to add a row. For each parameter you fill in: - name — the technical field name your webhook expects (e.g. order_id). Displayed in monospace; please without spaces. - type — the data type. Selected via a drop-down list, exactly three values: - string (text, e.g. an order number or a name) — this is the default selection for every new row. - number (number, e.g. a number of people or an amount), - boolean (yes/no, e.g. "express requested"). - Recommendation: when in doubt, leave it as string — the AI can pass almost anything as text. - description — a short explanation of what this parameter is. The AI reads this too, in order to ask the customer for the right value (e.g. "The order number from the confirmation email"). - "req." (the "required" checkbox) — if it is ticked, the parameter is marked as a mandatory field: the agent actively asks for it before calling the tool. Default: not ticked (optional). Recommendation: tick everything without which your webhook cannot work (e.g. the order number). - Use the bin icon at the end of the row ("Remove parameter") to delete a parameter row again.

A tool may also have no parameters at all (in which case "No parameters yet." is shown in the editing area). This makes sense for functions without input, e.g. "fetch current opening hours".

Step 5 — Save. Click "Save tool". The tool now appears as a row in the list — with its name, a counter badge ("1 Param" / "{count} Params", shown only when there are parameters) and the description below it. With "Cancel" you discard the draft without saving.

Note: Empty parameter rows (without a name) are automatically discarded on saving. Only parameters with a filled-in name end up in the tool.

Managing tools

In the list of created tools you have two icon buttons per entry: - Edit (pencil) — reopens the tool in the editing area, including all parameters. - Remove (bin, red) — deletes the tool from the list.

Step 6 — Save the entire agent (very important). All changes in this area are initially only a local draft. Only when you click "Save" in the fixed save bar at the bottom are the tools permanently stored with the agent. As long as there are unsaved changes, a notice appears there; the button stays disabled if nothing has been changed. Do not leave the page without having saved here.

What is stored technically

So that you and your IT team are on the same page: per tool, Prezio stores three pieces of information — the name, the description and an input schema (input_schema). The input schema is generated automatically from your parameter rows as a JSON schema, in the form:

{
  "type": "object",
  "properties": {
    "order_id": { "type": "string", "description": "Order number" }
  },
  "required": ["order_id"]
}

It is exactly this structure (plus the values gathered from the customer) that Prezio sends via HTTP POST to your Tool webhook URL as soon as the agent uses the tool. Your application processes the request and responds with the result, which the agent then conveys to the customer.

Setting up the webhook address (in the "Channels" area)

As mentioned above, the recipient address is not maintained here but in the agent's "Channels" area: - Tool webhook URL (tool_webhook_url) — the internet address of your application that executes all tools of this agent (example in the field: https://your-app.com/api/tool-handler). Default: empty. Without this URL your tools have no effect. - For security, a webhook secret (tool_webhook_secret) can additionally be stored. With it, your application can verify that an incoming call really comes from Prezio. Leave it empty if you do not use it. - Separate from this, there is a notification webhook URL (notification_webhook_url, example https://your-app.com/api/notify) — this is not intended for tools but for event notifications, and has nothing to do with this area.

Tips & pitfalls

  • The tool name is mandatory, the webhook URL comes from elsewhere. You can save a tool without a webhook address being stored — but it will then never be executed. Enter the Tool webhook URL in the "Channels" area, otherwise the tool runs into nothing.
  • The description controls the AI's behaviour. The agent calls a tool only if the description fits the customer query well. A woolly description is the most common reason why a tool "does not respond". If you want to trace whether and why the agent used a tool, the AI debug area helps you: in the Decision Flow of each reply you can see the tool calls that were actually executed, step by step.
  • Spaces in the name disappear on purpose. Type "create customer" and it automatically becomes create_customer. Do not use umlauts or special characters in tool and parameter names.
  • Only three parameter types. You have exclusively string, number and boolean to choose from. For dates, selection lists and the like, use string and describe the expected format in the parameter's description (e.g. "Date in the format YYYY-MM-DD").
  • Choose "required" (req.) well. Only parameters marked as required are reliably requested from the customer by the agent. If you forget to mark a mandatory field, the agent may call the tool with missing information — your webhook then receives an incomplete request.
  • Empty parameter rows are harmless. If you forget to fill in a row you started, it is simply ignored on saving. You do not have to delete it specially, but you should do so for clarity.
  • Don't forget to save. Adding or deleting a tool on its own is not enough — only the "Save" button at the bottom in the fixed bar writes the change permanently. If you leave without saving, the changes are lost.