# langgraph-bigtool lets an agent find the tool it needs from a registry > langgraph-bigtool is a Python library for LangGraph agents that can access hundreds or thousands of tools, using LangGraph's long-term memory store as a searchable index of tool metadata so the agent retrieves the relevant tools for a problem before calling them. It suits a team whose tool catalogue has outgrown what a model can hold in one prompt, and it needs a LangGraph store with an embedding index. **langchain-ai/langgraph-bigtool** — Build LangGraph agents with large numbers of tools - Repository: https://github.com/langchain-ai/langgraph-bigtool - Stars: 558 · Forks: 48 - Language: Python - License: MIT - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/langchain-ai-langgraph-bigtool ## The problem is the tool list, not the tool calling langgraph-bigtool is a Python library for creating LangGraph agents that can access large numbers of tools, and it works by leveraging LangGraph's long-term memory store to allow an agent to search for and retrieve the relevant tools for a given problem. The distinction is worth being clear about, because it is not a new tool calling mechanism. The model still calls tools the same way. What changes is that the agent is not handed every tool up front. Instead it gets one extra tool, a retrieval tool, which looks up the catalogue and returns the identifiers of the tools worth trying for the current problem. That is the whole architecture, and it is a reasonable answer to a specific failure mode, which is that a prompt with a thousand tool descriptions is both expensive and less accurate, because the model has to sift them itself every turn. The library also inherits LangGraph's out-of-the-box support for streaming, short-term and long-term memory and human-in-the-loop, since it is built on top of LangGraph rather than beside it. ## The registry, the store and the embedding index The quickstart demonstrates the library by equipping an agent with all functions from Python's built-in math library, which the README notes is about fifty tools and that some models can handle that number in a single invocation without issue, so the example is for demonstration. The setup has three parts. A registry is a dict mapping identifiers to tool instances, built with a random uuid per tool. The store is a LangGraph InMemoryStore configured with an index, where the embed key takes the embeddings object, the dims key sets the dimension count, and the fields key lists which properties are indexed, and the example indexes the description field with 1536 dimensions to match a small text embedding model. Each tool is then put into the store under the tools namespace with its name and description. The agent is created with a create_agent call that takes the model and the registry, and the result is a builder whose compile method takes the store. The feature list calls this storage of tool metadata, and notes that control over how descriptions, namespaces and other information are stored goes through LangGraph's built-in persistence layer, with support for both the in-memory backend and Postgres. ## What the agent actually does at run time The recorded output of the demo run makes the mechanism concrete, and it is worth reading because the shape of the trace is what you would design. The first step is an AI message with a tool call to retrieve_tools carrying a query of arc cosine calculation. The tool message that comes back lists the available tools as cos and acos, and only those two. The next step is an AI message calling acos with the argument 0.5. The tool message returns the numeric result, 1.0471975511965976, and the final AI message states that the arc cosine of 0.5 is approximately 1.0472 radians. Two things are worth noting. The retrieval is a separate round trip before any real tool runs, so the cost of the pattern includes one extra model call per tool-using turn. And the retrieved set is small, so the tool descriptions in the second prompt are only the ones that matter, which is where the accuracy and token savings come from. ## Replacing the retrieval with your own logic The customisation section is where the library stops being a fixed pattern. You can pass retrieve_tools_function or retrieve_tools_coroutine into create_agent, and these functions are expected to return a list of IDs. The documented example takes a query and an injected store, calls store.search against the tools namespace with a limit of two, collects the result keys as tool ids, and returns them, with a comment marking the place to insert custom logic. The argument schema is inferred from the type hints, so a function whose query argument is annotated as a Literal of categorical values signals to the model that it should fill in one of those categories rather than free text. The second example shows that the retrieval does not have to run a semantic search at all. It takes a category argument of billing or service and returns the identifier lists directly, which means the whole thing can be a lookup table when the routing is known in advance. ## Retrieval without the store at all The README is explicit that you can implement arbitrary logic for the tool retrieval, which does not have to run semantic search against a query, and it shows the simplest possible version with a registry of three named tools and a retrieval function keyed on a category literal that returns the billing identifiers or the service identifier. The tip underneath explains why the type hint matters, because the argument schema is inferred from type hints, and type hinting the argument as a Literal will signal that the model should populate a categorical value. That is a small trick with a large effect, because without it the model emits a free text query and the function has to guess how to map it, while with it the model is choosing from a fixed set. For a catalogue that is organised into categories rather than described in prose, that is the version worth writing, and it means you can skip the embedding index and the store entirely. ## Packaging, tests and how the project is built The package is on PyPI as langgraph-bigtool at version 0.0.3, requires Python 3.10 or newer, and declares a single runtime dependency, langgraph 0.3.0 or newer, which tells you the library is a thin layer rather than a framework of its own. It is built with the pdm backend, and the development groups are carefully separated. The test group has numpy, pytest, ruff, mypy, pytest-socket, pytest-asyncio and types-setuptools, and the integration group has langchain with the openai extra at 0.3.20 or newer. The pytest-socket dependency is the detail that says the project is careful, because it disables network access during unit tests, and the Makefile confirms it with a --disable-socket flag alongside --allow-unix-socket. The Makefile has separate targets for unit and integration tests, a watch mode through pytest-watch, and lint and format targets that run ruff format and ruff check with --diff so they report rather than rewrite, with the mypy invocation commented out. Ruff is configured at a line length of 88 targeting Python 3.10 with the pycodestyle, pyflakes, isort and bugbear rule sets, and mypy is configured for Python 3.11 with return-any warnings and untyped definitions disallowed. The install and quickstart are one pip command each: ```bash pip install langgraph-bigtool ``` ```bash pip install langgraph-bigtool "langchain[openai]" export OPENAI_API_KEY= ``` ## Conclusion Adopt langgraph-bigtool when your agent's tool count has grown past what fits in a single prompt and you want retrieval to pick the relevant subset, and you are already running LangGraph with a store backend. Do not adopt it for a small fixed tool set, since the extra retrieval step costs a round trip that buys nothing there. Verify first that your store has an embedding index configured, since the library relies on semantic search over the tool descriptions, and that your embedding dimensions match the model you index with. ## FAQ ### How does langgraph-bigtool let an agent use thousands of tools? It uses LangGraph's long-term memory store to index tool metadata, including descriptions and namespaces, and equips the agent with a retrieval tool that returns the identifiers of the tools relevant to the current problem. The agent then calls only those, so the full catalogue never has to fit in one prompt. ### Do I need LangGraph's store to use langgraph-bigtool? No. The README shows that the retrieval logic can be arbitrary and need not run semantic search at all, with an example returning fixed identifier lists per category based on a Literal type hint, which also signals to the model that it should pick a categorical value rather than write free text. ### How do I customise tool retrieval in langgraph-bigtool? Pass retrieve_tools_function or retrieve_tools_coroutine into create_agent, and the function is expected to return a list of IDs. The documented example takes a query and an injected store, calls store.search against the tools namespace with a limit of two and returns the result keys, with a comment marking where to insert your own logic. ### What does langgraph-bigtool depend on? It requires Python 3.10 or newer and declares a single runtime dependency, langgraph 0.3.0 or newer, and the example uses an in-memory store with an embedding index over the description field at 1536 dimensions. Postgres is supported as a store backend through LangGraph's persistence layer. ## Sources - [Issues](https://github.com/langchain-ai/langgraph-bigtool/issues) - [langchain-ai/langgraph-bigtool on GitHub](https://github.com/langchain-ai/langgraph-bigtool) - [License: MIT](https://github.com/langchain-ai/langgraph-bigtool/blob/main/LICENSE) - [README](https://github.com/langchain-ai/langgraph-bigtool/blob/main/README.md) - [Releases](https://github.com/langchain-ai/langgraph-bigtool/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/langchain-ai-langgraph-bigtool