Retrieves a list of all Kusto services known to the MCP.
Could be null if no services are configured.

:return: List of objects, {"service": str, "description": str, "default_database": str}

Executes a KQL query on the specified database. If no database is provided,
it will use the default database.

:param query: The KQL query to execute.
:param cluster_uri: The URI of the Kusto cluster.
:param database: Optional database name. If not provided, uses the default database.
:param client_request_properties: Optional dictionary of additional client request properties.
:return: The result of the query execution as a list of dictionaries (json).

Executes a kusto management command on the specified database. If no database is provided,
it will use the default database.

:param command: The kusto management command to execute.
:param cluster_uri: The URI of the Kusto cluster.
:param database: Optional database name. If not provided, uses the default database.
:param client_request_properties: Optional dictionary of additional client request properties.
:return: The result of the command execution as a list of dictionaries (json).

Retrieves a list of all entities (databases, tables, external tables, materialized views,
functions, graphs) in the Kusto cluster.

:param entity_type: Type of entities to list: "databases", "tables", "external-tables",
"materialized-views", "functions", "graphs".
:param database: The name of the database to list entities from.
Required for all types except "databases" (which are top-level).
:param cluster_uri: The URI of the Kusto cluster.
:param client_request_properties: Optional dictionary of additional client request properties.

:return: List of dictionaries containing entity information.

Retrieves schema information for all entities (tables, external tables, materialized views,
functions, graphs) in the specified database.

In most cases, it would be useful to call kusto_sample_entity() to see *actual* data samples,
since schema information alone may not provide a complete picture of the data (e.g. dynamic columns, etc...)

:param cluster_uri: The URI of the Kusto cluster.
:param database: The name of the database to get schema for.
:param client_request_properties: Optional dictionary of additional client request properties.
:return: List of dictionaries containing entity schema information.

Retrieves the schema information for a specific entity (table, external table,
materialized view, function, graph) in the specified database.
If no database is provided, uses the default database.

:param entity_name: Name of the entity to get schema for.
:param entity_type: Type of the entity (table, external-table, materialized-view, function, graph).
:param cluster_uri: The URI of the Kusto cluster.
:param database: Optional database name. If not provided, uses the default database.
:param client_request_properties: Optional dictionary of additional client request properties.
:return: List of dictionaries containing entity schema information.

Intelligently executes a graph query using snapshots if they exist,
otherwise falls back to transient graphs.
If no database is provided, uses the default database.

:param graph_name: Name of the graph to query.
:param query: The KQL query to execute after the graph() function.
Must include proper project clause for graph-match queries.
:param cluster_uri: The URI of the Kusto cluster.
:param database: Optional database name. If not provided, uses the default database.
:param client_request_properties: Optional dictionary of additional client request properties.
:return: List of dictionaries containing query results.

Critical:
* Graph queries must have a graph-match clause and a projection clause.
Optionally they may contain a where clause.
* Graph entities are only accessible in the graph-match scope.
    When leaving that scope (sub-sequent '|'), the data is treated as a table,
    and graph-specific functions (like labels()) will not be available.
* Always prefer expressing everything with graph patterns.
  Avoid using graph-to-table operator unless you have no other way around it.
* There is no id() function on graph entities. If you need a unique identifier,
  make sure to check the schema and use an appropriate property.
* There is no `type` property on graph entities.
  Use `labels()` function to get the list of labels for a node or edge.
* Properties that are used outside the graph-match context are renamed to `_` instead of `.`.
  For example, `node.name` becomes `node_name`.
* For variable length paths, you can use `all` or `any` to enforce conditions on all/any edges
  in variable path length elements (e.g. `()-[e*1..3]->() where all(e, labels() has 'Label')`).

Examples:

# Basic node counting with graph-match (MUST include project clause):
kusto_graph_query(
    "MyGraph",
    "| graph-match (node) project labels=labels(node)
     | mv-expand label = labels
     | summarize count() by tostring(label)",
    cluster_uri
)

# Relationship matching:
kusto_graph_query(
    "MyGraph",
    "| graph-match (house)-[relationship]->(character)
        where labels(house) has 'House' and labels(character) has 'Character'
        project house.name, character.firstName, character.lastName
    | project house_name=house_name, character_full_name=character_firstName + ' ' + character_lastName
    | limit 10",
    cluster_uri
)

