Search and discovery tools

Overview

The search tools are how your assistant finds things in your organization. Most conversations start with one: the assistant searches to find the real workflow, run or template you mean, then passes its id to the other tools.

All search tools are read-only and return only resources you're allowed to see.

What all search tools share

The search tools share these filters. search_marketplace_templates has no author filter, and cross_reference takes only the resource you're asking about.

Filter	Description
Name search	Case-insensitive match on part of the name or id.
Tags	Match resources with any of the given tags.
Authors	Match resources created by any of the given user emails.
Description	Case-insensitive match on part of the description.
Context tags	key=value for an exact match, or just key to match any value.
Created and modified time	Only resources created or modified within a time range.
Sort order	Newest or oldest modified or created, or by name. Default is most recently modified.
Page size	Default 10, maximum 500. Large results come in pages that the assistant can continue through.

Most search tools also have a count mode. Instead of listing results, they return an exact total. They can also group the count into buckets, but grouped results include only the 10 largest buckets and don't say when others were left out. For more buckets, or a grouping where the smaller ones matter, the assistant should use aggregate_orchestrator_resources, which returns up to 100. Ask "how many" and the assistant will use count mode.

tip

You don't need to know the filter names. Describe what you're looking for, like "Terraform workflows in the prod group that failed this week and have no policy attached", and the assistant maps it to the right filters.

search_workflows

Finds workflows, both standalone ones and those inside stacks. It has the widest range of filters of any search tool.

Filter	Description
Last run status	For example ERRORED, COMPLETED, APPROVAL_REQUIRED, CANCELLED.
Workflow type	Terraform, OpenTofu, Custom, Ansible, CloudFormation, Kubernetes or Helm.
Workflow group or stack	Only workflows in a given workflow group or stack. A group filter returns the group's standalone workflows; workflows inside the group's stacks are found with the stack filter. You can also ask for standalone workflows only, or stack workflows only.
Template	Workflows created from a given library template, either any revision or one specific revision. Also available for workflow step templates.
Git source	Match the repository URL, branch or tag, or VCS provider. You can also ask for template-based or git-based workflows only.
Connectors and runners	Workflows using a given cloud connector or VCS connector, a connector type (such as AWS_OIDC), or a private runner group.
Drift and policy	Workflows with or without detected drift, or with or without a policy attached.
Terraform settings	For example, drift checks enabled, a specific Terraform version, or lifecycle hooks configured.
Notifications and chaining	Workflows that notify on drift, or that chain to another workflow.
Impact analysis	Workflows that chain to a given workflow, or whose plain-text environment variable values mention a given secret or another workflow's outputs. See the note below for what this doesn't cover.

In count mode, results can be grouped by workflow type, last run status, Terraform version, template or template revision.

Example prompts

"Which workflows in the production group are currently failing?"

"How many of our workflows are on each Terraform version?"

"Which workflows use the secret db-password? I want to rotate it."

"Find workflows that have drift checks enabled but no drift notification."

"What would break if I deleted the network-core workflow?"

Impact analysis is partial

The secret and output lookups only match text inside plain-text environment variable values, such as ${secret::db-password}. They don't see secret-type environment variables (/secrets/db-password), git, policy or container authentication, or IaC input values. An empty or short result doesn't mean nothing depends on the secret or workflow. Check those other places before rotating or deleting.

search_stacks

Finds stacks.

Filter	Description
Stack status	For example READY, IN_PROGRESS, ERRORED.
Template group	Stacks created from a given stack template, any revision or a pinned one.
Cloud connector	Stacks using a given cloud connector.
Drift and policy	Stacks with or without detected drift, or with or without a policy attached.

In count mode, results can be grouped by stack status.

To find stacks whose workflows are failing or waiting for approval, the assistant searches the workflows instead, with search_workflows filtered by stack and last run status.

Example prompts

"Which stacks in the engineering group have drift detected?"

"List stacks created from the three-tier-app stack template."

search_workflow_runs

Finds individual runs of workflows. Results come from the search index and can lag behind current run state. To follow a specific run after it starts, use get_workflow_run.

