Getting Started
How Runstack avoids context bloat with a tool registry and four meta tools—and how agents discover, authenticate, and execute tools at scale.
Source: https://runstack.engineer/docs/getting-started
Runstack is built so you can offer 1,000+ tools without stuffing every schema into the model on every turn. Domain tools live in a tool registry; the LLM only sees four meta tools that search, authenticate, connect, and execute on demand.
The problem: context bloat
When every toolkit tool is exposed directly to the model, each name, description, and JSON schema is sent on every request. As you add toolkits and tools:
- Token usage grows quickly
- Responses slow down
- You risk hitting context limits
- Tool choice becomes noisier and less reliable
That pattern does not scale when your product roadmap adds toolkits continuously.
The solution: registry + meta tools
Runstack splits responsibilities:
| Layer | Role |
|---|---|
| Tool registry | Stores all registered tools across toolkits—metadata, parameters, auth requirements—not loaded into the model until needed. |
| Meta tools | The only tools the LLM sees in its tool list. They query the registry and run work on the user's behalf. |
The model discovers tools with search, checks or establishes auth when required, then executes by name. You can add toolkits to the registry without changing the four meta tools the model must understand.
The four meta tools
| Meta tool | Purpose |
|---|---|
| search_tools | Search the registry by regex (names and/or descriptions). Returns matching tools, schemas, and auth hints. |
| check_authentication | Verify the user has connected whatever a tool requires. |
| initiate_connection | Return an OAuth (or connection) URL when the user still needs to link a provider. |
| execute_tool | Run a registry tool by exact name and arguments, with tokens injected server-side. |
See the full API shape in MCP Tools.
Why this scales
- Fixed tool surface — Four meta tools in context, whether the registry has 40 or 4,000 entries.
- On-demand metadata — Only search results for the current task enter the conversation.
- Lower latency — Smaller default tool payloads and clearer routing for the model.
- Toolkit growth — New toolkits and tools ship in the registry; integrators do not redeploy giant tool lists.
How a request flows
When the toolkit you need is already linked, the agent searches the registry, confirms auth, and runs the tool—no OAuth detour:
<Mermaid
chart={`sequenceDiagram
participant U as User
participant L as LLM + meta tools
participant R as Tool registry
U->>L: "Create a Linear issue: Fix checkout timeout"
L->>R: search_tools(pattern: "linear.*issue|create")
R-->>L: linear_create_issue(team, title, ...)
L->>L: check_authentication(linear_create_issue)
L-->>L: connected
L->>R: execute_tool(linear_create_issue, { title: "Fix checkout timeout", ... })
R-->>L: { issueId, url }
L->>U: "Created ENG-482 — link in Linear"`}
/>
Flow when auth is required
Many registry tools need a linked account. Runstack walks the user through OAuth with initiate_connection—tokens stay on the server, not in the model.
Knowledge bases (KB) complement that: they store durable context from earlier turns and runs (profile fields, defaults, IDs you already resolved). On the next task the agent can pull from KB instead of calling a tool again just to rediscover the same fact—for example using stored username: deepraj when assigning an issue, rather than invoking something like getUsername on every request.
<Mermaid
chart={`sequenceDiagram
participant U as User
participant L as LLM + meta tools
participant KB as Knowledge base
participant R as Tool registry
participant O as Provider OAuth
Note over U,O: First time — connect the toolkit
U->>L: "List my open issues"
L->>R: search_tools(pattern: "issue|list")
R-->>L: list_issues (requires connection)
L->>L: check_authentication(list_issues)
L-->>L: not connected
L->>L: initiate_connection(provider)
U->>O: Complete OAuth
O-->>U: Connected
Note over U,O: Later — auth OK, context from KB
U->>L: "Create an issue assigned to me"
L->>KB: Pull stored context (username, team)
KB-->>L: username deepraj, defaultTeam ENG
L->>L: check_authentication(create_issue)
L-->>L: connected
L->>R: execute_tool(create_issue, assignee deepraj)
Note right of L: Skips getUsername — KB has profile context
R-->>L: { issueId, url }
L->>U: "Created ENG-490 and assigned to you"`}
/>
What the model is guided to do
Runstack's system behavior follows this loop:
- search_tools — Find registry entries that match the user's intent.
- KBrain (when enabled in Context) — Runstack injects knowledge base excerpts and workspace memory into the system prompt (not a fifth meta tool).
- check_authentication — If a match requires a connection, verify it exists.
- initiate_connection — If not connected, return a link for the user to complete OAuth.
- execute_tool — Run the chosen tool with validated arguments (often enriched from KB).
- Respond — Use tool output to answer the user; repeat if more steps are needed. New facts can be written back to KB for the next turn.
Where to go next
- MCP Tools: Parameters, responses, and usage limits for each meta tool.
- Toolkits: Toolkits, OAuth linking, and what you can use today.
- Runstack Studio: Build visual agent workflows and publish them to the marketplace.
- Cursor: Install Runstack MCP in Cursor over HTTP or stdio.
- API Keys: Create keys and authenticate registry access.