Tools
Tools let the assistant look things up or take actions in your own systems: check an order, list free appointment slots, create a ticket. You describe an endpoint once; the assistant decides when to call it.
Updated
On this page
How tools work
#- 01
You describe an endpoint
A name, a plain-language description, the URL and method, the parameters the assistant must supply, and how to authenticate.
- 02
The assistant decides to call it
When a visitor asks something the tool can answer, the model fills in the parameters. It only ever sees the name, the description and the parameters, never your URL or keys.
- 03
The platform makes the call
Kothadesk calls your API from its servers with your stored credentials, filters the response and hands the result back to the model, which answers the visitor.
- 04
Everything is logged
Each call appears under the reply in the conversation view, with its arguments, result, status and duration.
| Type | Use it for | What happens |
|---|---|---|
| Read | Looking things up: order status, free slots, fee due | Runs on its own; failed connections are retried once |
| Write | Changing something: book, cancel, create a ticket | The visitor sees a Confirm card with the details and must press Confirm. Never retried. DELETE requests are always write tools |
A write tool can be set to run without asking (auto-run). Even then, the first message of a conversation always asks for confirmation. Use auto-run only for low-risk, reversible actions such as creating a support ticket.
Add a REST tool
#Open the bot, go to Tools and choose Add REST tool.
| Field | What to enter | Rules |
|---|---|---|
| Function name | What the model calls, for example get_order_status | 3 to 48 characters: lower-case letters, digits and underscores, starting with a letter. Unique per bot |
| Shown to visitors as | A friendly label, for example Order status | Up to 60 characters |
| Description for the model | When to use the tool and what it returns. This is the most important field | 20 to 1000 characters |
| Method | GET, POST, PUT, PATCH or DELETE | DELETE is always a write tool |
| URL | Your endpoint, with {{args.name}} placeholders in the path | https only, port 443 or 8443, a public host name, no user name or password in the URL |
| Parameters (JSON Schema) | The values the model must supply | An object with up to 20 properties and "additionalProperties": false |
| Result filter (optional) | A JMESPath expression that keeps only the fields the model needs | Up to 500 characters |
| Summary for visitors (optional) | A short line shown in the chat, for example Order {{args.order_id}}: {{result.status}} | Up to 200 characters |
| Authentication | How your API checks the call | See Credentials below |
| Read or Write | Whether the call changes anything | Read by default |
| Only for signed-in users | Hide the tool from anonymous visitors | Turned on automatically when the URL uses {{end_user...}} |
| Timeout | How long to wait | 500 to 30000 ms, default 10000 |
Parameters that are not used in the URL path are sent as query parameters for GET and DELETE, and as a JSON body for POST, PUT and PATCH.
Tip: Write the description the way you would brief a new colleague: "Use this when a customer asks where their order is. Needs the order number, which starts with ORD-. Returns the status and the expected delivery date." Good descriptions are the difference between a tool that is used well and one that is ignored.
To change a saved tool, press Edit on its row. The function name is fixed after creation, and a saved secret is kept unless you type a new one.
Credentials and signed-in visitors
#| Option | Sent as |
|---|---|
| No auth | Nothing (only for public data) |
| API key header | Your key in the header you name (default X-Api-Key) |
| Bearer token | Authorization: Bearer <token> |
| Basic auth | Authorization: Basic with your user name and password |
| OAuth2 client credentials | A token fetched from your token URL with your client id and secret, cached until shortly before it expires |
Secrets are encrypted and never shown again, only their last four characters. The model never sees them. Create a dedicated key for Kothadesk with the narrowest permissions your API allows.
For anything personal, such as "my orders" or "my fee status", use signed identity rather than asking the visitor for an id. When your site starts the chat with a signed identity token, a tool can use these values:
| Placeholder | Value |
|---|---|
| {{args.name}} | A parameter the model supplied |
| {{end_user.sub}} | The signed-in user's id from your identity token |
| {{end_user.email}}, {{end_user.name}} | Their email and name, if you included them |
| {{end_user.ctx.key}} | Extra signed context from your site, for example a plan or account id |
| {{conversation.id}}, {{bot.id}} | The conversation and bot ids |
Watch out: Never put a user id, email or customer id in the parameters. The model could be talked into looking up someone else. Use {{end_user.sub}} in the URL instead; the tool is then hidden from anonymous visitors and your API also receives an X-Kothadesk-End-User header.
Test before you rely on it
#- 01
Press Test on the tool
Enter example arguments as JSON, and a test user id for signed-in tools. Write tools really run, so use test data.
- 02
Read the result
You see the status, HTTP code, time taken, the summary, exactly what the model receives, and the request with secrets masked.
- 03
Try it in the Playground
Ask the question a customer would ask. For write tools the Playground shows Confirm and Decline, like the widget.
Connect an MCP server
#If your system already offers a remote MCP server (Streamable HTTP), connect it instead of describing endpoints one by one. Choose Add MCP server, enter a name, the server URL and authentication (API key header, bearer token or OAuth2).
- Kothadesk lists the server's tools (up to 200). Each starts switched off: enable only the ones this bot needs.
- Tools that declare themselves read-only start as Read; everything else starts as Write and asks the visitor to confirm.
- Turn on Signed-in users only for tools that act on the customer's own account. Only those tools receive the signed-in user's id (in the X-Kothadesk-End-User header), and anonymous visitors never see them.
- Press Refresh tools after the server changes. A tool whose definition changed is switched off until you approve it again.
- If the server stops answering, its tools are not offered until it is back.
Tip: Building your own server? The Build an MCP server guide has a complete, tested sample in Python.
Worked examples
#Online shop
Order status and returns
Let customers check an order and start a return without waiting for an agent.
| Field | Value |
|---|---|
| Function name | get_order_status |
| Description | Use when a customer asks where their order is or when it will arrive. Needs the order number, which looks like ORD-12345. Returns the status and the expected delivery date. |
| Method and URL | GET https://api.yourshop.com/v1/orders/{{args.order_id}} |
| Result filter | {status: status, expected_delivery: eta, courier: courier.name} |
| Summary | Order {{args.order_id}}: {{result.status}} |
| Authentication | API key header |
| Type | Read |
{
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "Order number, for example ORD-12345",
"pattern": "^ORD-[0-9]{4,10}$"
}
},
"required": ["order_id"],
"additionalProperties": false
}Visitor: Where is my order ORD-48213?
Bot: It has shipped with BlueDart and should arrive on Thursday, 3 October.
For returns, add a second tool, start_return: POST https://api.yourshop.com/v1/customers/{{end_user.sub}}/returns with order_id and reason as parameters, type Write, auto-run off. It only appears for signed-in customers and always asks them to confirm.
Clinic or bookings
Free slots and bookings
Show available appointments and book one after the patient confirms.
| Tool | Method and URL | Type |
|---|---|---|
| list_free_slots | GET https://api.yourclinic.in/slots (parameters: date, doctor) | Read |
| book_appointment | POST https://api.yourclinic.in/appointments (parameters: slot_id, patient_name, phone) | Write, auto-run off |
{
"type": "object",
"properties": {
"date": { "type": "string", "format": "date", "description": "Day to check, YYYY-MM-DD" },
"doctor": { "type": "string", "enum": ["dr-sharma", "dr-baruah", "any"] }
},
"required": ["date", "doctor"],
"additionalProperties": false
}Visitor: Can I see Dr Baruah tomorrow evening?
Bot: Dr Baruah has 5:30 pm and 6:15 pm free tomorrow. Which one suits you?
Visitor: 6:15, name Rina Das, 98640 12345
Bot: Confirm: Book appointment. Dr Baruah, tomorrow 6:15 pm, Rina Das. [Confirm] [Cancel]
Software company
Account plan and support tickets
Answer "what plan am I on?" for signed-in users and open a ticket when the bot cannot solve a problem.
| Tool | Method and URL | Type |
|---|---|---|
| get_my_plan | GET https://api.yourapp.com/accounts/{{end_user.ctx.account_id}}/plan (no parameters) | Read, signed-in only |
| create_ticket | POST https://api.yourapp.com/tickets (parameters: subject, description, priority) | Write, auto-run on (low risk) |
Pass account_id as signed context from your app when it starts the chat. A tool with no parameters still needs a schema: {"type": "object", "properties": {}, "additionalProperties": false}.
Coaching institute
Batch timings and fee status
Answer batch questions for everyone and fee questions only for the signed-in student.
| Tool | Method and URL | Type |
|---|---|---|
| get_batch_timings | GET https://api.yourinstitute.in/batches (parameters: course, centre) | Read |
| get_fee_status | GET https://api.yourinstitute.in/students/{{end_user.sub}}/fees (no parameters) | Read, signed-in only |
Visitor: JEE weekend batch timings at Jorhat centre?
Bot: The JEE weekend batch at Jorhat runs Saturday and Sunday, 8 am to 12 noon.
Visitor: Is my second instalment paid?
Bot: Your second instalment of 18,000 rupees is due on 15 October; it is not paid yet.
Limits
#| Limit | Value |
|---|---|
| Enabled tools per bot | 20 |
| Enabled tools per workspace | Free 3, Pro 20, Business 100 |
| Tool rounds per answer | Up to 5, then the assistant answers with what it has |
| Calls | 20 per conversation per hour, 120 per bot per minute |
| Response size | 256 KB read; the model sees at most 6000 characters per result |
| Timeout | 500 ms to 30 seconds per call |
Calls leave from Kothadesk's servers through a filtering proxy: private, local and cloud-metadata addresses are refused, and redirects are not followed. Your API must be reachable over the public internet.
Troubleshooting
#Why does saving a tool say the URL is not allowed?
Tool URLs must use https on port 443 or 8443 and a public host name. Private addresses and other ports are refused.
What does “the tool could not be reached” mean?
Kothadesk could not connect to your endpoint. Check that the host name resolves publicly and that your firewall allows the call.
Why does a tool report that it is not configured correctly?
Authentication failed. Re-enter the key, or check the OAuth2 token URL, client id and scopes.
What should I do when a tool's response is too large?
Add a result filter or return less from the endpoint.
Why does a tool time out?
Your endpoint answered too slowly. Speed it up or raise the tool's timeout, up to 30 seconds.
Why does the assistant never call my tool?
The model decides from the description. Rewrite it to say when to use the tool, in the words your customers use.