# Variable length path matching:
kusto_graph_query(
    "MyGraph",
    "| graph-match (source)-[path*1..3]->(m)-[e]->(target)
        where all(path, labels() has 'Label')
        project source, destination, path, m, e, target
    | take 100",
    cluster_uri
)

Retrieves a data sample from the specified entity.
If no database is provided, uses the default database.

:param entity_name: Name of the entity to sample data from.
:param entity_type: Type of the entity (table, external-table, materialized-view, function, graph).
:param cluster_uri: The URI of the Kusto cluster.
:param sample_size: Number of records to sample. Defaults to 10.
:param database: Optional database name. If not provided, uses the default database.
:param client_request_properties: Optional dictionary of additional client request properties.
:return: List of dictionaries containing sampled records.

Ingests inline CSV data into a specified table. The data should be provided as a comma-separated string.
If no database is provided, uses the default database.

:param table_name: Name of the table to ingest data into.
:param data_comma_separator: Comma-separated data string to ingest.
:param cluster_uri: The URI of the Kusto cluster.
:param database: Optional database name. If not provided, uses the default database.
:param client_request_properties: Optional dictionary of additional client request properties.
:return: List of dictionaries containing the ingestion result.

Retrieves KQL query examples that semantically resemble the user's prompt.

IMPORTANT: Call this tool BEFORE writing any KQL query. The returned shots contain
expert-written KQL examples that reveal the correct databases, tables, column names,
and query patterns for this cluster. Without this context, you are likely to query
the wrong table or database.

Use this to:
- Discover which databases and tables contain the data you need
- Learn the correct column names and schema for a given domain
- Find proven query patterns as starting points

The returned shots come from a curated collection of expert-written examples
paired with natural language descriptions.

:param prompt: The user prompt to find similar shots for.
:param shots_table_name: Name of the table containing the shots. The table should have "EmbeddingText" (string)
                         column containing the natural language prompt, "AugmentedText" (string) column containing
                         the respective KQL, and "EmbeddingVector" (dynamic) column containing the embedding vector
                         for the NL.
                         If not provided, uses the KUSTO_SHOTS_TABLE environment variable.
:param cluster_uri: The URI of the Kusto cluster.
:param sample_size: Number of most similar shots to retrieve. Defaults to 3.
:param database: Optional database name. If not provided, uses the "AI" database or the default database.
:param embedding_endpoint: Optional endpoint for the embedding model to use. If not provided, uses the
                         AZ_OPENAI_EMBEDDING_ENDPOINT environment variable. If no valid endpoint is set,
                         this function should not be called.
:param client_request_properties: Optional dictionary of additional client request properties.
:return: List of dictionaries containing the shots records.

Build a deeplink URL that opens the given KQL query in the appropriate web explorer UI.

For Azure Data Explorer clusters, opens in Kusto Web Explorer (dataexplorer.azure.com).
For Microsoft Fabric Eventhouse clusters, opens in the Fabric query workbench.

The cluster type is auto-detected from the URI. If detection fails,
falls back to querying the cluster with `.show version`.

:param cluster_uri: The URI of the Kusto cluster.
:param database: The database name.
:param query: The KQL query text.
:return: A deeplink URL string, or None if the cluster type could not be determined.

Retrieves the query execution plan without actually running the query.
This is significantly lighter than execution and useful for understanding
performance characteristics and estimating query impact.

:param query: The KQL query to get the execution plan for.
:param cluster_uri: The URI of the Kusto cluster.
:param database: Optional database name. If not provided, uses the default database.
:param client_request_properties: Optional dictionary of additional client request properties.
:return: A compact dictionary with the following keys:
    * query_text — the query as received by the engine
    * stats — planning statistics: Duration, PlanSize (bytes), RelopSize (bytes)
    * relop_tree — the logical operator tree (compact JSON)
    * execution_hints — extracted from the physical plan:
        * estimated_rows — total row count the engine expects to process
        * concurrency — parallelism hint (-1 = auto, 1 = parallel partitions)
        * spread — node spread hint (-1 = auto, 1 = distributed)
        * shard_scans — per-shard info: total_rows and has_selection (filter applied)
    * error — if the query has semantic errors (e.g., bad column name), this contains
        the error message. The query is NOT executed.

