Simplify Maka tool discovery: direct baseline + turn-scoped tool_search

[Astro-Han]

Context

Maka currently advertises a large live tool surface and controls it through several overlapping mechanisms: economy mode, named load_tools groups, MAKA_DISABLE_DEFERRED_TOOLS, historical ledger aliases, and exact hosted-execution tool ceilings. This makes the model-facing contract difficult to explain and leaves more than one source of truth for tool identity and availability.

Issue #1382 proposed a provider-native-first Tool Search design. The implementation audit suggests a simpler provider-independent contract that works across every model backend and does not persist model-specific discovery state.

Proposed direction

1. Keep a small direct baseline of frequently useful tools: Bash, Read, ArchiveRead, Write, Edit, Glob, Grep, WebFetch, AskUserQuestion, and StopBackgroundTask.
2. Add one Maka-owned, model-facing tool_search tool. A successful search selects bounded matching tools and makes their schemas available on the next model step.
3. Make activation monotonic within the current turn only. Clear discovered tools at turn completion; do not replay discovery across turns and do not add unload semantics.
4. Keep execution-time availability checks as the final guard.
5. Defer other available tools by default, including low-frequency tools such as WriteStdin. Context-required tools may still be injected directly when the corresponding runtime state requires them.
6. Retire economy/full mode, MAKA_DISABLE_DEFERRED_TOOLS, named load_tools groups, and historical model-facing alias recovery once tool_search covers their use cases.
7. Treat executable tool bindings as the authority. Search metadata should be derived from those bindings rather than becoming a second identity catalog.
8. Preserve exact hosted-execution ceilings: when callers provide boundTools or a hosted tool profile, discovery must not escape that ceiling.

Skill/SkillSearch are intentionally excluded pending a separate discussion about skill discovery and host injection. Goal tools are also discussed separately because their public shape can be simplified before deciding how they are exposed.

Questions to settle

• What bounded search result format and result cap give models enough information without reintroducing a catalog dump?
• Should search index only names/descriptions, or also compact parameter metadata and aliases?
• Which runtime states require a deferred tool to become direct automatically for that turn?
• What migration sequence lets us remove the old mechanisms without temporarily making required tools unreachable?

If this direction holds, #1382 can track the implementation but should be updated away from its provider-native-first and cross-turn persistence assumptions. Follow-up implementation issues should be split by independently revertible intent rather than by internal file.

AI assistance disclosure: Maka helped audit the current implementation and draft this proposal. I reviewed the scope and proposed direction.

[likun666661]

I think the core contract needs one more separation: a successful search should not immediately make every matched tool schema visible.

The model needs a lightweight way to understand the available tool space before searching, and it should get another opportunity to confirm the candidates before Maka sends full schemas. A simple flow is:

grouped tool-name index
  -> tool_search
  -> name + summary candidates
  -> load_tools
  -> full schema visible on the next provider step

The states are distinct:

• Bound: the Runtime has an executable binding. This is the capability ceiling.
• Discoverable: the tool appears in a lightweight index, grouped with tool names only.
• Activated: tool_search returned the tool as a candidate with compact metadata such as name and summary. It is still not callable.
• Loaded: the model explicitly selected the candidate through load_tools, and the Runtime validated it against both the activated candidates and current bindings.
• Visible: the complete callable definition is actually serialized into a provider request. Only this state allows the model to call the tool.

For provider step n, let B be the current bindings, A the search candidates, and L the explicitly loaded tools:

tool_search(group, query):
  A <- boundedSearch(groupIndex intersect B)

load_tools(names):
  require names subset-of A intersect B
  L <- L union names

next provider step:
  V <- (Direct union L) intersect B

Neither search nor load changes B. Also, a load_tools call cannot rewrite the visibility snapshot of the provider step in which it executes; the selected schemas become visible on the following step.

This addresses two practical problems:

1. Without a pre-search inventory, the model has to probe tool_search repeatedly without knowing what kinds of tools exist.
2. If search directly exposes every match, a broad query can inject many full schemas before the model has selected the tool it actually wants.

The initial discovery surface can stay small: expose only group -> tool names. Search then returns bounded name + summary candidates, and load_tools is the explicit confirmation boundary before full schema exposure.

