Kusto Tools

TL;DR

• Standardize incident queries — Same proven KQL runs every time, no variations
• Turn tribal knowledge into reusable tools — Your best queries become shared capabilities
• Query with parameters — Users ask in plain language, agent substitutes values automatically
• Test before deploy — Validate queries execute correctly before adding to custom agents

The problem: Everyone writes their own queries

During incidents, your team's senior engineers have battle-tested queries that find issues fast. But that knowledge is stuck in their heads, Slack threads, and personal notebooks. When they're not on-call, less experienced responders waste time:

• Reinventing queries from scratch, often with mistakes
• Writing overly broad queries that return too much data or miss edge cases
• Missing critical columns that would reveal the root cause
• Using wrong time windows or forgetting to filter by environment

Each engineer queries the same data differently. One finds the issue in 5 minutes. Another spends 30 minutes going in circles with ad-hoc KQL.

What Kusto tools solve

Kusto tools let you codify your best queries as reusable, parameterized tools. The agent executes the exact query you write—no interpretation, no variation. Your team's expertise becomes a shared capability.

What changes:

Before	After
Senior engineer writes query from memory	Query is saved as a tool, anyone can use it
On-call guesses at time ranges and filters	Parameters prompt for what's needed
Each responder gets different results	Same query runs every time
Complex joins must be remembered	Multi-step logic is pre-built

Example: Instead of asking on-call to "figure out how to query error logs," they just ask the agent:

Show me errors from the last 24 hours

The agent uses your pre-built tool with timeRange=24h, returning exactly the columns and filters your team needs.

How it works

1. Connect — Add your Azure Data Explorer cluster as a connector
2. Create — Define queries with parameters using ##parameterName## syntax
3. Test — Validate the query executes correctly in the portal
4. Attach — Add the tool to a custom agent
5. Use — Agent calls the tool when user questions match the tool's description

Two approaches to data queries

When you add an ADX connector, choose between deterministic or flexible queries:

Approach	Description	Use when
Database query connector	Agent uses predefined queries (Kusto tools)	You want deterministic, exact queries
Database indexing connector	Agent generates queries by learning your schema	You want flexible, ad-hoc queries

Creating a Kusto tool

Create tools in Builder → Agent Canvas → Create → Tool → Kusto tool. Each tool needs a name, description, connector, database, and KQL query with optional ##paramName## parameter placeholders.

For the full walkthrough with screenshots, see the Create a Kusto tool tutorial.

Adding a tool to a custom agent

After creating your tool, attach it to a custom agent via the canvas view + button → Add existing tools.

Prerequisites

Azure Data Explorer permissions

The agent's managed identity needs the AllDatabasesViewer role on your ADX cluster.

Using a KQL management command:

.add cluster AllDatabasesViewer ('aadapp=<ManagedIdentityClientId>;<TenantId>')

Or through the Azure portal: Navigate to your ADX cluster → Security + networking → Permissions → Add → AllDatabasesViewer.

Kusto connector

Before creating tools, set up an ADX connector. When adding the connector:

• Choose Database query connector (for predefined queries, not schema learning)
• Use the full cluster URL including database: https://mycluster.eastus.kusto.windows.net/mydatabase

Parameterized queries

Make your tools flexible with parameters using ##parameterName## syntax:

AppEvents
| where TimeGenerated > ago(##timeRange##)
| where EventLevel == "Error"
| where Message contains "##searchPattern##"
| take 100

When the agent uses this tool, it substitutes parameters based on user input:

User says	Agent substitutes
"errors from the last day"	timeRange=24h
"find null pointer exceptions"	searchPattern=NullPointerException

Parameters let one tool handle many variations of the same question.

Execution modes (YAML)

When defining tools in YAML, choose an execution mode:

Mode	Description	Use when
Query	Execute an inline KQL query	Most common—query is defined directly in YAML
Function	Call a stored function on the cluster	Query logic is defined in ADX as a function
Script	Run a KQL script from an external file	Complex multi-statement queries

# Query mode (most common)
spec:
  mode: Query
  query: |-
    AppEvents | take 10

# Function mode
spec:
  mode: Function
  function: GetRecentErrors

Query best practices

Use appropriate time ranges — Default to recent data:

| where TimeGenerated > ago(1h)

Add result limits — Prevent overwhelming output:

| take 100

Include helpful projections — Return only columns the agent needs:

| project TimeGenerated, Name, DurationMs, ResultCode

When to use Kusto tools vs. ad-hoc queries

Scenario	Kusto tools	Ad-hoc queries
Standardized runbook steps	✅
Repeatable investigation patterns	✅
Complex multi-join queries	✅
Exploring unfamiliar data		✅
One-time investigations		✅

Get started

Resource	What you'll learn
Create a Kusto tool →	Step-by-step walkthrough with screenshots

Related capabilities

Capability	What it adds
Custom agents →	Assign tools to specialized custom agents
Connectors →	Connect other data sources