Skip to main content

Assistant Tools and How to Use Them

Tool Configuration​

Tools extend your assistants' capabilities beyond generating text responses. They allow assistants to interact with external systems, retrieve information, and perform specialized functions. This chapter covers the available tools, their parameters, and best practices for implementation.

Understanding Assistant Tools​

Tools enable your assistants to:

  • Access real-time information
  • Interact with your business systems
  • Store and retrieve data during conversations
  • Call specialized assistants for specific tasks
  • Validate data against business rules

Each tool serves a specific purpose and should be carefully selected based on your assistant's requirements.

Available Tool Types and Parameters​

Each tool below includes:

  • Parameters: The inputs the tool requires
  • Example usage in prompt: How to instruct your Assistant to use this tool (include this in your Assistant instructions)

get_current_time​

Retrieves the current time, optionally in a specified timezone.

Parameters:

  • timezone (string, optional): The timezone to use (e.g., "America/New_York", "Europe/Amsterdam")

Example usage in prompt:

When the customer asks about business hours, use the get_current_time tool to check if we're currently open.
Example:
Customer: "Are you open right now?"
You: I'll check our current hours. [Use get_current_time to determine if within business hours]

write_to_memory​

Stores data in the conversation memory that can be retrieved later in the same conversation.

Parameters:

  • key (string, required): The identifier for storing the data
  • data (string, required): The data to store

Note: For details on how stored memory appears in prompt construction, see How Deepdesk Constructs Assistant Prompts.

Example usage in prompt:

When the customer provides their account number, store it using write_to_memory for future reference in the conversation.
Example:
Customer: "My account number is 12345"
You: Thank you for providing your account number. [Use write_to_memory to store "12345" with key "account_number"]

call_knowledge_assist​

Queries Knowledge Assistants to retrieve relevant information.

Parameters:

  • headers (object, optional): HTTP headers for the request
  • question (string, required): The query to send to the Knowledge Assistant
  • chat_history (array, optional): Previous messages for context
  • assistant_code (string, optional): Code of the Knowledge Assistant to use
  • conversation_id (string, optional): Current conversation ID

Note: Knowledge Assistants are specialized assistants configured separately in Deepdesk that connect to specific source documents, websites, or APIs. Each Knowledge Assistant has its own name, instructions, and content sources, and is identified by a unique code.

Example usage in prompt:

When customers ask about product specifications or policies, use call_knowledge_assist to search our knowledge base.
Example:
Customer: "What's your return policy?"
You: [Use call_knowledge_assist with question "What is our return policy?" and the appropriate Knowledge Assistant code]

call_deepdesk​

Makes internal calls to Deepdesk's API.

Parameters:

  • path (string, required): The API endpoint path
  • method (string, required): HTTP method (GET, POST, PUT, DELETE)
  • headers (object, optional): HTTP headers for the request
  • payload (object, optional): Request body data

Example usage in prompt:

Use call_deepdesk to retrieve conversation metadata or update the conversation status.
Example:
To check if a customer has been tagged with specific labels, make an API call to retrieve conversation metadata.

validate​

Validates data against specified logic rules.

Parameters:

  • data (object, required): The data to validate
  • logic (object, required): JSONLogic rules for validation

Example usage in prompt:

Use the validate tool to check if customer-provided information meets our requirements.
Example:
When a customer provides an email address, validate that it follows the correct format.

call_url​

Makes HTTP requests to external URLs.

Parameters:

  • url (string, required): The URL to call
  • method (string, required): HTTP method (GET, POST, PUT, DELETE)
  • headers (object, optional): HTTP headers for the request
  • payload (object, optional): Request body data

Example usage in prompt:

Use call_url to retrieve information from external systems that aren't configured as APIs in Deepdesk.
Example:
To check current weather conditions, make a call to a weather API with the customer's location.

call_api​

Makes calls to pre-configured API endpoints in your Deepdesk environment.

Parameters:

  • api_code (string, required): The code of the preconfigured API to use
  • path (string, required): The API endpoint path
  • method (string, required): HTTP method (GET, POST, PUT, DELETE)
  • headers (object, optional): HTTP headers for the request
  • payload (object, optional): Request body data
  • skip_evaluation (boolean, optional): If true, skips the evaluation of this tool call

Example usage in prompt:

