Skip to content

Consolidate tool surface to cut MCP client context cost (v1.4.0) - #9

Merged
oysteinkrog merged 6 commits into
InitialForce:developfrom
oysteinkrog:ergo/tool-surface-trim
Aug 4, 2026
Merged

oysteinkrog merged 6 commits into
InitialForce:developfrom
oysteinkrog:ergo/tool-surface-trim

Conversation

@oysteinkrog

Copy link
Copy Markdown
Member

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):

  • Fold wpf_get_session_info into wpf_diagnostics (session info is now part of the diagnostics payload).
  • Merge the three selection tools (wpf_select_item, wpf_select_item_by_index, wpf_select_item_by_scroll) into one discriminated wpf_select_item (identifier vs index, with scrollToRealize for virtualized containers).
  • Remove wpf_get_binding_info (high error rate downstream); use wpf_resolve_binding.
  • Net: four tools removed/merged from the published surface.

Kept wpf_toggle deliberately. It is complementary to wpf_set_check_state, not redundant: set_check_state (L0) handles CheckBox/RadioButton and rejects bare ToggleButton, while wpf_toggle (L1) is the only path for a bare ToggleButton, a checkable MenuItem, or any IToggleProvider target. (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 into docs/mcp-tools-reference.md. Nothing is lost; it moves off the wire schema into the reference. llms.txt stays the concise catalog.

Versioning

Bumped VersionPrefix to 1.4.0. This is a breaking tool-surface change; releases here are tag-driven, so tag v1.4.0 to publish the InitialForce.SnoopAgent.* packages.

Verification

  • SnoopWPF.Agent.BrokerHost builds clean (Release).
  • SnoopWPF.Agent.Tests: 884 passed, 4 skipped (env-gated perf/concurrency), 0 failed.
  • Tests referencing removed tools were deleted or ported to the surviving tools; ToolSurfaceCoverageTests updated.
  • Integration tests that require live WPF injection were not run headless.

Based cleanly off v1.3.0 (currently identical to develop), so it excludes the in-flight wpf-perf-idle-improvements work by design.

Downstream

After this publishes as 1.4.0, the consuming ui-mcp-winui repo bumps its InitialForce.SnoopAgent.* PackageReferences from 1.3.0 to 1.4.0 and re-vendors.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FP4doygmRG5xEvj6CFMcZq

oysteinkrog and others added 6 commits August 3, 2026 13:43
…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.
@oysteinkrog
oysteinkrog merged commit 6786a34 into InitialForce:develop Aug 4, 2026
5 checks passed
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