Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Tool collections: coarse-grained grouping with progressive disclosure

Open
  • Is something wrong?
#255 13 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
javascript
Domain
api

Research direction

Start by reading this proposal alongside #199, #161, #227, and #135 to understand the related registry, skills, and cross-document discussions. The issue proposes adding registerCollection() while preserving registerTool() and getTools() behavior; define what collection registration and discovery should guarantee, including identity across navigation and server roundtrips. Done means the proposal has a settled API and behavior that address progressive disclosure and compatibility.

Written by the indexing model from the issue text.

Description

enhancement

In a large JS application, the number of registered tools grows fast. Tools accumulate across routes, across features, and across client/server boundaries. A moderately complex app can easily surface 100+ tools (see also #88, where an MCP bridge exposes 50+ from a single server). Today getTools() hands the agent one flat list, which means:

  • The agent must read every tool description to find the 3 it needs, spending tokens on tools that are irrelevant to the current task.
  • As the tool list grows, the accuracy of the model selection will decrease. This was a well-documented failure mode for large flat tool lists in backend MCP, and it's why progressive disclosure patterns (tool search, toolsets) have emerged in backend MCP.
  • There's no unit between "one tool" and "every tool on the page."

Applications already have natural coarse-grained groupings: an auth flow (sign-in, sign-out, verify-2fa, recover-account), a cart flow (add-to-cart, remove-from-cart, apply-promo, begin-checkout), a video experience (play, seek, set-captions, set-speed). What's missing is a way to expose that structure so an agent can read a handful of group descriptions first, pick the relevant one, and only then drill into those tools.

There's a second problem this addresses. When a tool execution spans a client/server interaction, or across tabs, the tool call triggers a navigation or a server roundtrip, and tools re-register on the way back. We've sometimes observed agents failing to re-find the relevant tools after the roundtrip. A collection whose identity persists (from cart count/data to server to success/error) improves continuity.

Strawman

Keep registerTool() as-is and add a collection primitive alongside it:

document.modelContext.registerCollection({
  name: "cart-checkout",
  description: "Create cart, process order, report to user",
  tools: ["cart-inventory", "confirm-payment", "process-cart-order", "get-order-status", "cancel-order", "cart-success", "cart-error"],
});

Benefits:

  • Backwards compatible, and keeps the existing API simple. Agents that don't understand collections call getTools() and get the flat list they get today. Tools registered without a collection remain top-level. Collections are additive structures that preserve the current API.
  • Deterministic. A collection is a defined set, defined by the application owner. It doesn’t require natural-language interpretation. Devs can define this according to how they would like their application to be used.
  • Cheap for the agent. The initial payload is smaller, the agent doesn’t have to process non-related tools for task completion.
  • Can help with cross-document, and cross-tab actions. We need tools to outlive a single document view: #227 extends discovery across the browsing context group, and #135 discusses cross-document tool responses. A collection could provide cohesion beyond a navigation or server roundtrip. The agent could have some continuity of defined tools instead of re-reading an entire flat list.

Frameworks

Filing this partly as a sub-topic of the frameworks meta issue (#199, section 2: scoped, composable registries). This could fit well into Framework mental-models.

Alternatives considered: Skills (#161)

#161 proposes skills that bundle tools with workflow instructions and structured context, and grouping falls out of that as a side effect (tools: ["searchProducts", "addToCart", ...]). Skills are solving a real problem, but I don't think they're the right home for grouping, for two reasons:

  1. Creates two API surface areas to think about: If grouping only exists via skills, a developer who just wants to expose their cart tools has to reach for a primitive whose main job is behavioral guidance, and every framework integration has to reason about both surfaces. Grouping is structural and could live with tool registration itself, where you’re already defining it.
  2. Determinism: As I alluded to above, a skill's instructions field leaves room for LLM-based agents to interpret, which clients may weigh differently or ignore completely. Developers need a consistent, enumerable way to expose groupings that behave the same in every client.
Dominant language
Bikeshed
Stars
4.7k
Forks
328
Avg merge
2d 15h
Merged PRs (30d)
16

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from webmachinelearning/webmcp

All issues in webmachinelearning/webmcp

Similar issues

More Backend & API Design issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.