Use call_api when you need to access our CRM, inventory system, or other business systems.
Example:
When a customer asks about their order status:
1. Extract the order number from their message
2. Use call_api with these specific parameters:
- api_code: 'order-management-system'
- path: '/orders/{order_number}'
- method: 'GET'
3. Format the response to show:
- Current order status (e.g., "Processing", "Shipped", "Delivered")
- Estimated delivery date
- Shipping carrier and tracking number if available
4. If the API returns an error code, inform the customer their order couldn't be found and verify the order number

Skip Evaluation​

The skip_evaluation parameter is available on the call_api tool. When set to true, the tool's response will be returned directly without being evaluated by the LLM first. This can be useful for:

  • Performance optimization on simple API calls
  • Preventing the LLM from interpreting or modifying API responses
  • Ensuring exact data integrity for critical applications

Example usage in prompt for Knowledge Assist integration:

When customers ask detailed product questions, use call_api with our external knowledge system. The system will return properly formatted answers with sources, so we should use skip_evaluation to present these answers directly to the customer.
Example:
Customer: "What is the warranty period for product X?"
You: Let me check our product database for that information. [Use call_api with api_code: "knowledge-system", path: "/query", method: "POST", payload: {"question": "warranty period for product X"}, skip_evaluation: true]

Using skip_evaluation:true in this scenario allows the external system's response to be passed directly to the user without requiring the LLM to reprocess all the fields in the schema. This is particularly valuable when:

  • The external system already returns properly formatted data with the required fields
  • You want to preserve the exact formatting and content returned by the specialized system
  • You need to optimize response time by eliminating an unnecessary evaluation step

Important: When using skip_evaluation:true with Knowledge Assist responses:

  • Field keys must exactly match the schema requirements
    • answer and question are required
  • The sources field is optional but if included:
    • It must be an array of objects
    • Each object must have name and url fields
  • Additional fields will be ignored by the system
  • Missing required fields will cause the response to be rejected
  • For the exact schema format, refer to Assistant Configuration Fields

Tool Usage Best Practices​

Parameter Placeholders and Chaining Tools​

When writing instructions for assistants, you can guide them to use dynamic values from different sources:

When accessing customer information:
1. Use values from parameters with {parameters.customer_id} syntax
2. Reference metadata with {metadata.channel} syntax
3. Retrieve memory values using the format {memory.account_number}
4. Use results from previous tool calls in subsequent calls

Example of chaining tool calls:

When processing a return request:
1. Extract the order ID from the customer's message
2. Use call_api with api_code: "order-system" to retrieve the order details
3. From the response, extract the purchased items and use in your next tool call
4. Use call_api with api_code: "return-system" and include the specific item IDs from the previous response
5. Present the return options to the customer based on the final response

Example of using parameters:

When a customer contacts us:
1. Check if we have their account information using {parameters.account_id}
2. If available, use call_api with our CRM system using this account ID
3. Personalize your response using {parameters.customer_name} when greeting them

Example of using memory:

When helping with multi-step processes:
1. Ask for and store the customer's preference using write_to_memory
2. In later parts of the conversation, reference this stored preference using {memory.preference}
3. Use the stored value in subsequent tool calls without asking the customer again

Error Handling​

Always include instructions for error handling when using tools:

If the API call fails, inform the customer that the system is temporarily unavailable and offer an alternative solution.

Contextual Tool Selection​

Guide your assistant on when to use each tool:

- Use call_knowledge_assist for product questions and policies
- Use call_api with our CRM when dealing with customer account issues
- Use get_current_time when time-sensitive information is needed

Example Tool Chains​

Tools can be used together to create powerful workflows. Here are some examples to include in your assistant instructions:

Product Recommendation Workflow​

When helping customers find the right product:
1. First, use call_knowledge_assist to understand product features and compatibility
2. Then, use call_api with our product catalog to check current availability
3. Verify the product meets customer requirements
4. Present options in a clear, organized format

Account Verification Workflow​

When helping customers with account-specific questions:
1. Ask for customer identification if not already provided
2. Use write_to_memory to store the customer's account information
3. Use call_api with our CRM to verify customer identity
4. Only proceed with account-specific actions after verification

Interactive Troubleshooting Workflow​

When helping customers troubleshoot product issues:
1. Use call_knowledge_assist to identify potential solutions
2. Present options to the customer clearly
3. Based on customer response, use call_api to look up specific fixes
4. Use get_current_time if you need to schedule a follow-up

By combining tools effectively in your assistant instructions, you can create assistants that deliver personalized, context-aware solutions to complex customer needs.