Query and schema tools

The MCP tools that run and validate Hamelin queries, list the datasets a query can read, and return the schemas and guides a query is written against.

execute-hamelin-query runs a query, and validate-hamelin-query checks one for errors. The dataset tools read the catalog, the schema tools return the ECS and signal references, and the guide tools return the Hamelin language guide and the resource engineering guide as text.

Tool names and schemas can change at any time

An agent sees each change the next time it reads tools/list, while a script that hard-codes a tool name or schema breaks when that tool changes.

Each section below is one tool as MCP access registers it: its title, its description, the annotations it sets, and the input and output schemas from tools/list. Field paths use parent.child for a nested object, parent[].child for the items of an array, and parent[Value].child for one variant of a field that takes several shapes.

execute-hamelin-query

Execute a Hamelin query.

Executes a Hamelin query and returns the results.

This tool runs headlessly without the user seeing the results directly.

Annotations: readOnlyHint true, idempotentHint true.

Inputs

Field	Type	Required	Description
hamelinQuery	string	Required	The Hamelin query to execute and run. Must not be empty.
timeRange	string	Required	The time range for the query (e.g. -1h..now(), -1d..now(), ts('2025-09-10T17:52:00Z')..ts('2025-09-10T17:57:00Z')). A time range is an expression constructed as {earliest}..{latest}. earliest is inclusive, latest is exclusive. Each can be a relative time expression (e.g. -1h, -1d, -1w), a function that returns a timestamp (e.g. now(), today(), yesterday(), tomorrow()), or a function ts() that takes an ISO8601 timestamp (e.g. ts('2024-04-16T17:52:00-05:00'), ts('2024-04-16T17:52:00Z')). You do not need to also add this time range to the Hamelin query using the "WITHIN" operator. Relative expressions and the today()/yesterday()/tomorrow() functions resolve in the organization's time zone — the zone stated alongside today's date in your system messages — so today() is the local calendar day, not a UTC one. Timestamps you pass to ts() are absolute and are used exactly as written. Just use this timeRange parameter only!
changesetId	string	Optional	Pattern: ^CHG_[A-Z0-9]{1,7}$.

Outputs

