Skip to content

Add fields param to six more list/search tools#2810

Draft
tommaso-moro wants to merge 1 commit into
tommaso-moro-add-fields-param-filteringfrom
tommaso-moro-add-fields-param-remaining-tools
Draft

Add fields param to six more list/search tools#2810
tommaso-moro wants to merge 1 commit into
tommaso-moro-add-fields-param-filteringfrom
tommaso-moro-add-fields-param-remaining-tools

Conversation

@tommaso-moro

@tommaso-moro tommaso-moro commented Jul 3, 2026

Copy link
Copy Markdown
Contributor

Note

Stacked on #2775. Review/merge that PR first.

What

#2775 introduced an optional fields response-filtering parameter, gated behind the fields_param feature flag and instrumented with adoption/savings telemetry, for search_code and get_file_contents. This PR extends the exact same pattern to six more read tools:

  • list_issues
  • list_pull_requests
  • list_commits
  • list_releases
  • search_issues
  • search_pull_requests

Callers can pass fields: [...] to receive only the fields they need for each result item, reducing tool response size (and downstream context usage) on the largest, most frequently called read tools.

How

Each tool follows the dual-variant pattern established in the base PR:

  • X — the fields_param-enabled variant. Advertises the fields array parameter, filters each result item to the requested subset, and records telemetry. Owns X_ff_fields_param.snap.
  • LegacyX — the fields_param-disabled variant. Exposes the original schema (no fields), never filters, and records no telemetry — it's the kill switch when the flag is off. Owns the canonical X.snap.

Mutually exclusive FeatureFlagEnable / FeatureFlagDisable annotations guarantee exactly one variant survives inventory filtering for any flag state (asserted for all eight gated tools in Test_FieldsParamVariants_MutuallyExclusive).

Response shapes are preserved:

  • Wrapped responses (list_issues, search_issues, search_pull_requests) keep their count / pagination envelope and only filter the item list.
  • Bare-array responses (list_commits, list_releases, list_pull_requests) keep their array shape.

Shared helpers keep the surface small:

  • fieldsSchemaProperty builds the fields schema (the base PR's two tools now use it too).
  • recordFieldsUsageFor centralizes the telemetry full-size computation.
  • Filtering reuses the existing filterEachField helper.

Each field enum lists only the JSON fields the specific tool actually emits — e.g. list_commits omits stats/files (it requests commits without per-file detail) and list_issues lists only the fields its GraphQL fragment populates — so callers are never offered a field the tool cannot return.

Testing

  • Per-tool field-filtering, telemetry (filtered savings + unfiltered adoption), and Legacy* definition tests.
  • Extended the mutual-exclusivity gating test to all eight gated tools.
  • Regenerated _ff_fields_param toolsnaps and docs/feature-flags.md.
  • script/lint clean; script/test (race) green.

Extend the optional `fields` response-filtering parameter (gated behind the
`fields_param` feature flag, with adoption/savings telemetry) to six more read
tools, following the dual-variant pattern already used by search_code and
get_file_contents:

- list_issues, list_pull_requests, list_commits, list_releases
- search_issues, search_pull_requests

For each tool, `X` is the flag-enabled variant that advertises `fields` and
filters each result item to the requested subset, while `LegacyX` exposes the
original schema and never filters, acting as a kill switch when the flag is off.
Exactly one variant survives inventory filtering for any flag state via mutually
exclusive FeatureFlagEnable / FeatureFlagDisable annotations. Wrapped responses
(list_issues, search_issues, search_pull_requests) preserve their count /
pagination envelope and only filter the item list; bare-array responses keep
their array shape.

Filtering reuses the shared filterEachField helper. A new fieldsSchemaProperty
helper builds the `fields` schema (search_code and get_file_contents now use it
too), and a shared recordFieldsUsageFor helper centralizes the telemetry
full-size computation. Each field enum lists only the JSON fields the specific
tool actually emits: list_commits omits stats/files (requested without per-file
detail) and list_issues lists only the fields its GraphQL fragment populates.

Adds per-tool field-filtering, telemetry, and Legacy definition tests, extends
the mutual-exclusivity gating test to all eight gated tools, and regenerates the
`_ff_fields_param` toolsnaps and feature-flag docs.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
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.

1 participant