Under this model, item 6 can still retire economy/full mode, MAKA_DISABLE_DEFERRED_TOOLS, historical aliases, and the current load-by-predefined-group semantics. However, groups and load_tools themselves should remain with narrower responsibilities:

• groups organize the lightweight discovery index;
• tool_search retrieves candidate details;
• load_tools confirms exact tools;
• the next provider request establishes visibility.

Search indexes and matching results may be cached, provided cached candidates are revalidated against the current bindings. Provider or prompt caching is a downstream transport optimization and should not be part of the lazy-loading contract.

The tradeoff is that the initial group/name index still grows with the number of bound tools, but it is much smaller than publishing every description and input schema, while avoiding blind trial-and-error discovery.

AI assistance disclosure: Maka helped analyze the state transitions and draft this comment; I reviewed the conclusion and posted it.

[Astro-Han]

Thanks. I agree that separating candidate discovery from full-schema visibility is a coherent design. I am not convinced that the extra confirmation step belongs in the first slice.

The product goal here is to reduce tool tax. tool_search, load_tools, tool_describe, and tool_call are all model-facing protocol surface. They need descriptions, schemas, prompt space, state handling, and additional provider round trips. I would avoid turning an internal distinction such as Activated versus Loaded into another mandatory model interaction unless the current traces show that it solves a real problem.

I checked a local Maka Dev runtime snapshot from Aug 7 to Aug 24: 63 sessions, 23,450 messages, and 8,710 tool invocations. load_tools was called 18 times and all 18 calls succeeded. I found no deferred-not-loaded failures, no repeated discovery, and no attempt to call a hidden tool before loading it. The only unavailable-tool event was a misspelled Archivement. The five browser failures happened after the correct browser group had been loaded and were caused by the browser surface not being visible. This is not a discovery benchmark, but it does not show the failure that an additional confirmation step is intended to fix.

The current deferred catalog is four groups and 15 tools: Rive, Browser, Computer Use, and Agent. That is large enough for group loading to become coarse, but not yet evidence that Maka needs a three-stage discovery protocol.

The comparison with other agents is mixed. Codex uses a single tool_search seam. Pi changes the active tool set and exposes new tools on the next request. OpenCode uses one search() surface that returns callable signatures. oh-my-pi keeps a canonical tool registry and uses either an active tool set, an optional read/write xd:// transport, or a single eval CodeMode entry point.

There are also valid multi-stage designs. Hermes uses tool_search, tool_describe, and tool_call; Kimi Code uses select_tools followed by schema injection; Grok uses search_tool and use_tool. Those designs make sense for larger or more dynamic MCP catalogs, but they are not evidence that Maka should adopt the same number of model-facing steps.

Kimi Code is also not the architecture I would use as a reference for Maka. In our Terminal-Bench 2.1 comparison, Maka scored 62/89 versus Kimi Code at 53/89. Among tasks that finished before the deadline, the rates were 95.1% versus 85.7%. The report also documents important harness differences, so I would not attribute the whole gap to select_tools. Still, the result supports keeping Maka’s tool surface and runtime policy narrower rather than copying Kimi’s schema-injection path. Comparison report

For the first slice, I would use one Maka-owned discovery seam:

direct baseline + tool_search
  -> bounded matches with schema
  -> next provider step exposes the selected tools
  -> model calls the real tool directly

tool_search should search only the current boundTools catalog and activate a bounded set for the current turn. The Runtime should remain the authority for the binding ceiling, execute-time checks, and next-step projection. I would keep historical load_tools calls readable for replay and compatibility, but I would not make the model call load_tools after tool_search.

For providers without native deferred search, the Runtime can project the selected schemas into the next request. For providers that support native search later, that can become an optimization behind the same contract. I would not add tool_describe, tool_call, or a separate candidate-confirmation state in the first implementation.

I would measure result count, schema bytes, time to the first successful tool call, extra round trips, repeated searches, and invalid selections. If those measurements show that direct search-to-activation exposes too many schemas or causes frequent wrong selections, an explicit confirmation boundary can be added later.

AI assistance disclosure: Codex helped me inspect the Maka runtime data and related agent implementations and draft this comment; I reviewed and approved the final position.