Field	Type	Description
queryId	string
result	object
result.columns	array of object
result.columns[].name	string
result.columns[].type	object (seven variants)	Or one of binary, boolean, interval, calendar_interval, int, double, rows, string, timestamp, unknown, variant. Nested fields omitted; see the schema in tools/list.
result.rows	array of array of unknown
errors	array of object
errors[].message	string
executionDurationMillis	number	The duration of the query execution in milliseconds.
rowCount	number
queryProgress	object
queryProgress.elapsedTimeMillis	integer	Minimum 0.
queryProgress.tasksCompleted	integer	Minimum 0.
queryProgress.tasksScheduled	integer	Minimum 0.
queryProgress.rowsScanned	integer	Minimum 0.
queryProgress.bytesScanned	integer	Minimum 0.
queryProgress.stages	array of object (two variants)
queryProgress.stages[][variant 1].stageId	integer	Minimum 1.
queryProgress.stages[][variant 1].startedAt	string	Format: date-time. Constrained by a pattern; see the schema in tools/list.
queryProgress.stages[][variant 1].finishedAt	string	Format: date-time. Constrained by a pattern; see the schema in tools/list.
queryProgress.stages[][variant 1].tasksCompleted	integer	Minimum 0.
queryProgress.stages[][variant 1].tasksScheduled	integer	Minimum 0.
queryProgress.stages[][variant 1].tasksFailed	integer	Minimum 0.
queryProgress.stages[][variant 1].completed	boolean
queryProgress.stages[][variant 1].producesResults	boolean
queryProgress.stages[][variant 1].resultRowProgress	object	Nested fields omitted; see the schema in tools/list.
queryProgress.stages[][variant 1].stage	string	Always planning.
queryProgress.stages[][variant 2].stageId	integer	Minimum 1.
queryProgress.stages[][variant 2].startedAt	string	Format: date-time. Constrained by a pattern; see the schema in tools/list.
queryProgress.stages[][variant 2].finishedAt	string	Format: date-time. Constrained by a pattern; see the schema in tools/list.
queryProgress.stages[][variant 2].tasksCompleted	integer	Minimum 0.
queryProgress.stages[][variant 2].tasksScheduled	integer	Minimum 0.
queryProgress.stages[][variant 2].tasksFailed	integer	Minimum 0.
queryProgress.stages[][variant 2].completed	boolean
queryProgress.stages[][variant 2].producesResults	boolean
queryProgress.stages[][variant 2].resultRowProgress	object	Nested fields omitted; see the schema in tools/list.
queryProgress.stages[][variant 2].id	integer	Minimum 0.
queryProgress.stages[][variant 2].firstTaskStartedAt	string	May be null. Format: date-time. Constrained by a pattern; see the schema in tools/list.
queryProgress.stages[][variant 2].stage	enum	One of scan, broadcast_build, join, join_broadcast, process, materialize, write, reduction, result.
resolvedTimeRange	string
executionTimeRange	object
executionTimeRange.start	string	Format: date-time. Constrained by a pattern; see the schema in tools/list.
executionTimeRange.end	string	Format: date-time. Constrained by a pattern; see the schema in tools/list.
executionTimeRange.endInclusive	boolean
queryExpansion	object
queryExpansion.expanded	boolean
queryExpansion.inlinedDatasets	array of string
queryExpansion.expandedQuery	string
modelResultText	string
links	array of object (three variants)
links[][resource].type	string	Always resource.
links[][resource].id	string
links[][resource].resourceKind	enum	One of CaseAlertBlock, Alert, AiProvider, Case, CaseAnalysisBlock, CaseLogBlock, CaseNoteBlock, CaseResponseActionBlock, Changeset, Chat, Comment, Connector, ContentPack, ContentPackInstallation, ContentWorkItem, Credential, Dashboard, DataPlane, Detection, Folder, HttpToolConfig, Integration, Lookup, Mapper, McpConfig, Organization, Parser, ResourceGroup, Role, Schema, Skill, Space, Table, ThreatReport, Union, User, View, WebhookConfig.
links[][resource].link	string	Canonical URL for this result. Format: uri.
links[][changeset].type	string	Always changeset.
links[][changeset].id	string
links[][changeset].link	string	Canonical URL for this result. Format: uri.
links[][query].type	string	Always query.
links[][query].id	string
links[][query].link	string	Canonical URL for this result. Format: uri.

validate-hamelin-query

Validate a Hamelin query.

Validates a Hamelin query and returns detailed error information if the query is invalid.

Annotations: readOnlyHint true, idempotentHint true.

Inputs

Field	Type	Required	Description
hamelinQuery	string	Required	The Hamelin query to validate.
schemaId	string	Optional
templateParameters	array of object (two variants)	Optional
templateParameters[][primitive].id	string	Required	Must not be empty.
templateParameters[][primitive].name	string	Required	Pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$. Must not be empty. At most 64 characters.
templateParameters[][primitive].kind	string	Required	Always primitive.
templateParameters[][primitive].type	enum	Required	One of int, double, boolean, string, interval.
templateParameters[][primitive].values	array of string	Required
templateParameters[][primitive].defaultValue	string	Optional	At most 1024 characters.
templateParameters[][primitive].description	string	Optional	At most 1024 characters.
templateParameters[][identifier_fragment].id	string	Required	Must not be empty.
templateParameters[][identifier_fragment].name	string	Required	Pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$. Must not be empty. At most 64 characters.
templateParameters[][identifier_fragment].kind	string	Required	Always identifier_fragment.
templateParameters[][identifier_fragment].values	array of string	Required
templateParameters[][identifier_fragment].defaultValue	string	Required	Pattern: ^[a-zA-Z0-9_]+$. At most 1024 characters.
templateParameters[][identifier_fragment].description	string	Optional	At most 1024 characters.
changesetId	string	Optional	Pattern: ^CHG_[A-Z0-9]{1,7}$.

Outputs

