# What Is the `tool_index_path` Parameter in Needle? Purpose, Usage, and Configuration

> Learn how to use the tool_index_path parameter in Needle to define custom tools for LLM agents. Understand its purpose, usage, and configuration for enhanced agent functionality.

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

---

**The `tool_index_path` parameter specifies the file path to a JSON-based tool index that enumerates custom tools available to Needle's LLM-driven agents.**

In the Needle framework, `tool_index_path` provides a flexible mechanism for extending agent capabilities without modifying source code. This parameter points to a structured definition file that Needle parses at startup to register custom tools with the agent runtime.

## What Does `tool_index_path` Configure?

`tool_index_path` controls **how and where Needle discovers tool definitions**. When you supply this argument, Needle performs three operations:

1. **Loads** the JSON file from the specified filesystem path
2. **Parses** each tool entry to extract name, description, parameter schema, and implementation reference
3. **Registers** the resulting tool schemas with the agent's prompt context, enabling the LLM to invoke them through the tool-use API

This externalized configuration approach lets you add, remove, or modify tools by editing a JSON file rather than changing Python code in [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py).

## File Structure and Expected Format

The tool index file follows a JSON schema with a top-level `tools` array. Each tool entry requires four fields:

| Field | Description | Example Value |
|-------|-------------|---------------|
| `name` | Identifier used by the LLM to invoke the tool | `"search_web"` |
| `description` | Natural language explanation of tool purpose | `"Search the web for a query..."` |
| `parameters` | JSON Schema object defining expected arguments | `{"type": "object", "properties": {...}}` |
| `implementation` | Python import path to the callable implementation | `"needle.agent.tools.search_web"` |

### Example Tool Index File

```json
{
  "tools": [
    {
      "name": "search_web",
      "description": "Search the web for a query and return the top result.",
      "parameters": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Search query to execute"
          }
        },
        "required": ["query"]
      },
      "implementation": "needle.agent.tools.search_web"
    },
    {
      "name": "calculate",
      "description": "Perform a mathematical calculation.",
      "parameters": {
        "type": "object",
        "properties": {
          "expression": {
            "type": "string",
            "description": "Arithmetic expression to evaluate"
          }
        },
        "required": ["expression"]
      },
      "implementation": "needle.agent.tools.calculate"
    }
  ]
}

```

Save this structure to a file (e.g., [`my_tools.json`](https://github.com/cactus-compute/needle/blob/main/my_tools.json)) and reference it via `tool_index_path` when launching Needle.

## Command-Line Usage

Pass the `tool_index_path` value using the `--toolindexpath` flag in Needle's CLI:

```bash

# Run Needle with a custom tool index

needle run --toolindexpath ./config/my_tools.json

# Override default tools with a minimal custom set

needle run --toolindexpath /app/tools/production_tools.json --agent default

```

The CLI parser in [`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py) handles this argument and ensures the tool index loads before agent initialization begins.

## Internal Implementation Details

According to the cactus-compute/needle source code, the `tool_index_path` parameter flows through several key components:

- **[`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py)** — Parses `--toolindexpath` and validates the file exists before passing the path to the agent runtime
- **[`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py)** — Contains `build_schema()` and the `@tool` decorator that transform Python callables into the structured descriptions used by the index
- **[`needle/agent/fetch.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/fetch.py)** — Reads and deserializes the JSON file specified by `tool_index_path`, then registers each tool with the agent's tool registry

When the agent receives a completion request, available tools (loaded from `tool_index_path`) are serialized into the prompt according to the target LLM's tool-use format—typically OpenAI-style function calling or equivalent schemas.

## When to Use `tool_index_path`

Use `tool_index_path` in these scenarios:

- **Environment-specific tools** — Different tool sets for development, staging, and production deployments
- **Experimentation** — Rapidly prototype new tools without code changes
- **Third-party integrations** — Share standardized tool definitions across teams or repositories
- **Security boundaries** — Restrict or expand available capabilities per deployment context

If you omit `tool_index_path`, Needle falls back to built-in tools defined in [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py) or the default configuration hardcoded in the agent class.

## Summary

- **`tool_index_path`** points to a JSON file that enumerates custom tools for Needle agents
- The file follows a structured schema with `name`, `description`, `parameters`, and `implementation` fields
- Use `--toolindexpath` at the CLI to load custom tools without code changes
- The implementation spans [`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py), [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py), and [`needle/agent/fetch.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/fetch.py)

## Frequently Asked Questions

### What happens if `tool_index_path` points to a malformed JSON file?

Needle raises a parsing error during startup before initializing the agent. The error message indicates the specific JSON syntax problem and the file location, allowing you to fix the configuration before the agent attempts to use any tools.

### Can I combine tools from `tool_index_path` with built-in tools?

Yes. When `tool_index_path` is provided, Needle typically merges the custom tools with the default set unless you explicitly disable built-ins through additional flags. Check [`needle/cli.py`](https://github.com/cactus-compute/needle/blob/main/needle/cli.py) for merge behavior specific to your Needle version.

### Does `tool_index_path` support hot-reloading of tools during runtime?

No. Needle loads the tool index once at startup. To apply changes to the tool definitions, you must restart the agent process with the updated JSON file. Runtime tool registration would require modifications to [`needle/agent/fetch.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/fetch.py) or custom agent implementations.

### What JSON Schema version does the `parameters` field use?

The `parameters` object uses **JSON Schema Draft 7** conventions, compatible with OpenAI's function calling specification. Needle's `build_schema()` utility in [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py) can auto-generate compliant schemas from Python type annotations if you prefer defining tools in code rather than JSON.