Critical:
* This does NOT execute the query — it only generates the plan.
* The plan shows the logical operators the engine would use.
* Use this to estimate cost and understand performance before running expensive queries.
* PlanSize indicates the overall plan complexity; RelopSize indicates the logical tree size.
* execution_hints.estimated_rows and shard_scans reveal the data volume the engine expects to scan.
* has_selection=true in shard_scans means a filter narrows the scan (extent pruning applies).

Runs a suite of diagnostic commands and returns a JSON summary of the cluster's
current state. Each section runs independently — if a command fails (e.g., due to
permissions or unsupported features), that section returns an error while others
continue normally.

:param cluster_uri: The URI of the Kusto cluster.
:param database: Optional database name. If not provided, uses the default database.
:param client_request_properties: Optional dictionary of additional client request properties.
:return: A dictionary with keys for each diagnostic area. Each value is either a list
         of row-dicts or {"error": "<message>"} if that command failed.

Sections returned:
* capacity — resource utilization limits (total, consumed, remaining per resource)
* cluster — cluster node info and state
* principal_roles — caller's permission scope and role
* diagnostics — internal cluster diagnostics (health, latency, utilization)
* workload_groups — configured workload groups and their policies
* rowstores — rowstore state and memory usage
* ingestion_failures — ingestion failures from the last 24 hours

List all Eventstream items in a workspace.
Authentication is handled transparently using Azure Identity.

:param workspace_id: The workspace ID (UUID)
:return: List of eventstream items

Get an Eventstream item by workspace and item ID.
Authentication is handled transparently using Azure Identity.

:param workspace_id: The workspace ID (UUID)
:param item_id: The eventstream item ID (UUID)
:return: Eventstream item details

Get the definition of an Eventstream item.
Authentication is handled transparently using Azure Identity.

:param workspace_id: The workspace ID (UUID)
:param item_id: The eventstream item ID (UUID)
:return: Eventstream definition

Create an Eventstream item in Microsoft Fabric.
Authentication is handled transparently using Azure Identity.

User-friendly options:
- Provide only eventstream_name: Auto-generates IDs and creates basic eventstream
- Provide only eventstream_id: Auto-generates name as "Eventstream_YYYYMMDD_HHMMSS"
- Provide both: Uses your specified values
- Provide full definition: Advanced users can specify complete eventstream config

:param workspace_id: The workspace ID (UUID)
:param eventstream_name: Name for the new eventstream (auto-generated if not provided)
:param eventstream_id: ID for the eventstream (auto-generated if not provided)
:param definition: Eventstream definition (auto-generated basic one if not provided)
:param description: Optional description for the eventstream
:return: Created eventstream details

Update an Eventstream item by workspace and item ID.
Authentication is handled transparently using Azure Identity.

:param workspace_id: The workspace ID (UUID)
:param item_id: The eventstream item ID (UUID)
:param definition: Updated eventstream definition
:return: Updated eventstream details

Delete an Eventstream item by workspace and item ID.
Authentication is handled transparently using Azure Identity.

:param workspace_id: The workspace ID (UUID)
:param item_id: The eventstream item ID (UUID)
:return: Deletion confirmation

Start a new eventstream definition builder session.

:param name: Name of the eventstream to create
:param description: Optional description of the eventstream
:return: Session information and next steps

Get the current eventstream definition.

:param session_id: Builder session ID
:return: Current definition

Clear the current eventstream definition and start over.

:param session_id: Builder session ID
:return: Confirmation of clearing

Add a sample data source to the eventstream definition.

:param session_id: Builder session ID
:param sample_type: Type of sample data (Bicycles, Stock, etc.)
:param source_name: Name for the source (auto-generated if not provided)
:return: Updated definition summary

Add a custom endpoint source to the eventstream definition.

:param session_id: Builder session ID
:param source_name: Name for the source (auto-generated if not provided)
:param endpoint_url: Custom endpoint URL (deprecated - use data connections instead)
:return: Updated definition summary

Add a derived stream to the eventstream definition.

:param session_id: Builder session ID
:param stream_name: Name for the stream
:param input_nodes: List of node names (sources, operators, or other streams) that feed this stream.
                   If None and only one stream exists, automatically connects to that stream.
:return: Updated definition summary

Add an Eventhouse destination to the eventstream definition.