Field	Type	Description
success	boolean	Whether the query is valid.
errorCount	number
errors	array of object
errors[].message	string
links	array of object (three variants)
links[][resource].type	string	Always resource.
links[][resource].id	string
links[][resource].resourceKind	enum	One of CaseAlertBlock, Alert, AiProvider, Case, CaseAnalysisBlock, CaseLogBlock, CaseNoteBlock, CaseResponseActionBlock, Changeset, Chat, Comment, Connector, ContentPack, ContentPackInstallation, ContentWorkItem, Credential, Dashboard, DataPlane, Detection, Folder, HttpToolConfig, Integration, Lookup, Mapper, McpConfig, Organization, Parser, ResourceGroup, Role, Schema, Skill, Space, Table, ThreatReport, Union, User, View, WebhookConfig.
links[][resource].link	string	Canonical URL for this result. Format: uri.
links[][changeset].type	string	Always changeset.
links[][changeset].id	string
links[][changeset].link	string	Canonical URL for this result. Format: uri.
links[][query].type	string	Always query.
links[][query].id	string
links[][query].link	string	Canonical URL for this result. Format: uri.

get-query-performance

Get query performance.

Returns a compact performance summary for a completed query. Use the query ID from execute-hamelin-query. The summary includes data-plane processing time, scan volume, output rows, task counts, stage durations, and derived rates. Output rows per scanned row is an observed ratio for the portion of the query that ran.

Annotations: readOnlyHint true, idempotentHint true.

Inputs

Field	Type	Required	Description
queryId	string	Required	The ID of a completed query. Must not be empty.

Outputs

Field	Type	Description
queryId	string
performance	object (two variants)
performance[available].status	string	Always available.
performance[available].elapsedTimeMillis	integer	May be null. Minimum 0.
performance[available].rowsScanned	integer	Minimum 0.
performance[available].bytesScanned	integer	Minimum 0.
performance[available].outputRows	integer	Minimum 0.
performance[available].rates	object
performance[available].rates.scannedRowsPerSecond	number	May be null. Minimum 0.
performance[available].rates.scannedMebibytesPerSecond	number	May be null. Minimum 0.
performance[available].rates.outputRowsPerScannedRow	number	May be null. Minimum 0.
performance[available].stages	array of object
performance[available].stages[].stage	enum	One of planning, scan, broadcast_build, join, join_broadcast, process, materialize, write, reduction, result.
performance[available].stages[].stageId	integer	Minimum 1.
performance[available].stages[].durationMillis	integer	May be null. Minimum 0.
performance[available].stages[].tasksCompleted	integer	Minimum 0.
performance[available].stages[].tasksScheduled	integer	Minimum 0.
performance[available].stages[].tasksFailed	integer	Minimum 0.
performance[unavailable].status	string	Always unavailable.
performance[unavailable].reason	string
links	array of object (three variants)
links[][resource].type	string	Always resource.
links[][resource].id	string
links[][resource].resourceKind	enum	One of CaseAlertBlock, Alert, AiProvider, Case, CaseAnalysisBlock, CaseLogBlock, CaseNoteBlock, CaseResponseActionBlock, Changeset, Chat, Comment, Connector, ContentPack, ContentPackInstallation, ContentWorkItem, Credential, Dashboard, DataPlane, Detection, Folder, HttpToolConfig, Integration, Lookup, Mapper, McpConfig, Organization, Parser, ResourceGroup, Role, Schema, Skill, Space, Table, ThreatReport, Union, User, View, WebhookConfig.
links[][resource].link	string	Canonical URL for this result. Format: uri.
links[][changeset].type	string	Always changeset.
links[][changeset].id	string
links[][changeset].link	string	Canonical URL for this result. Format: uri.
links[][query].type	string	Always query.
links[][query].id	string
links[][query].link	string	Canonical URL for this result. Format: uri.

list-dataset-names

List dataset names.

Lists all visible dataset names in the catalog. Inspect these names to find relevant datasets, then use get-dataset-columns to read their schemas.

Annotations: readOnlyHint true, idempotentHint true.

Inputs

Field	Type	Required	Description
changesetId	string	Optional	Pattern: ^CHG_[A-Z0-9]{1,7}$.

Outputs

