Repository navigation
Consolidate tool surface to cut MCP client context cost (v1.4.0) - #9
Merged
oysteinkrog merged 6 commits intoAug 4, 2026
Merged
Conversation
…ct_item, drop binding_info) Breaking tool-surface changes to the shared SnoopWPF.Agent MCP package, from a downstream mc-ui review. Net -4 tools (36 -> 32). - wpf_get_session_info removed; its session-info data is folded into wpf_diagnostics under a new nullable "sessionInfo" field (null when the Dispatcher probe fails). wpf_diagnostics is now the first-call tool for both health and session metadata. The inspector's GetSessionInfoAsync is unchanged. - wpf_select_item_by_index and wpf_select_item_by_scroll removed; folded into a single discriminated wpf_select_item. Callers pass exactly one of: identifier (index-string/text/substring), or index (exact zero-based). The index mode takes scrollToRealize:false (default, no realization) or scrollToRealize:true (scroll a virtualized list to materialize the container first). Passing neither or both fails with INVALID_ARGUMENT. The three inspector methods are unchanged; the consolidated tool dispatches to them. - wpf_get_binding_info removed (high error rate downstream); wpf_resolve_binding is the single binding-inspection tool. The inspector's GetBindingInfoAsync is unchanged. wpf_toggle was NOT removed. Removing it would drop a real capability that wpf_set_check_state does not cover: the engine's SetCheckStateAsync explicitly rejects bare ToggleButton and any non-ToggleButton (e.g. a checkable MenuItem), while ToggleAsync handles those via IToggleProvider. Per the review guard, this is flagged for a decision (extend set_check_state to absolute-set bare ToggleButton/MenuItem, or accept the capability drop) rather than dropping it. Updated: tool source, ToolProxyRegistrar assembly marker (and the Host/Server markers, which referenced the deleted SessionInfoTool and would not compile), llms.txt, docs/mcp-tools-reference.md, the tool-count guard, and unit + injection/integration tests. Meaningful assertions from the removed tests were ported into WpfDiagnosticsToolTests and SelectItemToolTests. Package version not bumped (owned by the leader). Co-Authored-By: Claude Opus 4.8 <[email protected]> Claude-Session: https://claude.ai/code/session_01FP4doygmRG5xEvj6CFMcZq
…rence Bead sn4: context-cost trim of the wpf_* tool [Description] strings. Each consuming agent pays for every tool description on every session, and the input/mutation tools carried ~20-40 lines of Guidelines/Limitations/Applies-to prose each. Trimmed 16 verbose tool descriptions to the essential (what it does + the discriminator/key rule + key error codes + a "See docs/mcp-tools-reference.md" pointer): click, toggle, expand_collapse, double_click, execute_command, set_text_value, set_check_state, set_slider_value, select_item, poll_changes, pump_until_idle, act_sequence, act_until, get_actionables, get_list_items, diagnostics. The detailed prose was moved into docs/mcp-tools-reference.md so nothing is lost (prose -> reference pattern; llms.txt stays the concise catalog). Most tools already had reference sections mirroring the prose; added new sections for the five that did not: double_click, get_list_items, get_actionables, act_sequence, act_until. Nothing removed from behavior: no tool names, parameter names, parameter descriptions, return shapes, or error codes changed. Load-bearing discriminators were kept in the trimmed descriptions (select_item exactly-one identifier/index + scrollToRealize; set_check_state checked/unchecked/indeterminate; expand_collapse expand/collapse; act_sequence step type enum; act_until present/absent; toggle's set_check_state rejection/suggestion). Description text in the Tools assembly dropped roughly 37.3k -> 24.2k chars (~35%). Build (BrokerHost) clean; SnoopWPF.Agent.Tests 884 passed / 4 skipped. Co-Authored-By: Claude Opus 4.8 <[email protected]> Claude-Session: https://claude.ai/code/session_01FP4doygmRG5xEvj6CFMcZq
Bump VersionPrefix to 1.4.0 for the tool-surface consolidation (fold session_info into wpf_diagnostics, merge the select_item triple into one wpf_select_item, drop wpf_get_binding_info, trim per-tool descriptions). Breaking tool-surface change. The maintainer tags v1.4.0 to publish.
…ompletion) Completes bead sn4 across the remaining wpf_* tools that the first pass (14b36d3) left untrimmed. Same prose -> reference pattern: each [Description] reduced to the essentials (what it does + key discriminators/rules + key error codes + a "See docs/mcp-tools-reference.md" pointer), with detailed field enumerations and Guidelines/Limitations prose living in the per-tool sections of docs/mcp-tools-reference.md (which already mirror it). Trimmed 15 tools: capture_screenshot, fetch_blob, find_elements, get_ancestors, get_behaviors, get_children, get_properties, get_resources, get_triggers, get_visual_tree, inspect_element, resolve_binding, run_diagnostics, set_property, wait_for_property. Left get_windows unchanged (already a single sentence with no relocatable prose). Load-bearing discriminators kept in the trimmed descriptions: find_elements operator "Equals"|"Contains"; get_triggers source enum; resolve_binding status enum (OK/PathError/ValidationError/MissingDataContext/ConverterError/NoBinding); wait_for_property present/absent + DISPATCHER_BUSY; set_property "mutation must be enabled"; capture_screenshot ELEMENT_NOT_RENDERABLE; fetch_blob BLOB_NOT_FOUND; get_visual_tree childrenTruncated + 5000-node cap. The two "check count via wpf_inspect_element first" guidelines dropped from get_triggers/get_behaviors were relocated as Usage lines in their reference sections. No behavior, tool names, parameter names/descriptions, return shapes, or error codes changed. Description text for these tools dropped 5650 -> 4205 chars (~26%). Build (BrokerHost) clean; SnoopWPF.Agent.Tests 884 passed / 4 skipped. Co-Authored-By: Claude Opus 4.8 <[email protected]> Claude-Session: https://claude.ai/code/session_01FP4doygmRG5xEvj6CFMcZq
Oracle review of the consolidation flagged the XML doc still said '27 broker-side MCP tool proxies' while the implementation registers 32 (verified: 32 [McpServerToolType] classes). Align the doc; no runtime change.
…eview) A third-model review flagged two consolidation gaps: - wpf_select_item silently dropped scrollToRealize when passed with 'identifier' (a virtualized selection then failed as not-found with no explanation). Now INVALID_ARGUMENT; scrollToRealize is bool? so an explicit value with identifier is a loud caller error. - wpf_diagnostics folded session-info behind the 1s health-probe budget with a silent null on timeout, a reliability regression vs the removed wpf_get_session_info (which awaited the caller's token). Retry the session-info fetch once on the caller token when the probe budget elapses without the caller cancelling, so a cold/loaded first-call bootstrap isn't lost. Regression: SelectItemToolTests.IdentifierWithScrollToRealize_ThrowsInvalidArgument_NotSilentlyDropped, WpfDiagnosticsToolTests.SlowProbe_RetriesOnCallerToken_RecoversSessionInfo. Suite 884 -> 886 green.
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.
Why
A downstream mc-ui (MotionCatalyst wpf-mcp broker) review found the MCP tool surface was inflating client context on every session, and that a few
wpf_*tools carried high agent error rates. This consolidates the surface and trims per-tool description prose to cut that context cost, with no loss of capability.Changes
Tool-surface consolidation (breaking):
wpf_get_session_infointowpf_diagnostics(session info is now part of the diagnostics payload).wpf_select_item,wpf_select_item_by_index,wpf_select_item_by_scroll) into one discriminatedwpf_select_item(identifiervsindex, withscrollToRealizefor virtualized containers).wpf_get_binding_info(high error rate downstream); usewpf_resolve_binding.Kept
wpf_toggledeliberately. It is complementary towpf_set_check_state, not redundant:set_check_state(L0) handles CheckBox/RadioButton and rejects bare ToggleButton, whilewpf_toggle(L1) is the only path for a bare ToggleButton, a checkable MenuItem, or anyIToggleProvidertarget. (The downstream broker already stopped auto-retrying toggle because it is non-idempotent, so its retry hazard is handled there.)Description trims (
docs(agent)): trimmed the 16 most verbose per-tool[Description]attributes to a concise essentials line and relocated the detailed Guidelines/Limitations/Applies-to prose intodocs/mcp-tools-reference.md. Nothing is lost; it moves off the wire schema into the reference.llms.txtstays the concise catalog.Versioning
Bumped
VersionPrefixto1.4.0. This is a breaking tool-surface change; releases here are tag-driven, so tagv1.4.0to publish theInitialForce.SnoopAgent.*packages.Verification
SnoopWPF.Agent.BrokerHostbuilds clean (Release).SnoopWPF.Agent.Tests: 884 passed, 4 skipped (env-gated perf/concurrency), 0 failed.ToolSurfaceCoverageTestsupdated.Based cleanly off
v1.3.0(currently identical todevelop), so it excludes the in-flightwpf-perf-idle-improvementswork by design.Downstream
After this publishes as
1.4.0, the consumingui-mcp-winuirepo bumps itsInitialForce.SnoopAgent.*PackageReferences from1.3.0to1.4.0and re-vendors.🤖 Generated with Claude Code
https://claude.ai/code/session_01FP4doygmRG5xEvj6CFMcZq