# MCP Tools Reference: chronicle.googleapis.com

## Tool: `translate_udm_query`

Translates a natural language question or statement into a Chronicle UDM search query.

Use this tool to convert a human-readable search description into the UDM query syntax required by the `udm_search` tool. This tool calls the Chronicle API AiService.TranslateUDMQuery.

**Agent Responsibilities:**

- Provide the natural language text to be translated in the 'text' argument.
- Parse the raw JSON response.
- Extract the UDM query string from the 'query' field.
- Extract any suggested time range from the 'time_range' field (which contains 'startTime' and 'endTime').
- Check the 'message' field for any warnings or errors from the translation service.

**Example Usage:**

- `translate_udm_query(text="Show me all network traffic from IP 192.0.2.10 last Tuesday", projectId="my-project", customerId="my-customer", region="us")`
- `translate_udm_query(text="Find events for user 'testuser'", projectId="my-project", customerId="my-customer", region="us")`

**Next Steps (using MCP-enabled tools):**

- Use the output 'query' and 'time_range' as inputs to the `udm_search` tool to execute the search.
- If the 'query' is null or the 'message' indicates issues, refine the natural language 'text' and try again.

The following sample demonstrate how to use `curl` to invoke the `translate_udm_query` MCP tool.

| Curl Request |
|---|
| ```bash curl --location 'https://chronicle.googleapis.com/mcp' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/call", "params": { "name": "translate_udm_query", "arguments": { // provide these details according to the tool's MCP specification } }, "jsonrpc": "2.0", "id": 1 }' ``` |

## Input Schema

Request message for TranslateUDMQuery.

### TranslateUDMQueryRequest

| JSON representation |
|---|
| ``` { "projectId": string, "customerId": string, "region": string, "text": string } ``` |

| Fields ||
|---|---|
| `projectId` | `string` Google Cloud project ID. Defaults to environment configuration. |
| `customerId` | `string` Chronicle customer ID. Defaults to environment configuration. |
| `region` | `string` Chronicle region (e.g., "us", "europe"). Defaults to environment configuration. |
| `text` | `string` Natural language description of the events you want to find. |

## Output Schema

Response message for TranslateUDMQuery.

### TranslateUDMQueryResponse

| JSON representation |
|---|
| ``` { "query": string, "timeRange": { object (`https://docs.cloud.google.com/chronicle/docs/reference/mcp/tools_list/generate_synthetic_events#Output.Schema.Interval`) }, "message": string } ``` |

| Fields ||
|---|---|
| `query` | `string` Translated UDM Search query (if successful). |
| `timeRange` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/mcp/tools_list/generate_synthetic_events#Output.Schema.Interval`)`` Optional. Translated timerange (if the user specified a time range). |
| `message` | `string` Optional. Message to be shown to the user, e.g. if the translation was unsuccessful or if confidence is low. |

### Interval

| JSON representation |
|---|
| ``` { "startTime": string, "endTime": string } ``` |

| Fields ||
|---|---|
| `startTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `endTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |

### Timestamp

| JSON representation |
|---|
| ``` { "seconds": string, "nanos": integer } ``` |

| Fields ||
|---|---|
| `seconds` | `string (https://developers.google.com/discovery/v1/type-format format)` Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be between -62135596800 and 253402300799 inclusive (which corresponds to 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z). |
| `nanos` | `integer` Non-negative fractions of a second at nanosecond resolution. This field is the nanosecond portion of the duration, not an alternative to seconds. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be between 0 and 999,999,999 inclusive. |

### Tool Annotations

Destructive Hint: ❌ \| Idempotent Hint: ✅ \| Read Only Hint: ✅ \| Open World Hint: ❌