Field	Type	Description
datasetNames	array of string
links	array of object (three variants)
links[][resource].type	string	Always resource.
links[][resource].id	string
links[][resource].resourceKind	enum	One of CaseAlertBlock, Alert, AiProvider, Case, CaseAnalysisBlock, CaseLogBlock, CaseNoteBlock, CaseResponseActionBlock, Changeset, Chat, Comment, Connector, ContentPack, ContentPackInstallation, ContentWorkItem, Credential, Dashboard, DataPlane, Detection, Folder, HttpToolConfig, Integration, Lookup, Mapper, McpConfig, Organization, Parser, ResourceGroup, Role, Schema, Skill, Space, Table, ThreatReport, Union, User, View, WebhookConfig.
links[][resource].link	string	Canonical URL for this result. Format: uri.
links[][changeset].type	string	Always changeset.
links[][changeset].id	string
links[][changeset].link	string	Canonical URL for this result. Format: uri.
links[][query].type	string	Always query.
links[][query].id	string
links[][query].link	string	Canonical URL for this result. Format: uri.

get-dataset-columns

Get dataset columns.

Lists the columns of a dataset in the catalog.

Annotations: readOnlyHint true, idempotentHint true.

Inputs

Field	Type	Required	Description
datasetName	string	Required	The name of the dataset to get columns for.
changesetId	string	Optional	Pattern: ^CHG_[A-Z0-9]{1,7}$.

Outputs

Field	Type	Description
columns	array of object
columns[].name	string	The name of the column.
columns[].type	unknown	The type of the column.
links	array of object (three variants)
links[][resource].type	string	Always resource.
links[][resource].id	string
links[][resource].resourceKind	enum	One of CaseAlertBlock, Alert, AiProvider, Case, CaseAnalysisBlock, CaseLogBlock, CaseNoteBlock, CaseResponseActionBlock, Changeset, Chat, Comment, Connector, ContentPack, ContentPackInstallation, ContentWorkItem, Credential, Dashboard, DataPlane, Detection, Folder, HttpToolConfig, Integration, Lookup, Mapper, McpConfig, Organization, Parser, ResourceGroup, Role, Schema, Skill, Space, Table, ThreatReport, Union, User, View, WebhookConfig.
links[][resource].link	string	Canonical URL for this result. Format: uri.
links[][changeset].type	string	Always changeset.
links[][changeset].id	string
links[][changeset].link	string	Canonical URL for this result. Format: uri.
links[][query].type	string	Always query.
links[][query].id	string
links[][query].link	string	Canonical URL for this result. Format: uri.

get-ecs-schema

Get ECS schema.

Browses the ECS (Elastic Common Schema) fields that all mappers must target. Omit fieldPath to list top-level fields. Pass an exact dot-separated fieldPath to inspect that field and its direct children. Use this to confirm field names, types, and allowedValues when writing mapper queries. Categorization fields (event.kind, event.category, event.type, event.outcome) are closed vocabularies: use only their allowedValues, and leave the field unset when none fit.

Annotations: readOnlyHint true, idempotentHint true.

Inputs

Field	Type	Required	Description
fieldPath	string	Optional	Must not be empty.

Outputs

Field	Type	Description
field	object	May be null.
field.name	string	Field name relative to its parent.
field.path	string	Full dot-separated ECS field path.
field.type	string	Compact field type.
field.hasChildren	boolean	Whether the field has nested fields.
field.childCount	integer	Number of direct child fields. Minimum 0.
field.description	string
field.required	boolean
field.allowExtraFields	boolean
field.allowedValues	array of string
children	array of object
children[].name	string	Field name relative to its parent.
children[].path	string	Full dot-separated ECS field path.
children[].type	string	Compact field type.
children[].hasChildren	boolean	Whether the field has nested fields.
children[].childCount	integer	Number of direct child fields. Minimum 0.
children[].description	string
children[].required	boolean
children[].allowExtraFields	boolean
children[].allowedValues	array of string
links	array of object (three variants)
links[][resource].type	string	Always resource.
links[][resource].id	string
links[][resource].resourceKind	enum	One of CaseAlertBlock, Alert, AiProvider, Case, CaseAnalysisBlock, CaseLogBlock, CaseNoteBlock, CaseResponseActionBlock, Changeset, Chat, Comment, Connector, ContentPack, ContentPackInstallation, ContentWorkItem, Credential, Dashboard, DataPlane, Detection, Folder, HttpToolConfig, Integration, Lookup, Mapper, McpConfig, Organization, Parser, ResourceGroup, Role, Schema, Skill, Space, Table, ThreatReport, Union, User, View, WebhookConfig.
links[][resource].link	string	Canonical URL for this result. Format: uri.
links[][changeset].type	string	Always changeset.
links[][changeset].id	string
links[][changeset].link	string	Canonical URL for this result. Format: uri.
links[][query].type	string	Always query.
links[][query].id	string
links[][query].link	string	Canonical URL for this result. Format: uri.

