Add fields param to search_code and get_file_contents#2775
Open
tommaso-moro wants to merge 3 commits into
Open
Add fields param to search_code and get_file_contents#2775tommaso-moro wants to merge 3 commits into
tommaso-moro wants to merge 3 commits into
Conversation
tommaso-moro
force-pushed
the
tommaso-moro-add-fields-param-filtering
branch
from
de798fe to
b19ce6a
Compare
Add an optional `fields` array parameter to the `search_code` and `get_file_contents` tools so callers can request only the fields they need, reducing tool response size and context usage. - search_code: filters each result item to the selected fields while preserving the total_count / incomplete_results wrapper. - get_file_contents: filters each directory entry when listing a directory; ignored for single-file responses. Adds shared filterFields / filterEachField helpers and per-tool field enums, plus unit tests and regenerated toolsnaps and docs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
tommaso-moro
force-pushed
the
tommaso-moro-add-fields-param-filtering
branch
from
b19ce6a to
3326613
Compare
Register search_code and get_file_contents as two mutually exclusive variants gated by the new `fields_param` feature flag, following the existing dual-variant flag pattern: - The flag-enabled variant advertises the optional `fields` parameter and filters each result to the requested subset. It owns the `<tool>_ff_fields_param` toolsnap. - The Legacy* variant exposes the original schema with no `fields` parameter and never filters, acting as a kill switch when the flag is off. It owns the canonical toolsnap. Add best-effort, low-cardinality telemetry at each tool's filter point to measure adoption and realized savings: - `mcp.fields.tool_call` (increment) tagged by tool and whether the response was filtered. - `mcp.fields.bytes_full` / `bytes_sent` / `bytes_saved` (counters) tagged by tool, emitted only when a response was filtered. Tags are limited to `tool` and `filtered` to bound cardinality; repo, owner, user, query, and the requested field list are never tagged. The local server discards these via the noop metrics sink, while hosted deployments inject a real sink. Metrics accessors now fall back to a noop sink when no exporter is configured so emitting telemetry never panics. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
tommaso-moro
force-pushed
the
tommaso-moro-add-fields-param-filtering
branch
from
3326613 to
a877d9c
Compare
tommaso-moro
force-pushed
the
tommaso-moro-add-fields-param-filtering
branch
2 times, most recently
from
256394a to
a877d9c
Compare
Remove the mcp.fields.bytes_saved counter. It is derivable on the dashboard from the two remaining byte counters, since sum(bytes_full) - sum(bytes_sent) equals the total saved at any rollup, so emitting it separately is redundant. Keeping only bytes_full and bytes_sent shrinks the emitted telemetry surface. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
tommaso-moro
force-pushed
the
tommaso-moro-add-fields-param-filtering
branch
from
2414489 to
1f51e0d
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces an optional fields parameter (gated behind the fields_param feature flag) for search_code and get_file_contents to let callers request a reduced response shape, lowering tool response size and context usage while capturing adoption/effectiveness telemetry.
Changes:
- Added dual tool variants (flag-enabled + legacy kill-switch) for
search_codeandget_file_contents, with schema advertising and runtime filtering only whenfields_paramis enabled. - Implemented generic JSON-tag-driven field filtering helpers and best-effort telemetry (
mcp.fields.*) for adoption and realized byte savings. - Added unit tests for filtering behavior, telemetry emission, and inventory gating; updated toolsnaps and feature flag documentation.
Show a summary per file
| File | Description |
|---|---|
| pkg/github/tools.go | Registers both flag-enabled and legacy variants for the two tools. |
| pkg/github/search.go | Adds fields support, filtering, telemetry, and legacy variant for search_code. |
| pkg/github/search_test.go | Updates toolsnap expectations for the flag-enabled variant; adds filtering/telemetry/legacy tests. |
| pkg/github/repositories.go | Adds fields support, directory-entry filtering, telemetry, and legacy variant for get_file_contents. |
| pkg/github/repositories_test.go | Updates toolsnap expectations for the flag-enabled variant; adds filtering/telemetry/legacy tests. |
| pkg/github/minimal_types.go | Adds enums for allowed field names and generic filtering helpers. |
| pkg/github/fields_telemetry.go | Adds shared low-cardinality telemetry emission helper for fields usage. |
| pkg/github/fields_telemetry_test.go | Adds unit tests validating telemetry behavior with a recording sink. |
| pkg/github/fields_param_gating_test.go | Verifies inventory exposes exactly one variant per tool and advertises fields only when enabled. |
| pkg/github/feature_flags.go | Adds fields_param to the allowlist of user-enableable feature flags. |
| pkg/github/dependencies.go | Makes Metrics() safe when observability exporters aren’t wired (returns noop). |
| pkg/github/toolsnaps/search_code_ff_fields_param.snap | Adds toolsnap for the flag-enabled search_code schema. |
| pkg/github/toolsnaps/get_file_contents_ff_fields_param.snap | Adds toolsnap for the flag-enabled get_file_contents schema. |
| docs/feature-flags.md | Documents the fields_param flag and the fields parameter for both tools. |
Review details
- Files reviewed: 14/14 changed files
- Comments generated: 0
- Review effort level: Low
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds an optional
fieldsarray parameter tosearch_codeandget_file_contentsso callers can request only the fields they need, reducing tool response size and context usage. The feature is gated behind thefields_paramfeature flag and instrumented so we can measure adoption and realized savings.How
fieldsfiltering —search_codefilters each result item (selectable:name,path,sha,repository,text_matches);get_file_contentsfilters each directory entry (selectable:type,name,path,size,sha,url,git_url,html_url,download_url). Filtering is ignored for single-file responses. Whenfieldsis omitted, behavior is unchanged.fieldsand filters, and a legacy variant with the original schema that acts as a kill switch when the flag is off. When the flag is off,fieldsis not advertised at all.mcp.fields.tool_call(adoption) andmcp.fields.bytes_full/bytes_sent(effectiveness). Tags are limited totoolandfilteredso cardinality stays bounded.Filtering is done by a small generic helper (
filterFields/filterEachFieldinminimal_types.go) that marshals each result item to JSON, decodes it to amap[string]any, and keeps only the requested keys. I opted for this so field names stay in sync with each type's json tags and one helper works for every tool.Testing
_ff_fields_paramsnapshots; the legacy variants own the canonical snapshots. README anddocs/feature-flags.mdregenerated.script/lintclean;script/test(full race suite) passing.Example Tool Call