morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[GH-ISSUE #6870] Advertise a stable family for each tool in `tools/list` metadata, and document that DeepSeek Harness does not lazy-load #4208

New issue

Open

opened 2026-10-31 00:47:43 +00:00 by bsakaguchi · 9 comments

bsakaguchi commented

2026-10-31 00:47:43 +00:00

Owner

Originally created by @kirkchinese on GitHub (Oct 23, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/6870

Before submitting

I searched the open and closed issues and pull requests for a related proposal.
I understand the contribution scope must be reviewed before integration; open questions are welcome here.
This request does not include credentials, private samples, or sensitive target data.

Area

MCP or agent integration

Current limitation

DeepSeek Harness, which rea setup --client dsh supports, does not lazy-load MCP tools: dsh-mcp-client registers all of them and the Harness sends every input schema with every request. With REA 6.7.0 on DeepSeek Harness 0.2.0-rc.2, the first request of a headless task reported 249,653 input tokens. Claude Code routed to DeepSeek turns tool search off for the same reason (#2019 and the client-configuration guide). So the premise in #1669 does not hold for these hosts.

We built a Harness plugin (dsh-capability-catalog) that indexes MCP servers lazily: a compact family index in the system prompt plus search/describe/call tools. REA behind it starts on demand and the same task's first request reported about 9.2k input tokens. The plugin already reads a family from tool _meta when present; without it, it has to guess from tool names; for REA we maintain a hand-written mapping of all 207 tools to 14 families, which goes stale whenever tools are added or renamed.

Use cases

Lazy-indexing clients and gateways (our Harness plugin, MCP gateways, search_tools-style layers) group REA's tools for a compact index and family browsing.
Hosts without tool search can still show the model which capability areas exist without sending 668 KB of schemas.

Desired outcome and success criteria

Each tool in tools/list carries a stable family in _meta, for example "_meta": {"io.github.morluto/rea": {"family": "javascript-electron"}}, taken from the existing contract families in src/contracts.
Optionally a one-line family description, either in server instructions or in a separate _meta field on the first tool of each family.
No tool is hidden or renamed; tools/list stays the complete canonical inventory and input schemas are unchanged.
The DeepSeek Harness section of docs/client-configuration.md notes the measured per-request cost when REA is registered directly.

Expected interaction with targets

None. This only changes discovery metadata.

Alternatives considered

Operator tool selection (#1669): closed, and hides tools.
Client-side name heuristics: our generic heuristic leaves 67 of 207 REA tools in a catch-all group.

Originally created by @kirkchinese on GitHub (Oct 23, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/6870 ### Before submitting - [x] I searched the open and closed issues and pull requests for a related proposal. - [x] I understand the contribution scope must be reviewed before integration; open questions are welcome here. - [x] This request does not include credentials, private samples, or sensitive target data. ### Area MCP or agent integration ### Current limitation DeepSeek Harness, which `rea setup --client dsh` supports, does not lazy-load MCP tools: `dsh-mcp-client` registers all of them and the Harness sends every input schema with every request. With REA 6.7.0 on DeepSeek Harness 0.2.0-rc.2, the first request of a headless task reported 249,653 input tokens. Claude Code routed to DeepSeek turns tool search off for the same reason (#2019 and the client-configuration guide). So the premise in #1669 does not hold for these hosts. We built a Harness plugin ([dsh-capability-catalog](https://github.com/kirkchinese/dsh-capability-catalog)) that indexes MCP servers lazily: a compact family index in the system prompt plus search/describe/call tools. REA behind it starts on demand and the same task's first request reported about 9.2k input tokens. The plugin already reads a `family` from tool `_meta` when present; without it, it has to guess from tool names; for REA we maintain a [hand-written mapping](https://github.com/kirkchinese/dsh-capability-catalog/blob/main/packages/rea/families.yml) of all 207 tools to 14 families, which goes stale whenever tools are added or renamed. ### Use cases - Lazy-indexing clients and gateways (our Harness plugin, MCP gateways, `search_tools`-style layers) group REA's tools for a compact index and family browsing. - Hosts without tool search can still show the model which capability areas exist without sending 668 KB of schemas. ### Desired outcome and success criteria - Each tool in `tools/list` carries a stable family in `_meta`, for example `"_meta": {"io.github.morluto/rea": {"family": "javascript-electron"}}`, taken from the existing contract families in `src/contracts`. - Optionally a one-line family description, either in server instructions or in a separate `_meta` field on the first tool of each family. - No tool is hidden or renamed; `tools/list` stays the complete canonical inventory and input schemas are unchanged. - The DeepSeek Harness section of `docs/client-configuration.md` notes the measured per-request cost when REA is registered directly. ### Expected interaction with targets None. This only changes discovery metadata. ### Alternatives considered - Operator tool selection (#1669): closed, and hides tools. - Client-side name heuristics: our generic heuristic leaves 67 of 207 REA tools in a catch-all group.

bsakaguchi commented

2026-10-31 00:47:44 +00:00

Author

Owner

@XinwangTao commented on GitHub (Oct 24, 2026):

Strong +1 — the token numbers speak for themselves (249k vs ~9k first request), and a hand-written 207-to-14 mapping is exactly the kind of thing that goes stale. Adding a stable family to each tool's _meta in tools/list is the right fix. Two suggestions: (1) also expose the family list itself as top-level metadata so lazy clients can show capability areas without scanning every tool; (2) define a fallback rule for tools that don't set family yet, and treat family as part of the public API contract so tool renames don't silently break catalog plugins.

@XinwangTao commented on GitHub (Oct 24, 2026): Strong +1 — the token numbers speak for themselves (249k vs ~9k first request), and a hand-written 207-to-14 mapping is exactly the kind of thing that goes stale. Adding a stable family to each tool's _meta in tools/list is the right fix. Two suggestions: (1) also expose the family list itself as top-level metadata so lazy clients can show capability areas without scanning every tool; (2) define a fallback rule for tools that don't set family yet, and treat family as part of the public API contract so tool renames don't silently break catalog plugins.

bsakaguchi commented

2026-10-31 00:47:45 +00:00

Author

Owner

@definitelynotchirag commented on GitHub (Oct 25, 2026):

hey i have opened #7154 for this :)

i saw that REA already knows which family every tool belongs to internally, it just never put that on the wire. The pr adds it to each tool's _meta in tools/list. Its a small change in one spot of the registration path, and nothing is renamed or hidden i have skipped the per-family descriptions for now, can add them if you'd like!

@definitelynotchirag commented on GitHub (Oct 25, 2026): hey i have opened #7154 for this :) i saw that REA already knows which family every tool belongs to internally, it just never put that on the wire. The pr adds it to each tool's _meta in tools/list. Its a small change in one spot of the registration path, and nothing is renamed or hidden i have skipped the per-family descriptions for now, can add them if you'd like!

bsakaguchi commented

2026-10-31 00:47:45 +00:00

Author

Owner

@morluto commented on GitHub (Oct 26, 2026):

Thank you for the client-side measurements and concrete metadata use case. #7228 has since added opt-in tool-family selection, but it does not by itself publish a family on each tool; #7154 remains open for that requested metadata. The new selection family IDs and the adapter surfaces are different vocabularies, so their relationship needs to be settled in that review. This does not claim a new live Harness measurement.

@morluto commented on GitHub (Oct 26, 2026): Thank you for the client-side measurements and concrete metadata use case. #7228 has since added opt-in tool-family selection, but it does not by itself publish a family on each tool; #7154 remains open for that requested metadata. The new selection family IDs and the adapter surfaces are different vocabularies, so their relationship needs to be settled in that review. This does not claim a new live Harness measurement.

bsakaguchi commented

2026-10-31 00:47:45 +00:00

Author

Owner

@XinwangTao commented on GitHub (Oct 27, 2026):

morluto 提到的两个词汇表关系确实需要在 #7154 里定清楚。建议把 tools/list 中每个工具的 family 作为单一事实来源，让 #7228 的 opt-in selection 直接复用同一组 family ID，而不是另起一套 selection 词汇——否则客户端在"选择 family"和"读取工具元数据"时要做两次映射，正好又回到手写 mapping 的老问题。per-family 描述可以在后续迭代补充，不影响 metadata 先行落地。

@XinwangTao commented on GitHub (Oct 27, 2026): morluto 提到的两个词汇表关系确实需要在 #7154 里定清楚。建议把 tools/list 中每个工具的 family 作为单一事实来源，让 #7228 的 opt-in selection 直接复用同一组 family ID，而不是另起一套 selection 词汇——否则客户端在"选择 family"和"读取工具元数据"时要做两次映射，正好又回到手写 mapping 的老问题。per-family 描述可以在后续迭代补充，不影响 metadata 先行落地。

bsakaguchi commented

2026-10-31 00:47:45 +00:00

Author

Owner

@definitelynotchirag commented on GitHub (Oct 30, 2026):

6. Thank you for the client-side measurements and concrete metadata use case. #7228 has since added opt-in tool-family selection, but it does not by itself publish a family on each tool; #7154 remains open for that requested metadata. The new selection family IDs and the adapter surfaces are different vocabularies, so their relationship needs to be settled in that review. This does not claim a new live Harness measurement.

Settled on the PR side: #7154 now advertises the selection family ids from #7228, so the two vocabularies line up

@definitelynotchirag commented on GitHub (Oct 30, 2026): > 6\. Thank you for the client-side measurements and concrete metadata use case. [#7228](https://github.com/morluto/rea/pull/7228) has since added opt-in tool-family selection, but it does not by itself publish a family on each tool; [#7154](https://github.com/morluto/rea/pull/7154) remains open for that requested metadata. The new selection family IDs and the adapter surfaces are different vocabularies, so their relationship needs to be settled in that review. This does not claim a new live Harness measurement. Settled on the PR side: #7154 now advertises the selection family ids from #7228, so the two vocabularies line up

bsakaguchi commented

2026-10-31 00:47:45 +00:00

Author

Owner

@XinwangTao commented on GitHub (Oct 30, 2026):

Nice — aligning the selection family ids with the _meta family resolves the double-mapping issue I raised earlier: clients can now browse and select using a single vocabulary. One remaining suggestion: treat the family field in tools/list _meta as part of the public contract and add a test asserting every tool carries a non-empty family, so future tool additions don't silently drift back to hand-written mappings.

@XinwangTao commented on GitHub (Oct 30, 2026): Nice — aligning the selection family ids with the _meta family resolves the double-mapping issue I raised earlier: clients can now browse and select using a single vocabulary. One remaining suggestion: treat the family field in tools/list _meta as part of the public contract and add a test asserting every tool carries a non-empty family, so future tool additions don't silently drift back to hand-written mappings.

bsakaguchi referenced this issue

2026-10-31 01:12:04 +00:00

[PR #4208] [CLOSED] fix(sqlite): classify path resolution errors as invalid input #6126

bsakaguchi commented

2026-11-03 07:16:59 +00:00

Author

Owner

@kirkchinese commented on GitHub (Nov 3, 2026):

Thanks @morluto and @definitelynotchirag. The vocabulary alignment in #7154 works for us: @kirkchinese/dsh-capability-catalog already reads a string family from namespaced tool _meta, including io.github.morluto/rea, so no client-side mapping change is needed when that lands. #7228 is also compatible with our lazy catalog because the MCP cache key includes the server environment, including REA_MCP_TOOL_FAMILIES.

For clarity on our side: curated rules are pinned to REA 6.7.0 (207 tools). We will prefer the upstream family metadata whenever present and use name-based rules only as a fallback for versions that do not publish it.

@kirkchinese commented on GitHub (Nov 3, 2026): Thanks @morluto and @definitelynotchirag. The vocabulary alignment in #7154 works for us: `@kirkchinese/dsh-capability-catalog` already reads a string `family` from namespaced tool `_meta`, including `io.github.morluto/rea`, so no client-side mapping change is needed when that lands. #7228 is also compatible with our lazy catalog because the MCP cache key includes the server environment, including `REA_MCP_TOOL_FAMILIES`. For clarity on our side: curated rules are pinned to REA 6.7.0 (207 tools). We will prefer the upstream `family` metadata whenever present and use name-based rules only as a fallback for versions that do not publish it.

bsakaguchi commented

2026-11-03 07:16:59 +00:00

Author

Owner

@kirkchinese commented on GitHub (Nov 3, 2026):

Thanks @definitelynotchirag — yes, canonical per-family descriptions would be very welcome on our side, either in this PR or as a small follow-up.

We would treat the family IDs and their English descriptions as the upstream-owned source of truth, while our plugin handles presentation and Chinese localization. That would let us retire more of the hand-maintained mapping and wording over time.

No need to block #7154 on this, though: having every tool advertise a stable family is already the important part for lazy clients.

@kirkchinese commented on GitHub (Nov 3, 2026): Thanks @definitelynotchirag — yes, canonical per-family descriptions would be very welcome on our side, either in this PR or as a small follow-up. We would treat the family IDs and their English descriptions as the upstream-owned source of truth, while our plugin handles presentation and Chinese localization. That would let us retire more of the hand-maintained mapping and wording over time. No need to block #7154 on this, though: having every tool advertise a stable family is already the important part for lazy clients.

bsakaguchi commented

2026-11-04 04:56:16 +00:00

Author

Owner

@XinwangTao commented on GitHub (Nov 4, 2026):

Agreed — treating family IDs and the English descriptions as the upstream-owned source of truth, with plugins handling presentation and localization, is the right split. I'd still suggest adding the contract test to #7154 (assert every tool carries a non-empty family) so future tool additions can't silently drift back to name-based heuristics. Happy to review the PR when it's ready.

@XinwangTao commented on GitHub (Nov 4, 2026): Agreed — treating family IDs and the English descriptions as the upstream-owned source of truth, with plugins handling presentation and localization, is the right split. I'd still suggest adding the contract test to #7154 (assert every tool carries a non-empty family) so future tool additions can't silently drift back to name-based heuristics. Happy to review the PR when it's ready.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#4208

No description provided.

Rows
Columns

[GH-ISSUE #6870] Advertise a stable family for each tool in tools/list metadata, and document that DeepSeek Harness does not lazy-load #4208

Before submitting

Area

Current limitation

Use cases

Desired outcome and success criteria

Expected interaction with targets

Alternatives considered

[GH-ISSUE #6870] Advertise a stable family for each tool in `tools/list` metadata, and document that DeepSeek Harness does not lazy-load #4208