get-signal-schema

Get signal schema.

Returns the signal schema defining the structure of signals produced by detections.

Annotations: readOnlyHint true, idempotentHint true.

Inputs

This tool takes no arguments.

Outputs

Field	Type	Description
schema	array of unknown
links	array of object (three variants)
links[][resource].type	string	Always resource.
links[][resource].id	string
links[][resource].resourceKind	enum	One of CaseAlertBlock, Alert, AiProvider, Case, CaseAnalysisBlock, CaseLogBlock, CaseNoteBlock, CaseResponseActionBlock, Changeset, Chat, Comment, Connector, ContentPack, ContentPackInstallation, ContentWorkItem, Credential, Dashboard, DataPlane, Detection, Folder, HttpToolConfig, Integration, Lookup, Mapper, McpConfig, Organization, Parser, ResourceGroup, Role, Schema, Skill, Space, Table, ThreatReport, Union, User, View, WebhookConfig.
links[][resource].link	string	Canonical URL for this result. Format: uri.
links[][changeset].type	string	Always changeset.
links[][changeset].id	string
links[][changeset].link	string	Canonical URL for this result. Format: uri.
links[][query].type	string	Always query.
links[][query].id	string
links[][query].link	string	Canonical URL for this result. Format: uri.

get-hamelin-language-guide

Hamelin language overview.

Returns a single overview of the whole Hamelin query language (syntax, operators, and how to work with data). Use this for breadth across the language.

For deeper dives into specific topics, you can use search-hamelin-documentation as well — it finds targeted excerpts via semantic search.

Annotations: readOnlyHint true, idempotentHint true.

Inputs

This tool takes no arguments.

Outputs

Field	Type	Description
hamelinPrompt	string	Overview of the Hamelin query language.
links	array of object (three variants)
links[][resource].type	string	Always resource.
links[][resource].id	string
links[][resource].resourceKind	enum	One of CaseAlertBlock, Alert, AiProvider, Case, CaseAnalysisBlock, CaseLogBlock, CaseNoteBlock, CaseResponseActionBlock, Changeset, Chat, Comment, Connector, ContentPack, ContentPackInstallation, ContentWorkItem, Credential, Dashboard, DataPlane, Detection, Folder, HttpToolConfig, Integration, Lookup, Mapper, McpConfig, Organization, Parser, ResourceGroup, Role, Schema, Skill, Space, Table, ThreatReport, Union, User, View, WebhookConfig.
links[][resource].link	string	Canonical URL for this result. Format: uri.
links[][changeset].type	string	Always changeset.
links[][changeset].id	string
links[][changeset].link	string	Canonical URL for this result. Format: uri.
links[][query].type	string	Always query.
links[][query].id	string
links[][query].link	string	Canonical URL for this result. Format: uri.

search-hamelin-documentation

Search Hamelin documentation.

Searches for pages in the Hamelin documentation that match a given query string. You can use this to find more detailed information about Hamelin features and how to use them, particularly in the context of creating complex Hamelin queries. This tool does not have any information about datasets and their contents. For those types of queries, you should use other tools like list-dataset-names and get-dataset-columns (for dataset names and schemas).

For documentation on the data source or log contents, use web_search.

When you use this tool, you should NEVER say you are using this tool or talk about how you are "searching the documentation". Just use the tool and its results silently to yourself.

Annotations: readOnlyHint true, idempotentHint true.

Inputs

Field	Type	Required	Description
query	string	Required	The query string to search for.

Outputs

