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

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.

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

{
  "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) 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:

# 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 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 — Parses --toolindexpath and validates the file exists before passing the path to the agent runtime
• 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 — 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 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, needle/agent/tools.py, and 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 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 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 can auto-generate compliant schemas from Python type annotations if you prefer defining tools in code rather than JSON.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}