Your AI agent is paying for tools it never uses. Every tool schema, every skill description, and every instruction sitting in the system prompt costs tokens on every single call. For a typical agent with 20 tools and 30 skills, that overhead can easily exceed 5,000 tokens per turn wasted on capabilities the agent does not need for that specific step. Ratel, a new open-source project climbing GitHub with 216 stars, solves this with a simple but powerful idea: progressive disclosure through BM25 retrieval. Instead of loading everything upfront, Ratel indexes tools and skills into searchable catalogs and only injects what the current turn actually requires. The result is roughly 80 percent fewer tokens and measurable accuracy gains on agentic benchmarks.
The Problem: Tool Overload Kills Agent Accuracy
As AI agents grow more capable, developers keep adding tools. A code generation agent might need read, write, search, lint, test, deploy, and debug tools. A sales agent might need CRM lookup, email, calendar, Slack, and spreadsheet tools. Each one adds schema definitions, parameter descriptions, and usage instructions to the context window. The problem compounds when you add skills - higher-level playbooks that bundle multiple tools together with domain-specific logic.
Research has consistently shown that model accuracy degrades as context grows, especially when irrelevant information crowds the prompt. If an agent needs to read a file but the context also contains tool schemas for email, Slack, and CRM operations, the model has to filter through noise to find the right action. The result is slower responses, higher costs, and more frequent tool selection errors. Ratel fixes this by not loading everything at all. Instead, it uses a retrieval-first architecture where tools and skills live in indexes, not in the prompt.
How Ratel Works: BM25 Indexes and Progressive Disclosure
Ratel uses BM25, the same ranking algorithm that powers most search engines, applied to schema-aware tool metadata and skill names and descriptions. The core is a Rust engine called ratel-ai-core that keeps indexes fast and deterministic. TypeScript and Python SDKs wrap this engine through native bindings - NAPI for TypeScript and PyO3 for Python.
When an agent needs to act, it calls a search_capabilities tool. Ratel searches separate tool and skill indexes and returns only the most relevant results. Tools can be invoked by ID directly. Skill instructions stay out of context entirely until the agent explicitly loads the relevant playbook with get_skill_content. This progressive disclosure pattern means the agent pays for exactly what it uses, nothing more.
Semantic and hybrid ranking are opt-in per catalog. When enabled, the SDK asynchronously embeds tools and skills using either an in-process model or any OpenAI-compatible embedding endpoint. This gives teams the option to upgrade from BM25 keyword matching to semantic similarity as their agent grows more complex.
Installation and Quick Start
Ratel ships SDKs for both TypeScript and Python, making it easy to integrate with existing agent frameworks. The install commands are straightforward:
# TypeScript
pnpm add @ratel-ai/sdk
# Python
pip install ratel-aiIn TypeScript, you create a ToolCatalog, register your tools with ID, name, description, and input/output schemas, then wrap them for use in your agent framework. Skills are created in a separate SkillCatalog with tool references and body instructions. The SDK exposes three key functions: searchCapabilitiesTool for retrieval, invokeToolTool for execution, and getSkillContentTool for loading skill instructions on demand.
Ratel also ships a local distribution through ratel-mcp that integrates with Model Context Protocol, making it immediately useful for coding agents like Claude Code, Cursor, and Codex. The benchmark harness at benchmark.ratel.sh provides full results across local, open-source, and frontier model setups.
Comparison to Alternatives
Most agent frameworks handle tool management in one of three ways: load all tools upfront (the default in most SDKs), use an LLM to decide which tools are relevant (adding latency and cost), or build custom routing logic. Ratel takes a different approach with its retrieval-first architecture.
| Approach | Token Cost | Latency | Accuracy Impact | Infrastructure Required |
|---|---|---|---|---|
| All tools upfront (default) | Highest | None | Degrades with tool count | None |
| LLM-based routing | High | High | Depends on routing model | Model inference |
| Vector DB retrieval | Low | Medium | Good with good embeddings | Vector DB infrastructure |
| Ratel (BM25 progressive disclosure) | Lowest (~80% fewer) | Low (in-process) | Improved by removing noise | None (no vector DB) |
The key differentiator is that Ratel requires no additional infrastructure. BM25 runs in-process in Rust with no external database, no embedding pipeline, and no API dependencies. For teams already dealing with agent reliability issues, this simplicity matters.
Why This Matters for Founders
For founders building AI agents - whether for internal workflows, customer-facing products, or developer tools - Ratel addresses a problem that gets worse as agents scale. Tool overload is a friction point that directly affects unit economics. Every wasted token increases API costs without improving outcomes. Every misselected tool creates a bad user experience that erodes trust in the agent.
The fact that Ratel is open source and dual-licensed (Apache 2.0 for the core engine, MIT for the SDKs) means teams can integrate it without licensing friction. The Rust-based core offers performance that Python-only solutions cannot match. And the progressive disclosure pattern represents a design philosophy that more agent builders will likely adopt as they discover that dumping everything into context is not a scalable strategy.
If you are building agents with more than a handful of tools, Ratel is worth evaluating. The project is early at 216 stars but the architecture is sound, the benchmarks are public, and the problem it solves is only going to become more pressing as agents grow more capable and tool ecosystems expand.