# What Is the `tool_index_path` Parameter in Needle Initialization?

> Discover the purpose of the tool_index_path parameter in Needle initialization. Learn how it speeds up tool retrieval for large catalogs by managing pre-computed tool embeddings.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: api-reference
- Published: 2026-08-20

---

**The `tool_index_path` parameter specifies where Needle stores or loads pre-computed tool embeddings to accelerate tool retrieval for catalogs containing more than five tools.**

When working with large tool catalogs in the [Needle agent framework](https://github.com/cactus-compute/needle), embedding every tool schema on every run becomes computationally expensive. The `tool_index_path` parameter solves this by enabling persistent caching of these embeddings, dramatically improving startup performance for production deployments.

---

## How Tool Embeddings Work in Needle

The Needle engine uses a **contrastive embedding model** to match user queries against available tools. Here's the sequence:

1. **Tool embedding** — Each tool schema is embedded once using a built-in contrastive head
2. **Query embedding** — Every user query is embedded during the turn
3. **Similarity scoring** — The five highest-scoring tools are selected for the prompt

This retrieval mechanism is implemented in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py), where the `Needle` class constructor handles the embedding pipeline.

---

## The Role of `tool_index_path`

According to the Needle source code, this parameter controls **disk persistence** of tool embeddings:

| Scenario | Behavior |
|----------|----------|
| **Path provided** | Embeddings are written to the specified file and re-used on subsequent runs (when tool schemas and model fingerprint match) |
| **Path omitted (`None`)** | Falls back to `~/.cache/cactus-needle/<engine version>/` — or re-embeds tools each time if caching is disabled |

The path encoding and engine handoff occurs in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) lines 55–66, with the actual engine invocation at line 91.

---

## Code Examples

### Default Cache Location

```python
import needle

# Use automatic caching in ~/.cache/cactus-needle/

agent = needle.Needle(
    tools=my_big_tool_list,          # Catalog with >5 tools

    tool_index_path=None,            # Default cache behavior

)
agent.run("find the best flight for me")

```

### Explicit Persistent Path

```python
import needle
from pathlib import Path

index_file = Path("/var/tmp/needle_tool_index.bin")

agent = needle.Needle(
    tools=my_big_tool_list,
    tool_index_path=str(index_file),  # Controlled persistence location

)
agent.run("schedule a meeting with Alice")

```

### Cross-Process Index Sharing

```python
index_file = "/tmp/needle_tool_index.bin"

# Process A creates and saves embeddings

agent_a = needle.Needle(tools=tool_set, tool_index_path=index_file)
agent_a.run("list all my contacts")

# Process B loads existing embeddings instantly

agent_b = needle.Needle(tools=tool_set, tool_index_path=index_file)
agent_b.run("send a message to Bob")

```

---

## Implementation Details

### Constructor Handling

In [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py), the `__init__` method encodes the `tool_index_path` and passes it to the native engine. The engine validates the path format and checks for existing valid embeddings before deciding whether to compute fresh embeddings or load from disk.

### Cache Invalidation

Embeddings are automatically recomputed when:
- Tool schemas change (hash mismatch)
- The engine version changes (model fingerprint mismatch)
- The cache file is corrupted or deleted

This validation logic resides in the native engine layer, ensuring deterministic retrieval behavior across runs.

### Supporting Files

| File | Purpose |
|------|---------|
| [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) | Defines `Needle` class; forwards `tool_index_path` to native engine |
| [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py) | Schema building and tool-indexing logic |
| [`needle/agent/fetch.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/fetch.py) | Engine binary location (used for default cache path derivation) |
| [`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/doc/apis.md) | Public API documentation including persistence behavior (lines 46–49) |

---

## When to Use `tool_index_path`

**Specify an explicit path when:**
- Running in containerized environments without persistent home directories
- Sharing embeddings across multiple processes or nodes
- Controlling cache location for compliance or storage management

**Use the default when:**
- Developing locally with standard toolchain setups
- Tool catalogs change frequently during iteration
- Automatic cache management is acceptable

---

## Summary

- `tool_index_path` enables **persistent storage** of pre-computed tool embeddings for large catalogs (>5 tools)
- The parameter is processed in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) and passed to the native contrastive retrieval engine
- Providing a path delivers **instant startup** on subsequent runs; omitting it uses `~/.cache/cactus-needle/` or skips caching
- Embeddings are **automatically invalidated** when schemas or model versions change

---

## Frequently Asked Questions

### What happens if I provide a path to an existing index with different tools?

Needle detects the schema hash mismatch and recomputes embeddings, overwriting the file with the new index. The invalidation check uses both tool schema fingerprints and engine version metadata.

### Can multiple Needle instances share the same `tool_index_path` concurrently?

Yes, but with caveats. Multiple readers can safely load from the same index file simultaneously. However, concurrent writes from different processes may corrupt the index—serialize agent initialization or use process-specific paths during writes.

### Does `tool_index_path` affect behavior with five or fewer tools?

No. The contrastive retrieval system only activates when the catalog exceeds five tools. Below this threshold, all tools are included in the prompt directly and no embedding cache is created regardless of the parameter value.

### What file format does the index use?

Needle uses a binary format specific to the native engine implementation. The file is not human-readable and should be treated as an opaque cache—do not attempt manual modification or version control of these files.