中文

谢谢。我同意把候选发现和完整 schema 暴露分开在技术上是合理的，但我不认为额外的确认步骤应该放进第一阶段。

这里的产品目标是减少工具税。tool_search、load_tools、tool_describe 和 tool_call 都是模型可见的协议面，都需要描述、schema、提示词空间、状态处理和额外的 provider 往返。除非当前轨迹已经显示 Activated 和 Loaded 的区分能解决真实问题，否则我不希望把这个内部状态区别变成模型必须执行的额外交互。

我检查了 8 月 7 日到 8 月 24 日的本地 Maka Dev 运行快照：63 个 session、23,450 条消息和 8,710 次工具调用。load_tools 调用了 18 次，18 次全部成功。没有发现 deferred-not-loaded 失败、重复发现，或者工具尚未加载就被调用的情况。唯一一次 unavailable-tool 是模型把工具名写成了 Archivement。5 次浏览器失败发生在正确加载 Browser group 之后，原因是浏览器界面当时不可见。这不是一个完整的 discovery benchmark，但当前数据也没有显示额外确认步骤要解决的问题。

当前 deferred catalog 是 4 组、15 个工具：Rive、Browser、Computer Use 和 Agent。这个规模已经足以让 group loading 开始变粗，但还不足以证明 Maka 需要三阶段 discovery 协议。

其他 Agent 的做法并不统一。Codex 使用单一的 tool_search 入口。Pi 修改 active tool set，并在下一次请求暴露新工具。OpenCode 使用一个返回 callable signature 的 search()。oh-my-pi 保持一个 canonical tool registry，可以使用 active tool set、可选的 read/write xd:// 传输，或者单一的 eval CodeMode 入口。

当然也有合理的多阶段设计。Hermes 使用 tool_search、tool_describe 和 tool_call；Kimi Code 使用 select_tools，之后注入 schema；Grok 使用 search_tool 和 use_tool。这些设计适合更大、更动态的 MCP catalog，但不能说明 Maka 也应该采用同样多的模型交互步骤。

Kimi Code 也不是我会拿来作为 Maka 架构参考的实现。在我们的 Terminal-Bench 2.1 对比中，Maka 是 62/89，Kimi Code 是 53/89；在 deadline 前完成的任务中，两者分别是 95.1% 和 85.7%。报告也记录了重要的 harness 差异，所以我不会把全部差距归因于 select_tools。但这个结果仍然支持 Maka 保持更窄的工具面和更简单的运行时策略，而不是复制 Kimi 的 schema 注入路径。

第一阶段我会采用一个 Maka 自己拥有的 discovery 入口：

direct baseline + tool_search
  -> 有上限的匹配结果和 schema
  -> 下一 provider step 暴露选中的工具
  -> 模型直接调用真实工具

tool_search 只搜索当前 boundTools catalog，并在当前 turn 激活有上限的一组工具。Runtime 仍然负责 binding ceiling、执行时检查和下一 step 的投影。我会保留历史 load_tools 调用的读取能力，用于 replay 和兼容，但不会要求模型在 tool_search 之后再调用 load_tools。

对不支持原生 deferred search 的 provider，Runtime 可以把选中的 schema 投影到下一次请求。以后支持原生 search 的 provider 可以在同一契约后面做优化。第一阶段我不会增加 tool_describe、tool_call 或单独的候选确认状态。

我会测量搜索结果数量、schema 字节数、第一次成功工具调用的延迟、额外往返次数、重复搜索和非法选择。如果数据证明直接 search-to-activation 暴露了过多 schema，或者经常选错，再增加显式确认边界。

AI assistance disclosure：Codex 协助我检查 Maka 运行数据和相关 Agent 实现，并起草了这条评论；最终立场由我审阅并确认。

[Astro-Han]

Thanks. I think our disagreement is now quite small. We agree on the inventory source (bound tool names in the initial system context), on boundTools as the ceiling, on turn-scoped discovery, and on model-owned schema visibility. What remains is which surface fits the current catalog.

Your coupling concern is real in one specific place: any code that later re-derives "was this call an activation?" from the input string — next-step projection, replay, telemetry. Classification would depend on the catalog state at re-derivation time, and names do change: tool-availability.ts still carries load_tool and connect_tool_source as seed aliases from this connector's own two renames.

