Skip to content

Add filter argument to components tool#68

Merged
derek-etherton-opslevel merged 2 commits intomainfrom
component-filtering
Jul 28, 2025
Merged

Add filter argument to components tool#68
derek-etherton-opslevel merged 2 commits intomainfrom
component-filtering

Conversation

@derek-etherton-opslevel
Copy link
Copy Markdown
Contributor

@derek-etherton-opslevel derek-etherton-opslevel commented Jul 22, 2025

Blocked on #69.

Problem

The components tool does not allow filtering, which means any queries for components must pull down all components in the account. This produces several large issues:

  1. More tokens are used than should be necessary pulling down and scanning through a bunch of unnecessary data. This has a direct cost.
  2. Large accounts or "dumber" agents will run out of context entirely trying to store thousands of components in context
  3. Any reporting-style queries that reference fields not returned by the components list tool directly are impossible to resolve, because the agent must fetch resourceDetails for each individual component. Allowing filtering on these fields gets around the issue in an efficient way.

Solution

Add a filter argument to the components tool.

The filter is based on our recently-publicized ServiceFilterInput in GraphQL. It takes the recursive shape of:

type componentFilter struct {
	Key        string           `json:"key,omitempty"`
	Type       string           `json:"type,omitempty"`
	Arg        string           `json:"arg,omitempty"`
	Connective string           `json:"connective,omitempty"`
	Predicates []componentFilter `json:"predicates,omitempty"`
}

Where a "simple" / "leaf" filter provides only Key, Type, and Arg, but a compound filter provides a list of Predicates along with a Connective.

To supplement usage of these filters, also adds an accountMetadata tool. This tool is a catch-all for important contextual account information that isn't likely to be queried on its own. It takes in an array of types which determines what it queries & returns.

Examples

Who owns the Rails Monolith? - now can fetch & return one single component, instead of paginating the entire account.

Screenshot 2025-07-22 at 1 59 19 PM

list all components owned by Team Dunderberg - simple filter with some prework (get GID)

Screenshot 2025-07-22 at 2 40 23 PM Screenshot 2025-07-22 at 2 41 43 PM

Fetch me all components written in Python or Ruby that are not in LTS - reporting-style query

Screenshot 2025-07-22 at 1 44 17 PM

Generate a condensed report of all Tier 1 and 2 components below Gold level that are not type "Vendor". Group the components by owning team, and include the team's Slack channel for contact. - complex reporting query

Screenshot 2025-07-22 at 1 57 19 PM

Checklist

  • I have run this code, and it appears to resolve the stated issue.
  • This PR has no user interface changes or has already received approval from product management to change the interface.
  • Make a changie entry that explains the customer facing outcome of this change.

@derek-etherton-opslevel derek-etherton-opslevel changed the base branch from main to add-account-metadata July 22, 2025 21:24
Comment thread src/cmd/root.go
For complete reference:
- Keys: aliases, alert_status, component_type_id, creation_source, deploy_environment, domain_id, filter_id, framework, group_ids, language, level_index, lifecycle_index, name, owner_id, owner_ids, product, properties, property, relationship, repository_ids, system_id, tag, tags, tier_index
- Types: belongs_to, contains, does_not_contain, does_not_equal, does_not_exist, does_not_match, does_not_match_regex, ends_with, equals, exists, greater_than_or_equal_to, less_than_or_equal_to, matches, matches_regex, satisfies_jq_expression
`),
Copy link
Copy Markdown
Contributor Author

@derek-etherton-opslevel derek-etherton-opslevel Jul 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Still can't find much in the way of concrete recommendations for tool description length, tool description vs argument description, etc. Having this detail in the top-level description should be better for planning, since most of these filters will require a bit of pre-work (fetching account metadata, team id, etc). Anywho this seems to work well and it's about as short + scannable as I can get it (yes I had AI go over it a few times).

Without a precise mapping from key <-> arg <-> predicate type, the agent will occasionally make a bad query, but the API errors are good enough that it can succeed on second shot. e.g. if it tries to query satisfies_jq_expression on a name, there will be an API error that states the supported predicate types. This is a worthy trade-off, because a complete mapping is brittle + a lot of context.

@derek-etherton-opslevel derek-etherton-opslevel changed the title Add filter options to components tool Add filter argument to components tool Jul 22, 2025
Comment thread src/cmd/root.go Outdated
Comment thread src/cmd/root.go Outdated
Copy link
Copy Markdown
Contributor

@wesleyjellis wesleyjellis left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Works for me

Base automatically changed from add-account-metadata to main July 23, 2025 19:12
@derek-etherton-opslevel derek-etherton-opslevel merged commit facbe8c into main Jul 28, 2025
2 checks passed
@derek-etherton-opslevel derek-etherton-opslevel deleted the component-filtering branch July 28, 2025 17:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants