Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Tool collections: coarse-grained grouping with progressive disclosure

Aperta
  • Qualcosa non va?
#255 13 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Tranquilla
Stack tecnologico
javascript
Ambito
api

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.
Lingua principale
Bikeshed
Stelle
4.7k
Fork
328
Merge medio
2g 15h
PR unite (30g)
16

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di webmachinelearning/webmcp

Tutte le issue di webmachinelearning/webmcp

Issue simili

Altre issue su Backend & API Design

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.