:param session_id: Builder session ID
:param workspace_id: Fabric workspace ID
:param item_id: Eventhouse item ID
:param database_name: Target database name
:param table_name: Target table name
:param input_streams: List of stream names that feed this destination
:param destination_name: Name for the destination (auto-generated if not provided)
:param data_ingestion_mode: Ingestion mode (ProcessedIngestion or DirectIngestion)
:param encoding: Input encoding
:return: Updated definition summary

Add a custom endpoint destination to the eventstream definition.

:param session_id: Builder session ID
:param input_streams: List of stream names that feed this destination
:param destination_name: Name for the destination (auto-generated if not provided)
:param endpoint_url: Custom endpoint URL (deprecated - use data connections instead)
:param method: HTTP method (deprecated)
:param headers: Optional HTTP headers (deprecated)
:return: Updated definition summary

Validate the current eventstream definition.

:param session_id: Builder session ID
:return: Validation results

Create an eventstream in Fabric from the current definition.

:param session_id: Builder session ID
:param workspace_id: Target Fabric workspace ID
:return: Creation results

List available components for building eventstreams.

:return: Available components

    Use this tool to list all Activator artifacts in a workspace.

    :param workspace_id: The workspace ID (UUID)
    :return: List of activator artifacts
    

    Use this tool create an alert that will fire when the source generates data.

    :param workspace_id: The workspace ID (UUID)
    :param trigger_name: Name of the trigger
    :param kql_cluster_url: The KQL cluster URL
    :param kql_database: The KQL database name
    :param kql_query: The KQL query to monitor. The query MUST be appropriate for the schema of the underlying
        data, otherwise the alert will not function correctly
    :param alert_recipient: Email address of the alert recipient
    :param alert_message: Alert message for the trigger
    :param alert_headline: Alert headline for the trigger
    :param alert_type: Type of alert - "teams" or "email" (defaults to "teams")
    :param kql_polling_frequency_minutes: Polling frequency in minutes. Must be one of: 5, 15, 60, 180, 360, 720,
        1440 (defaults to 5)
    :param artifact_id: If specified, the trigger will be created in the specified Activator artifact.
        If left blank, a new Activator artifact will be created.
    :return: Created trigger details:
        * url: URL back to the trigger in Fabric UI for further management
        * id: Artifact ID if a new one was created
        * displayName: Name of newly created trigger

    Critical:
    * This API call will NOT tell the caller if a KQL query is used which does not match the source data schema,
    so any KQL query should be double-checked upfront.
    

List all Map items in a workspace.
Authentication is handled transparently using Azure Identity.

:param workspace_id: The workspace ID (UUID)
:return: The list of map items in the specified workspace or error details

Get a Map item by workspace and item ID.
Authentication is handled transparently using Azure Identity.

:param workspace_id: The workspace ID (UUID) of the Map item
:param item_id: The map item ID (UUID)
:return: Map item details

Get the definition of a Map item.
Authentication is handled transparently using Azure Identity.

:param workspace_id: The workspace ID (UUID)
:param item_id: The map item ID (UUID)
:return: Map definition

Create a Map item in Microsoft Fabric.
Authentication is handled transparently using Azure Identity.

:param workspace_id: The workspace ID (UUID)
:param map_name: Name for the new map item
:param definition: Map item definition (auto-generated basic one if not provided)
:param description: Optional description for the map
:param folder_id: Optional folder ID (UUID) to place the map in.
If not specified, the Map is created with the workspace root folder.
:return: Created map details

Update a Map item's definition by workspace and item ID.
Authentication is handled transparently using Azure Identity.

:param workspace_id: The workspace ID (UUID)
:param item_id: The map item ID (UUID)
:param definition: Updated map definition
:return: Updated map details

Update a Map item's display name and description by workspace and item ID.
Authentication is handled transparently using Azure Identity.

:param workspace_id: The workspace ID (UUID)
:param item_id: The Map item ID (UUID)
:param display_name: The Map display name. The display name must follow naming rules according to item type.
:param description: The Map description. Maximum length is 256 characters.
:return: Updated map details

Delete a Map item by workspace and item ID.
Authentication is handled transparently using Azure Identity.

:param workspace_id: The workspace ID (UUID)
:param item_id: The map item ID (UUID)
:return: Error details or empty response on success