{
"type": "function",
"function": {
"name": "get_user_cart",
"description": "Retrieves the user's shopping cart contents including items, quantities, and prices.",
"strict": true,
"parameters": {
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}
}
}
get_user_cart function in your app, retrieves the user’s shopping cart data, and responds with personalized information about items, quantities, and total price.

How client-side tools work
Key capabilities
Key capabilities
- user context access: retrieve shopping cart contents, preferences, order history, and authentication tokens
- Action execution: add items to cart, apply a , update profiles, submit forms
- UI interaction: trigger UI updates, toggle elements, and refine search results dynamically
- Security: run in user’s security context with proper authentication
- Flexibility: use existing frontend or backend APIs without additional infrastructure
- Client-side context: access local storage, session data, and other browser-specific states
Security: Runs in your app’s security context.
Agent Studio never stores credentials.
Always validate authentication, sanitize inputs, and enforce access control.
For more information, see Client-side security patterns.
- Agent Studio: to define the tool schema.
- Your frontend or backend code to run the tool.
Agent Studio configuration
Define your tools in your agent using JSON schema format. For example:- Get shopping cart contents
- Add item to cart
JSON
Required fields
type: must be"function"function.name: function name (from 3 to 64 characters, letters, numbers, and underscores only)function.description: clear explanation of what the tool does and when to use itfunction.parameters: JSON schema objecttype: must be"object"properties: object defining each parameter with type and descriptionrequired: array of required parameter names (can be empty)additionalProperties: set tofalsefor strict mode. If you’re using strict mode:- All fields in
propertiesmust be inrequired - Use
["type", "null"]for optional fields (for example,"type": ["string", "null"]) - Always set
additionalProperties: falsefor objects - Use
enumfor restricted values - Set
minimumandmaximumconstraints for numbers
- All fields in
Optional but recommended fields
function.strict: set totrueto ensure reliable schema adherence (recommended for production)
JSON schema
JSON
- Define your tool using JSON schema (follows OpenAI Function Calling format)
- Add the tool to your agent with an API or using Other tools in the dashboard
Frontend or backend code configuration
Run tools from your frontend or backend code. For example:- JavaScript
- React InstantSearch
JavaScript
Advanced usage
Strict mode
Strict mode ensures the LLM reliably adheres to your JSON Schema instead of using “best-effort” matching.- Without strict mode
- With strict mode
JSON
- LLM might omit optional fields unpredictably
- Field types may not match exactly
- Additional unexpected fields might be included
Strict mode requirements
- All fields in
propertiesmust be inrequired - Use
["type", "null"]for optional fields (for example,"type": ["string", "null"]) - Set
additionalProperties: falsefor all objects - The LLM strictly follows the schema (no best-effort guessing)
Benefits of strict mode
- Predictable function calls every time
- Prevents schema drift
- Easier debugging (failures are schema violations, not interpretation issues)
- Recommended for production use
Render dynamic UI from agent context
Instead of returning data for the agent to describe in text, a client-side tool can return structured data that your frontend renders as UI. The agent decides what to show, and your app decides how to render it. Define arender_component tool whose parameters describe the component to render and the items it needs:
JSON
- The user asks to compare or browse products.
- The agent searches with the Algolia Search tool, then calls
render_componentwith acomponentand the matchingitems. - Your frontend receives the tool call, renders the named component, and returns a confirmation as the tool result.
- The agent continues the conversation, referring to what the user now sees.
JavaScript
Error handling patterns
Return structured errors that the agent can interpret and explain to users:- Successful response
- Error response
JSON
Common error codes
NOT_FOUND: Resource doesn’t existUNAUTHORIZED: User lacks permissionsOUT_OF_STOCK: Product unavailableINVALID_QUANTITY: Quantity exceeds limitsVALIDATION_ERROR: Input validation failed
Failures in the chat widget
A structured error response is a successful tool call: the agent reads the payload and explains it. When the tool itself can’t run at all, report a failure instead, so the chat shows it and the turn ends. With the InstantSearch chat widget,onToolCall reports a failure in three ways:
- Throw or reject. The chat settles the tool call with the error’s message.
- Call
addToolResult({ state: 'output-error', errorText })for a message you control. - Do nothing before the tool’s
timeoutelapses, 20 seconds by default. The chat aborts the handler’ssignaland settles the tool call itself.
signal your handler receives to any fetch you make, so work the chat has given up on doesn’t keep running.
For the full lifecycle, see the tools option of the chat widget reference for React or JavaScript.
Security
You must run client-side tools securely within your app. Use the following patterns to validate users, sanitise inputs, and enforce access control.Always validate authentication
JavaScript
Sanitize all inputs
JavaScript
Rate limiting
JavaScript
Don’t expose sensitive data
JavaScript