# genai_extract_tool_calls



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.

## Usage [#usage]

### Syntax [#syntax]

```kusto
genai_extract_tool_calls(messages)
```

### Parameters [#parameters]

| Name     | Type    | Required | Description                                                                                                         |
| -------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| messages | dynamic | Yes      | An array of message objects from a GenAI conversation. Each message typically contains `role` and `content` fields. |

### Returns [#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.

## Example [#example]

Extract tool calls from a GenAI conversation to analyze which functions are being invoked.

**Query**

```kusto
['otel-demo-genai']
| extend tool_calls = genai_extract_tool_calls(['attributes.gen_ai.input.messages'])
| where isnotnull(tool_calls)
| extend tool_name = tostring(tool_calls[0]['function']['name'])
| summarize call_count = count() by tool_name
| top 5 by call_count
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27otel-demo-genai%27%5D%20%7C%20extend%20tool_calls%20%3D%20genai_extract_tool_calls\(%5B%27attributes.gen_ai.input.messages%27%5D\)%20%7C%20where%20isnotnull\(tool_calls\)%20%7C%20extend%20tool_name%20%3D%20tostring\(tool_calls%5B0%5D%5B%27function%27%5D%5B%27name%27%5D\)%20%7C%20summarize%20call_count%20%3D%20count\(\)%20by%20tool_name%20%7C%20top%205%20by%20call_count%22%7D)

**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 [#list-of-related-functions]

* [genai\_extract\_function\_results](/apl/scalar-functions/genai-functions/genai-extract-function-results): Extracts function call results. Use this to see the outcomes of the tool calls.
* [genai\_has\_tool\_calls](/apl/scalar-functions/genai-functions/genai-has-tool-calls): Checks if messages contain tool calls. Use this to quickly filter conversations with function calling.
* [genai\_extract\_assistant\_response](/apl/scalar-functions/genai-functions/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](/apl/scalar-functions/genai-functions/genai-get-content-by-role): Gets content by role. Use this for more granular extraction of specific message types.

## Other query languages [#other-query-languages]

<LanguageComparisons>
  <Accordion title="Splunk SPL users">
    In Splunk SPL, you would need to filter and extract tool call information from nested message structures manually.

    <CodeGroup>
      ```sql Splunk example
      | eval tool_calls=mvfilter(match(role, "assistant") AND isnotnull(tool_calls))
      | eval tools=spath(tool_calls, "tool_calls")
      ```

      ```kusto APL equivalent
      ['ai-logs']
      | extend tools = genai_extract_tool_calls(messages)
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="ANSI SQL users">
    In ANSI SQL, you would need to unnest arrays and extract JSON fields for tool calls.

    <CodeGroup>
      ```sql 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
      ```

      ```kusto APL equivalent
      ['ai-logs']
      | extend tool_calls = genai_extract_tool_calls(messages)
      ```
    </CodeGroup>
  </Accordion>
</LanguageComparisons>