I would close that gap by making the effect an explicit recorded fact rather than something re-derived:

tool_search(query) result:
  activated: ["browser_snapshot"]   // exact-name hit, validated against boundTools
  activated: []                     // retrieval-only; candidates listed separately

The next-step projection, telemetry, and any replay read activated from the result record instead of re-classifying the input. Retrieval and visibility mutation then stay distinguishable per call record; caching and retry can branch on the receipt instead of string equality. Since discovery is turn-scoped and never replayed across turns, the historical-ledger half of the concern does not arise; the receipt covers the same-turn half.

With that in place, the remaining difference between one tool and two is one callable definition of model-facing surface, at equal provider step counts (parallel tool calls also cover the multi-tool case). For a catalog of four groups and fifteen tools, I would take the smaller surface for the first slice.

Two commitments so this stays falsifiable:

1. The receipt lands on both sides in the same slice — written into the tool_search result and read by the next-step projection — not as a follow-up.
2. We measure exactly what you listed: schemas exposed but never called, bytes of exposed-but-unused schemas, top-k recall of the tool eventually called, revised searches after seeing candidates, and tasks where the right tool falls outside the activation cap. If those numbers show exposure control is not enough, adding an explicit confirmation step is the right next move — and we would be adding it with data.

One boundary I want on record: if the catalog later becomes large or dynamic (for example externally attached tool sets growing to hundreds of entries), the balance shifts and your explicit confirmation layer becomes the right design. At today's scale it is not yet needed.

AI assistance disclosure: Claude helped verify the runtime code paths and draft this comment; I reviewed and approved the final position.

简体中文

谢谢。我认为我们的分歧已经很小：inventory 来源（初始 system context 放全部绑定工具名）、boundTools 天花板、turn 内有效、schema 可见性由模型决定，这些都已一致。剩下的只是当前目录规模下选哪种接口。

你说的耦合在一个具体位置是真实的：任何事后从输入字符串重推导"这次调用是不是激活"的代码——下一步投影、重放、遥测——其分类会依赖重推导时的目录状态，而工具名确实会变（tool-availability.ts 里至今保留着这个连接器自己两次改名留下的 load_tool、connect_tool_source 别名）。

我的解法是把效果变成显式记录的事实：tool_search 的 result 里写明 activated: [...]（纯检索时为空）。投影、遥测、重放读这条收据，不再重新分类输入。检索和可见性变更在每条调用记录里仍然可区分。发现状态不跨 turn 重放，账本那一半问题不存在；收据覆盖同 turn 这一半。

在此之上，单工具和双工具的实际差别只剩一份模型可见的工具定义，回合数相同（多工具场景可并行调用）。四组十五个工具的规模下，第一片我选更小的接口面。

两个承诺：收据的写和读在同一片落地；把你列的那组指标测上。如果数据表明暴露控制不够，再加显式确认步——那时是带着数字加的。

一个边界先说清：如果将来目录变大或高度动态（例如外接工具集合达到数百个），天平就会翻向你的显式确认层。今天还不到那一步。

AI assistance disclosure：Claude 协助核对 runtime 代码路径并起草本评论；最终立场由我审阅并确认。

[likun666661]

Thanks. I agree that an explicit effect receipt is better than re-deriving an activation from historical input. However, the receipt fixes observation of the coupling after the fact; it does not remove the coupling itself.

I want to ask the inverse question directly:

What concrete negative consequence do we get if the first slice keeps retrieval and visibility mutation separate from the beginning?

The uncoupled contract is small:

tool_search({ query })
  -> { candidates: [{ name, summary }] }       // read-only

load_tools({ names })
  -> { loaded: [name] }                        // explicit mutation receipt

It has two paths:

exact tool already known from initial catalog:
  load_tools(name)
  -> next step visible

tool meaning is unclear:
  tool_search(query)
  -> candidates
  load_tools(names)
  -> next step visible

The proposed overloaded contract has the same provider step counts:

exact tool already known:
  tool_search(exactName)
  -> next step visible

