feat(mcp): support progressive tool loading via _meta hints#120
Draft
feat(mcp): support progressive tool loading via _meta hints#120
Conversation
Add optional alwaysLoad and searchHint fields to ToolDefinition, forward them through GET /tools, and emit them as _meta["anthropic/alwaysLoad"] / _meta["anthropic/searchHint"] in the MCP ListTools response. Claude Code's ToolSearch defers MCP tools by default; tools marked alwaysLoad stay in context on every turn, and searchHint feeds the BM25 ranker so deferred tools surface for relevant queries. Mark the core discovery + interaction tools as alwaysLoad so Claude never has to round-trip through ToolSearch to tap the screen: describe, debugger-component-tree, screenshot, gesture-tap, gesture-swipe, launch-app, run-sequence. Everything else defers.
filip131311
reviewed
Apr 15, 2026
Collaborator
filip131311
left a comment
filip131311
left a comment
There was a problem hiding this comment.
we have a tool for restarting the app we shoud add it to the curated list:
describe
debugger-component-tree
screenshot
gesture-tap
gesture-swipe
launch-app
run-sequence
as it is vital for othere tools that depend on controling app start to work
Collaborator
|
BTW: nice find |
Tools that depend on controlling app startup (relaunch for clean state, refreshing native-devtools injection) need restart-app to be immediately callable rather than routed through a search round-trip.
Member
Author
|
Deferring till |
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
2 participants
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.
Summary
The Model Context Protocol spec lets a server attach optional
_metahints to each entry intools/list. Anthropic clients look for two keys that let a server express an opinion about how its tools should be presented:_meta["anthropic/alwaysLoad"]— a request to keep this tool's full schema visible on every turn rather than load it on demand._meta["anthropic/searchHint"]— a short phrase that helps the client surface the tool when a user request matches it, without needing the full description loaded into context.This PR threads both hints end-to-end through the Argent stack and sets them conservatively on a small core of tools. Clients that don't consume these keys simply ignore them per the MCP spec, so nothing changes for them.
What changed
Plumbing (3 packages)
@argent/registry—ToolDefinitiongains optionalalwaysLoad?: booleanandsearchHint?: string.@argent/tool-server—GET /toolsforwards both fields when set.@swmansion/argent(mcp) — newsrc/tool-mapping.tsmodule maps aToolMetaentry into the MCPtools/listshape, emitting_metaonly when at least one hint is present so clients that don't use it see byte-identical responses.Curation — only the eight tools the model reaches for on practically every turn opt in:
describedebugger-component-treescreenshotgesture-tapgesture-swipelaunch-apprestart-apprun-sequenceEverything else — profiler, flows, native-devtools, metro-debugger, and the rest of the long tail — is left untouched. Argent exposes around 125 tools today; keeping the always-on set small is deliberate, so the hints stay a light nudge rather than a blanket override.
Tests
packages/tool-server/test/http-tools-meta.test.ts— verifiesGET /toolspasses both hints through (and omits them for plain tools).packages/mcp/test/tool-mapping.test.ts— 7 cases coveringalwaysLoadtrue / false / missing,searchHintset / empty-string / missing, and that_metais omitted entirely when neither hint applies.Test plan
npm run buildat workspace root — clean tsc build.npm test -w @argent/registry -w @argent/tool-server -w @swmansion/argent— 634 passing (includes the 8 new cases).prettier --checkon all touched files — clean.Notes
alwaysLoad: falsebehaves identically toundefined(the hint is only forwarded when truthy). Empty-stringsearchHintis silently dropped.searchHintvalues on the long-tail tools (profiler, flows) so search ranking improves even without expanding the always-on set. Left out here to keep scope tight.