Field	Type	Description
results	array of object
results[].text	string	The text of the documentation page.
links	array of object (three variants)
links[][resource].type	string	Always resource.
links[][resource].id	string
links[][resource].resourceKind	enum	One of CaseAlertBlock, Alert, AiProvider, Case, CaseAnalysisBlock, CaseLogBlock, CaseNoteBlock, CaseResponseActionBlock, Changeset, Chat, Comment, Connector, ContentPack, ContentPackInstallation, ContentWorkItem, Credential, Dashboard, DataPlane, Detection, Folder, HttpToolConfig, Integration, Lookup, Mapper, McpConfig, Organization, Parser, ResourceGroup, Role, Schema, Skill, Space, Table, ThreatReport, Union, User, View, WebhookConfig.
links[][resource].link	string	Canonical URL for this result. Format: uri.
links[][changeset].type	string	Always changeset.
links[][changeset].id	string
links[][changeset].link	string	Canonical URL for this result. Format: uri.
links[][query].type	string	Always query.
links[][query].id	string
links[][query].link	string	Canonical URL for this result. Format: uri.

search-perpetual-documentation

Search Perpetual documentation.

Searches Perpetual product documentation for concepts, resources, workflows, connector setup, and MCP tools. Use this for questions about how Perpetual works and how to use it. Use search-hamelin-documentation for Hamelin query language syntax and functions. This tool does not inspect the organization's datasets or configuration; use the resource and dataset tools for those questions.

Annotations: readOnlyHint true, idempotentHint true.

Inputs

Field	Type	Required	Description
query	string	Required	The query string to search for.

Outputs

Field	Type	Description
results	array of object
results[].text	string	The text of the documentation page.
links	array of object (three variants)
links[][resource].type	string	Always resource.
links[][resource].id	string
links[][resource].resourceKind	enum	One of CaseAlertBlock, Alert, AiProvider, Case, CaseAnalysisBlock, CaseLogBlock, CaseNoteBlock, CaseResponseActionBlock, Changeset, Chat, Comment, Connector, ContentPack, ContentPackInstallation, ContentWorkItem, Credential, Dashboard, DataPlane, Detection, Folder, HttpToolConfig, Integration, Lookup, Mapper, McpConfig, Organization, Parser, ResourceGroup, Role, Schema, Skill, Space, Table, ThreatReport, Union, User, View, WebhookConfig.
links[][resource].link	string	Canonical URL for this result. Format: uri.
links[][changeset].type	string	Always changeset.
links[][changeset].id	string
links[][changeset].link	string	Canonical URL for this result. Format: uri.
links[][query].type	string	Always query.
links[][query].id	string
links[][query].link	string	Canonical URL for this result. Format: uri.

get-resource-engineering-guide

Get resource engineering guide.

Returns a condensed engineering guide for building detections, parsers, mappers, tables, or webhooks in Perpetual. Use before creating or editing resources in a changeset.

Annotations: readOnlyHint true, idempotentHint true.

Inputs

Field	Type	Required	Description
topic	enum	Required	Which engineering guide to load: detection, parser, mapper, table, lookup, or webhook. One of detection, parser, mapper, table, lookup, webhook.

Outputs

Field	Type	Description
guide	string
links	array of object (three variants)
links[][resource].type	string	Always resource.
links[][resource].id	string
links[][resource].resourceKind	enum	One of CaseAlertBlock, Alert, AiProvider, Case, CaseAnalysisBlock, CaseLogBlock, CaseNoteBlock, CaseResponseActionBlock, Changeset, Chat, Comment, Connector, ContentPack, ContentPackInstallation, ContentWorkItem, Credential, Dashboard, DataPlane, Detection, Folder, HttpToolConfig, Integration, Lookup, Mapper, McpConfig, Organization, Parser, ResourceGroup, Role, Schema, Skill, Space, Table, ThreatReport, Union, User, View, WebhookConfig.
links[][resource].link	string	Canonical URL for this result. Format: uri.
links[][changeset].type	string	Always changeset.
links[][changeset].id	string
links[][changeset].link	string	Canonical URL for this result. Format: uri.
links[][query].type	string	Always query.
links[][query].id	string
links[][query].link	string	Canonical URL for this result. Format: uri.

Related

• MCP access, the surface these tools are registered on.
• Hamelin, the query language.
• ECS field reference and Signal schema reference, the schemas two of these tools return.