tool meaning is unclear:
  tool_search(query)
  -> candidates
  tool_search(exactName)
  -> next step visible

So the separate contract does not add a provider round trip. In the ambiguous case both designs require two model calls before schema visibility. In the exact-name case both require one. The only additional model-facing cost is one small callable definition for load_tools.

Against that small cost, separation gives us:

• explicit read versus write semantics at call time;
• a naturally batchable load_tools({ names: [...] });
• one mutation receipt with atomic validation and clear partial-failure policy;
• search results that can be indexed and cached without effect semantics;
• availability events that do not depend on the search result contract;
• retry, replay, telemetry, and tests that follow the operation name rather than a branch inside it;
• a search layer that does not depend on turn-scoped visibility projection.

Parallel exact-name tool_search calls are not equivalent to a batch load. They create multiple calls and results, require per-call failure handling, and still need the Runtime to combine their effects. A single load_tools call represents the model decision directly.

The proposed receipt:

tool_search result:
  activated: [...]

also demonstrates that the supposedly removed state and transition still exist. Something must write the activation, persist it across the step boundary, and project it into the next request. The receipt is useful, but the natural producer of that receipt is the explicit mutating operation:

load_tools result:
  loaded: [...]

Putting the receipt on tool_search instead makes the search result schema part of the availability state machine. Projection now consumes a retrieval result because retrieval sometimes acts as a command. That is stronger code-scope coupling, not weaker coupling.

I also do not think callable-count alone is a good measure of contract entropy. Compare:

tool_search always searches
load_tools always loads

with:

tool_search searches unless query equals a canonical name,
in which case it mutates next-step visibility

The first contract has two names but one invariant per tool. The second has one name but effect-dependent semantics that must be explained in its description, implementation, tests, receipts, telemetry, and cache behavior. Fewer callable definitions do not necessarily mean a simpler system.

The current scale argument also does not match the target surface in this discussion. Four groups and fifteen tools describe the current deferred catalog. The proposal says that other available tools become deferred by default and explicitly includes runtime/client capabilities. The target search space is therefore not permanently bounded by the current four groups, and dynamic bound tools are already part of the architecture rather than a hypothetical future of hundreds of external tools.

More importantly, code-scope boundaries should not change when the catalog crosses an arbitrary size threshold. If explicit retrieval and mutation boundaries are the correct design at large scale, and they have no additional provider-round-trip cost at current scale, coupling them now only creates a later migration that we already know how to avoid.

The current implementation already has load_tools and a tool-availability transition. A thorough refactor can simplify it instead of deleting the boundary:

• remove economy/full mode;
• remove environment switching;
• replace predefined-group loading with canonical exact-name loading;
• remove historical aliases from the new model-facing contract while retaining only the compatibility reader that is actually required;
• add a pure tool_search over metadata derived from current bindings;
• keep request projection owned by the availability runtime.

That is a complete simplification of the old mechanism. It does not preserve legacy group semantics, and it does not add tool_describe or tool_call. It keeps only the boundary that already corresponds to a real state mutation.

The measurements you committed to are useful, but they compare exposure quality and retrieval quality. They do not identify a user-visible benefit from making search itself stateful. Before accepting the coupling for the first slice, I think we need a concrete answer to this:

Other than saving the small load_tools definition, what behavior, provider round trip, or implementation responsibility becomes simpler when exact-name search mutates visibility instead of calling an explicit existing loader?

If there is no additional benefit, I would rather complete the refactor with clean boundaries now than deliberately create a mixed-scope seam and plan to split it only after the catalog grows.

AI assistance disclosure: Maka helped analyze the architectural tradeoffs and draft this reply; I reviewed and approved the final position.

[Astro-Han]

Thanks — your last two replies changed my mind, so let me say the update plainly.

I'm withdrawing the exact-name overload. You were right: a tool whose input string conditionally means "read" or "write", depending on catalog state at classification time, is the worst version of this seam. The receipt recorded that coupling; it didn't remove it.

But the fix I now prefer removes the condition, not the single tool:

tool_search(query, limit?)
  -> top-k matches, bounded by result count and total schema bytes
  -> matched schemas visible on the next step, turn-scoped