Filter	Description
Run id	Find a specific run. The short id you see in the dashboard (for example nfgym507nuzy) works.
Run status	For example PLAN_FAILED, APPLY_PENDING, APPLYING, APPLIED, DESTROYED.
Workflow, stack or group	All runs of one workflow (its run history), of one stack, or of a whole workflow group.
Stack runs	Only runs that were part of a stack deployment, or only standalone runs.
Resumed runs	Only runs resumed from an earlier run, or only runs that weren't.
Trigger	How the run started, such as a workflow chain, a GitHub, GitLab, Bitbucket or Azure DevOps webhook, or the Terraform CLI.
Triggered by	Runs started by given users.

In count mode, results can be grouped by workflow type or status.

Example prompts

"Show me the last five runs of payments-api."

"How many runs failed at apply in the last 7 days?"

"Which runs were triggered by GitHub webhooks today?"

search_policies

Finds governance policies. Beyond the common filters, you can find policies built from a given policy template, any revision or a pinned one.

To find which workflows or stacks have a policy attached, the assistant uses the policy filter on search_workflows or search_stacks. To find what enforces a particular policy template, it uses cross_reference.

Example prompts

"List our policies that use the aws-s3-encryption policy template."

search_orchestrator_resources

A general search across resource types that don't have a dedicated tool, or across several types at once. It covers:

• workflow runs, stacks and workflow groups
• policies
• private runner groups
• roles
• secrets (names only, never values)
• cloud connectors and VCS connectors, all at once or one specific kind

It supports type-specific filters such as stack status, run status, runner group status, template, cloud connector, drift and policy, plus a filter for the connectors inside a connector group. You can also ask for only certain fields, which keeps large lists fast.

Example prompts

"List all our cloud connectors."

"Which connectors are in the aws-accounts connector group?"

"Show me our private runner groups and their status."

search_marketplace_templates

Finds templates in your organization's own library. Templates shared from other organizations or public marketplace templates aren't included. For the templates your organization has subscribed to, see get_subscription.

Filter	Description
Template type	IaC templates (the default), policy templates, workflow step templates, or stack templates.
Text search	Matches name, id, tags, descriptions, revision notes and input field labels.
VCS connector	IaC templates whose git source uses a given VCS connector.

Example prompts

"What Terraform templates do we have for VPCs?"

"List our workflow step templates."

get_orchestrator_resource_by_id

Fetches everything about one workflow, stack, run or other resource, including the detailed configuration that search results leave out to stay small. Examples are Terraform settings, custom steps, the Terraform plan and runtime parameters.

Resource rows can also include stored PolicyEvalResults and cost fields such as InfracostBreakdown, where populated. These are the fields stored on that resource's indexed snapshot; they aren't a complete historical facts lookup for any chosen workflow run.

Your assistant uses it after a search, once it knows exactly which resource you mean.

Example prompts

"Show me the full Terraform configuration of the eks-cluster workflow."

get_marketplace_template_by_id

Fetches everything about one template or one template revision from your library, including its input form, outputs, git source and revision aliases.

Pass a specific revision to see that revision's details. The assistant can fetch two revisions to compare them.

Example prompts

"What inputs does revision 3 of the rds-postgres template take?"

"What changed between revisions 2 and 3 of rds-postgres?"

cross_reference

Answers "what uses this?" in one call. Give it one of the following and it returns the resources that reference it:

You give it	It finds
An IaC template	Workflows created from it
A policy template	Policies that enforce it
A workflow step template	Workflows that use it in any step
A stack template	Stacks created from it
A cloud connector	Workflows, stacks and runner groups that use it
A VCS connector	Workflows whose git source uses it
A private runner group	Workflows pinned to it

Templates can be matched at any revision or at one specific revision. Like the search tools, it can return a count instead of a list.

Example prompts

"Which workflows are still on revision 2 of the empty-tf-resource template?"

"What would be affected if I removed the aws-prod connector?"

aggregate_orchestrator_resources

Counts resources of one type, grouped into buckets, largest first. It answers distribution questions without listing every resource.

You can group by, for example, workflow type, last run status, run status, stack status, runner type, resource type or template. It can also be limited to the connectors inside one connector group.

Example prompts

"How many of our workflows are in each last-run status?"

"What's the status distribution of our workflow runs?"

"How many of our connectors are AWS versus Azure?"