genai_extract_tool_calls

This page explains how to use the genai_extract_tool_calls function in APL.

The genai_extract_tool_calls function extracts tool call requests from GenAI messages. When an AI model decides to use external tools or functions, it generates tool call messages. This function retrieves those calls so you can analyze what tools are being invoked.

You can use this function to monitor tool usage patterns, debug function calling, track API integrations, or analyze which tools are most frequently requested by your AI applications.

For users of other query languages

If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.

Splunk SPL users

In Splunk SPL, you would need to filter and extract tool call information from nested message structures manually.

Splunk example

| eval tool_calls=mvfilter(match(role, "assistant") AND isnotnull(tool_calls))
| eval tools=spath(tool_calls, "tool_calls")

ANSI SQL users

In ANSI SQL, you would need to unnest arrays and extract JSON fields for tool calls.

SQL example

SELECT 
  conversation_id,
  JSON_EXTRACT(content, '$.tool_calls') as tool_calls
FROM conversations
CROSS JOIN UNNEST(messages)
WHERE JSON_EXTRACT(content, '$.tool_calls') IS NOT NULL

Usage

Syntax

genai_extract_tool_calls(messages)

Parameters

• messages (dynamic, required): An array of message objects from a GenAI conversation. Each message typically contains role and content fields.

Returns

Returns a dynamic object containing the tool calls from the conversation, or null if no tool calls are found. Tool calls typically include function name, arguments, and call ID.

Use case examples

Log analysis

Analyze which tools and functions are being called by your AI system to understand integration patterns.

Query

['sample-http-logs']
| where uri contains '/api/chat'
| extend tools = genai_extract_tool_calls(todynamic(response_body)['messages'])
| where isnotnull(tools)
| extend tool_name = tostring(todynamic(tools)[0]['function']['name'])
| summarize call_count = count() by tool_name

Run in Playground

Output

tool_name	call_count
get_weather	245
search_database	189
send_email	123

This query shows which tools are most frequently called, helping you understand integration usage patterns.

List of related functions

• genai_extract_function_results: Extracts function call results. Use this to see the outcomes of the tool calls.
• genai_has_tool_calls: Checks if messages contain tool calls. Use this to quickly filter conversations with function calling.
• genai_extract_assistant_response: Extracts assistant text responses. Use this when you need the text response instead of tool calls.
• genai_get_content_by_role: Gets content by role. Use this for more granular extraction of specific message types.