Search always activates what it returns. With no exact-name branch, the hazards on your list don't arise: every call record is uniformly an activation, the result is its own receipt, projection/telemetry/replay read it unconditionally, and a rename can never reclassify a historical call.

Stating the semantics accurately, in your words: ranker-selected schemas become visible; the model selects execution. You called this a coherent first-slice experiment — I now think it's the honest version of the small surface, and I'd rather run that experiment than blur read/write inside one contract.

It also answers your inverse question concretely: keeping retrieval and loading separate costs one extra provider round trip in every ambiguous discovery (search → candidates → load, versus search → schemas). That round trip is exactly the tax this proposal is trying to cut.

On precedent, I checked Codex in source rather than by reputation: codex-rs/core/src/tools/handlers/tool_search_spec.rs and tool_search.rs — one tool, required query plus optional limit with a default, BM25 over deferred tool metadata, top-k full definitions exposed for the next call, no load step, no confirmation, dynamic MCP/connector sources included. That's an existence proof at real plugin scale, not a benchmark — which is why the measurement commitment stands unchanged: your metric list is the judge, and if exposed-but-unused bytes or top-k recall come back bad, an explicit confirmation step is the data-backed next move. One correction to my earlier boundary: what triggers that flip is the measurements, not catalog size — Codex suggests size alone doesn't decide it.

AI assistance disclosure: Claude helped verify the Codex implementation and draft this comment; I reviewed and approved the final position.

简体中文

谢谢——你最近两条回复改变了我的想法，直接说结论。

我撤回精确名重载方案。 你是对的：一个工具的输入字符串要依赖分类时刻的目录状态才能确定是"读"还是"写"，这是这条接缝最差的版本。收据只是把耦合记录在案，没有消除它。

但我现在倾向的修法是删掉条件分支，而不是删掉单工具：

tool_search(query, limit?)
  -> top-k 匹配，受结果数和 schema 总字节双上限约束
  -> 匹配的 schema 下一步可见，turn 内有效

搜索永远激活它返回的东西。没有精确名分支，你列的风险就不成立：每条调用记录都统一是一次激活，result 本身就是收据，投影/遥测/重放无条件读取它，改名也不可能让历史调用换类别。

按你的措辞诚实标注语义：ranker 选中的 schema 变为可见；模型选择执行。 你说过这是一个自洽的第一阶段实验——我现在认为这是小接口面的诚实版本，我宁可跑这个实验，也不想在一个契约里混合读写。

这也具体回答了你的反问：检索与加载分离的代价，是每次模糊发现多付一个 provider 往返（search → candidates → load，对比 search → schemas）。这个往返正是这个提案要削减的税。

关于先例，我去源码里核了 Codex，而不是凭印象：codex-rs/core/src/tools/handlers/tool_search_spec.rs 与 tool_search.rs——单工具，必填 query 加带默认值的可选 limit，对 deferred 工具元数据做 BM25，top-k 完整定义在下一次调用暴露，无 load 步骤、无确认步，数据源包含动态 MCP/connector。这是真实插件规模下的存在性证据，不是对比实验——所以测量承诺原样保留：你列的指标就是裁判，如果"暴露未使用的字节"或 top-k 命中率数据不好，加显式确认步就是带着数据的下一步。修正我之前说的边界：触发翻转的是测量结果，不是目录规模——Codex 说明规模本身不决定这件事。

AI assistance disclosure：Claude 协助核对 Codex 实现并起草本评论；最终立场由我审阅并确认。

[likun666661]

Thanks. This version is much clearer. I agree with two corrections:

1. The exact-name overload should be withdrawn.
2. A uniform search-and-activate contract really does save one provider round trip in the ambiguous-discovery path.

The Codex implementation is also a valid existence proof. The source describes the operation honestly: BM25 search over deferred metadata, query plus optional limit, returning loadable tool definitions for the next model call, including dynamic sources.

So the remaining tradeoff should be stated completely:

Dimension	Search activates top-k	Search then explicit load
Canonical name already known	one call	one call
Meaning is ambiguous	one control call	two control calls
Schema exposure	every returned top-k schema	only model-confirmed schemas
Visibility decision	ranker + cap	model after name + summary
Model-facing surface	one compound tool	two single-purpose tools
Multi-tool selection	query/top-k driven	explicit canonical-name batch
Code boundary	retrieval produces availability mutation	retrieval and mutation remain separate

I accept the latency entry. I still reach the opposite first-slice conclusion for four reasons.

1. The extra round trip is not paid on every deferred-tool use

All bound canonical names are already in the initial runtime catalog. When the intended tool is clear from its name, the model can directly call:

load_tools({ names: ["browser_snapshot"] })

That is one control call, exactly like tool_search("browser_snapshot") in the compound design. The extra round trip appears only when names are insufficient and the model actually needs search summaries to disambiguate.

We do not yet know how frequently that ambiguous path occurs. Existing traces have no tool_search, so they cannot establish that this latency is common enough to justify coupling the scopes.

2. The saved round trip is exchanged for context bytes and ranker authority

The compound path is faster because it commits before the model sees the result:

query
  -> top-k ranker decision
  -> all top-k schemas visible

The separated path delays commitment:

query
  -> cheap name + summary candidates
  -> model decision
  -> selected schemas visible

A cap does not remove this tradeoff. A tight cap reduces bytes but risks excluding the correct tool. A loose cap improves recall but exposes more unused schemas. The model chooses limit before it sees the matches, so it cannot know the correct point on that curve for a particular query.

The cost comparison is therefore not simply one round trip versus nothing. It is:

one additional inference round trip versus top-k full-schema bytes plus ranker-owned visibility.

That needs measurement on both sides before choosing a permanent contract.

3. The separated design is the more informative first experiment

If we start with pure search followed by explicit load, every ambiguous discovery gives us:

• the ranker top-k;
• the summaries shown to the model;
• the exact names the model subsequently loads;
• the extra latency;
• the schemas and bytes avoided by confirmation.

From that trace we can compute ranker-to-model agreement and estimate the counterfactual auto-activation policy. If the model almost always loads all returned candidates and the extra round trip is material, merging the operations later has direct evidence behind it.

If we start with automatic activation, we can measure unused exposed schemas, but we cannot observe the missing counterfactual: which tools the model would have approved after seeing only cheap summaries. The confirmation step does not exist, so the most important comparison signal is unavailable.

Starting separated therefore produces the data needed to decide whether merging is safe. Starting merged produces only half of the comparison and requires adding the second path later to measure the other half.

4. The current Runtime already has the mutation boundary

This is not a choice between adding a new complex confirmation subsystem and keeping an existing simple search. Maka already has load_tools, turn-scoped availability state, step-start gating, and next-step projection.

A thorough refactor can make those responsibilities smaller and clearer:

tool_search
  pure search over metadata derived from current bound tools
  returns bounded name + summary candidates

load_tools
  accepts canonical exact names
  validates against current boundTools
  records one explicit loaded receipt
  affects next-step projection

At the same time, we can remove the actual legacy complexity:

• economy/full mode;
• MAKA_DISABLE_DEFERRED_TOOLS;
• predefined groups as loading units;
• historical aliases from the new model-facing contract;
• cross-turn discovery replay.

That is not preserving the old design. It is completing the refactor around the real read/write boundary that remains necessary in either implementation.

The uniform compound contract is much better than the withdrawn exact-name overload, but it still makes retrieval the command that changes availability. Its result must be consumed by projection as an activation receipt. The implementation can organize internal functions cleanly, but the public semantic boundary remains combined.

Codex proves that this combined contract can work at plugin scale. It does not prove that the extra round trip costs more than the schema bytes and selection precision it removes for Maka. That is exactly the local comparison we still lack.

My preferred first slice is therefore:

initial grouped canonical names
  -> direct load when the name is sufficient
  -> pure search when summaries are needed
  -> explicit batch load
  -> next-step visibility

This keeps the fast path at one call, keeps ambiguous selection model-owned, reuses the existing state boundary, and generates the traces needed to evaluate auto-activation honestly.

The key decision question is now measurable:

Among searches where names alone were insufficient, how often does the model load every top-k candidate, how many schema bytes does confirmation avoid, and is that saving worth one extra provider round trip?

Until we have that comparison, I do not think saving the round trip is enough reason to make search and availability mutation the same public operation from the start.

AI assistance disclosure: Maka helped verify the Codex source, analyze the complete tradeoff, and draft this reply; I reviewed and approved the final position.

[Astro-Han]

This has been a useful discussion. I think we have narrowed the disagreement to one question: does turn-scoped schema visibility need its own model-facing command from the start?

I agree that separating retrieval from mutation is a clean design. My concern is whether that boundary pays for itself today.

The Agile Manifesto principles call simplicity “the art of maximizing the amount of work not done.” Martin Fowler’s explanation of YAGNI makes the related point that a presumed future capability should not be built before it is needed. RFC 3439 applies the same idea to protocol architecture: complexity impedes scaling and brings ongoing operational cost.

These are defaults, not absolute rules. A separate command is justified when it protects an important boundary. Here, however, schema visibility is bounded, turn-scoped, and reversible. It does not authorize execution. The model must still call the tool, and the Runtime still enforces the step-start guard.

A has one stable rule:

tool_search always searches and activates its bounded results

B adds another model-facing tool, another public transition, and another provider round trip when the tool name is unclear. Those costs may be worthwhile if ranker-selected schemas cause poor recall, excessive context use, or wrong-tool execution. We do not have that evidence yet.

The existing load_tools implementation does not make B free. It currently loads groups, derives activation from call input, and restores activation across turns. Both proposals require replacing those semantics.

I therefore prefer to start with the smallest coherent and observable contract:

tool_search(query, limit?)
  -> bounded top-k full definitions
  -> visible on the next provider step
  -> cleared when the turn completes

We can record ranked results, activated schemas, subsequent calls, unused schema bytes, recall, and latency. The separated design can also be compared in @maka/eval. If the data shows that explicit confirmation protects something material, adding load_tools will have a concrete reason and a measurable goal.

That is how I would apply KISS and YAGNI here: not as a rule that fewer tools are always better, but as a burden of proof for every additional permanent concept.

AI assistance disclosure: Codex helped analyze the tradeoff and draft this comment; I reviewed and approved the final position.

中文

这是一次很有价值的讨论。我认为现在的分歧已经收敛到一个问题：turn-scoped 的 schema visibility 是否从第一阶段开始就需要一个独立的模型命令？

我同意分离 retrieval 和 mutation 是一种干净的设计。我的疑问是，这个边界在今天是否已经值得它带来的成本。

敏捷宣言原则把简洁定义为“尽最大可能减少不必要工作的艺术”。Martin Fowler 对 YAGNI 的解释也指出，不应因为推测未来需要某项能力，就提前实现它。RFC 3439则把同一个原则用于协议架构：复杂度会阻碍系统扩展，并持续产生运维成本。

这些是默认原则，不是绝对规则。如果一个独立命令保护了重要边界，它当然值得存在。但这里的 schema visibility 有上限、只在当前 turn 有效，而且可以恢复。它不授权执行。模型仍然必须调用真实工具，Runtime 也仍然执行 step-start guard。

A 只有一条稳定规则：

tool_search 总是搜索并激活数量受限的返回结果

B 增加了一个模型可见工具、一个公开状态转换，并在工具名称不明确时增加一次 provider 往返。如果 ranker 选择的 schema 确实造成 recall 不足、上下文浪费或错误工具执行，这些成本可能值得。但我们目前还没有这样的证据。

现有 load_tools 也不会让 B 免费落地。它目前按 group 加载、从调用输入推导激活，并跨 turn 恢复状态。两个方案都需要替换这些语义。

因此我倾向先采用最小、完整且可观测的契约：

tool_search(query, limit?)
  -> 返回数量受限的 top-k 完整定义
  -> 下一 provider step 可见
  -> turn 完成后清除

我们可以记录 ranked results、activated schemas、后续真实调用、未使用 schema 字节、recall 和 latency。分离方案也可以在 @maka/eval 中对比。如果数据证明显式确认保护了重要东西，再增加 load_tools 就会有具体理由和可测目标。

这就是我在这里对 KISS 和 YAGNI 的理解：不是工具越少永远越好，而是每增加一个永久概念，都应先证明它的必要性。

AI assistance disclosure：Codex 协助分析取舍并起草了这条评论；最终立场由我审阅并确认。