OpenJarvis/docs/user-guide/tools.md

Tools

The tool system enables agents to perform actions beyond text generation -- calculations, memory lookups, file reading, and sub-model calls. Tools follow a spec-driven design with a central dispatch engine and OpenAI function-calling format support.

Architecture

Agent  -->  Engine (with tool defs)  -->  tool_calls response  -->  ToolExecutor  -->  Tool.execute()
  ^                                                                                          |
  |                                                                                          v
  +-------------------------------  ToolResult  <--------------------------------------------+

---

BaseTool ABC

All tools implement the BaseTool abstract base class.

from abc import ABC, abstractmethod
from openjarvis.tools._stubs import ToolSpec
from openjarvis.core.types import ToolResult

class BaseTool(ABC):
    tool_id: str

    @property
    @abstractmethod
    def spec(self) -> ToolSpec:
        """Return the tool specification."""

    @abstractmethod
    def execute(self, **params) -> ToolResult:
        """Execute the tool with the given parameters."""

    def to_openai_function(self) -> dict:
        """Convert to OpenAI function-calling format."""

The to_openai_function() method is provided by the base class and converts the tool's spec into the format expected by OpenAI-compatible APIs:

{
  "type": "function",
  "function": {
    "name": "calculator",
    "description": "Evaluate a mathematical expression safely.",
    "parameters": {
      "type": "object",
      "properties": {
        "expression": {
          "type": "string",
          "description": "Math expression to evaluate"
        }
      },
      "required": ["expression"]
    }
  }
}

---

ToolSpec

The ToolSpec dataclass describes a tool's interface and characteristics.

Field	Type	Default	Description
name	str	--	Unique tool identifier
description	str	--	Human-readable description (sent to the model)
parameters	dict[str, Any]	{}	JSON Schema for the tool's parameters
category	str	""	Tool category (e.g., math, memory, reasoning)
cost_estimate	float	0.0	Estimated cost per invocation
latency_estimate	float	0.0	Estimated latency per invocation
requires_confirmation	bool	False	Whether the tool requires user confirmation
metadata	dict[str, Any]	{}	Additional metadata

---

ToolResult

The ToolResult dataclass holds the result of a tool execution.

Field	Type	Default	Description
tool_name	str	--	Name of the tool that was called
content	str	--	The tool's output (text)
success	bool	True	Whether the execution succeeded
usage	dict[str, Any]	{}	Token usage (for LLM tool)
cost_usd	float	0.0	Actual cost of the invocation
latency_seconds	float	0.0	Measured execution latency
metadata	dict[str, Any]	{}	Additional metadata

---

ToolExecutor

The ToolExecutor is the central dispatch engine for tool calls. It manages a set of tool instances, parses JSON arguments, measures execution latency, and publishes events on the event bus.

from openjarvis.tools._stubs import ToolExecutor

executor = ToolExecutor(tools=[calculator, think_tool], bus=event_bus)

# Get OpenAI-format tool definitions
openai_tools = executor.get_openai_tools()

# Execute a tool call
from openjarvis.core.types import ToolCall
tc = ToolCall(id="call_1", name="calculator", arguments='{"expression": "2+2"}')
result = executor.execute(tc)
print(result.content)  # "4"

Execution Flow

1. Parse arguments: The arguments JSON string from the ToolCall is deserialized.
2. Publish start event: TOOL_CALL_START is emitted on the event bus with tool name and arguments.
3. Execute: The tool's execute() method is called with the parsed parameters.
4. Measure latency: Execution time is recorded in result.latency_seconds.
5. Publish end event: TOOL_CALL_END is emitted with success status and latency.
6. Return result: The ToolResult is returned to the caller.

If the tool name is unknown, a ToolResult with success=False is returned. If JSON parsing fails or the tool raises an exception, the error is captured and returned as a failed ToolResult.

Methods

Method	Returns	Description
execute(tool_call)	ToolResult	Parse args, dispatch, measure, emit events
available_tools()	list[ToolSpec]	Return specs for all registered tools
get_openai_tools()	list[dict]	Return tools in OpenAI function format

---

Built-in Tools

Calculator

Registry key: calculator | Category: math

Evaluates mathematical expressions safely using Python's ast module. No arbitrary code execution -- only whitelisted operations are allowed.

Parameters:

Parameter	Type	Required	Description
expression	string	Yes	Math expression (e.g., "2+3*4", "sqrt(16)")

Supported operations:

Category	Operations
Arithmetic	+, -, *, /, // (floor div), % (mod), ** (power)
Functions	abs, round, min, max, sqrt, log, log10, log2
Trigonometry	sin, cos, tan
Rounding	ceil, floor
Constants	pi, e

Example:

from openjarvis.tools.calculator import CalculatorTool

calc = CalculatorTool()
result = calc.execute(expression="sqrt(144) + 3**2")
print(result.content)   # "21.0"
print(result.success)   # True

Think

Registry key: think | Category: reasoning

A zero-cost reasoning scratchpad. The input is echoed back as the output, allowing the model to "think out loud" during a tool-calling loop. This enables chain-of-thought reasoning within the agent workflow.

Parameters:

Parameter	Type	Required	Description
thought	string	Yes	The reasoning or thought process

Example:

from openjarvis.tools.think import ThinkTool

think = ThinkTool()
result = think.execute(thought="Let me break this problem into steps...")
print(result.content)   # "Let me break this problem into steps..."
print(result.success)   # True

!!! info "Cost and Latency" The Think tool has zero cost and near-zero latency, making it ideal for structured reasoning without consuming additional resources.

Retrieval

Registry key: retrieval | Category: memory

Searches the memory backend for relevant context and returns formatted results with source attribution.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Search query
top_k	integer	No	Number of results (default: 5)

Constructor parameters:

Parameter	Type	Default	Description
backend	MemoryBackend	None	Memory backend to search
top_k	int	5	Default number of results

Example:

from openjarvis.tools.retrieval import RetrievalTool
from openjarvis.memory.sqlite import SQLiteMemory

backend = SQLiteMemory(db_path="./memory.db")
retrieval = RetrievalTool(backend=backend)
result = retrieval.execute(query="machine learning")
print(result.content)   # Formatted context with source tags

LLM

Registry key: llm | Category: inference

Delegates a sub-query to an inference engine. Useful for summarization, sub-questions, or generating structured output within an agent workflow.

Parameters:

Parameter	Type	Required	Description
prompt	string	Yes	The prompt to send to the model
system	string	No	Optional system message for context

Constructor parameters:

Parameter	Type	Default	Description
engine	InferenceEngine	None	Inference engine to use
model	str	""	Model identifier

Example:

from openjarvis.tools.llm_tool import LLMTool

llm = LLMTool(engine=my_engine, model="qwen3:8b")
result = llm.execute(
    prompt="Summarize: AI is transforming industries...",
    system="You are a concise summarizer.",
)
print(result.content)

FileRead

Registry key: file_read | Category: filesystem

Reads file contents with safety validations. Supports optional directory restrictions, file size limits (1 MB max), and line count limiting.

Parameters:

Parameter	Type	Required	Description
path	string	Yes	Path to the file to read
max_lines	integer	No	Maximum lines to return (default: all)

Constructor parameters:

Parameter	Type	Default	Description
allowed_dirs	list[str]	None	Restrict file access to these directories

Safety features:

• Path validation against allowed directories (when configured)
• Maximum file size: 1 MB
• UTF-8 encoding required (rejects binary files)
• Existence and file-type checks

Example:

from openjarvis.tools.file_read import FileReadTool

reader = FileReadTool(allowed_dirs=["/home/user/projects"])
result = reader.execute(path="/home/user/projects/README.md", max_lines=50)
print(result.content)
print(result.metadata)  # {"path": "/home/user/projects/README.md", "size_bytes": 1234}

---

Tool Registration

Tools are registered via the @ToolRegistry.register() decorator, making them discoverable by name at runtime.

from openjarvis.core.registry import ToolRegistry
from openjarvis.tools._stubs import BaseTool, ToolSpec
from openjarvis.core.types import ToolResult


@ToolRegistry.register("my_tool")
class MyTool(BaseTool):
    tool_id = "my_tool"

    @property
    def spec(self) -> ToolSpec:
        return ToolSpec(
            name="my_tool",
            description="A custom tool that does something useful.",
            parameters={
                "type": "object",
                "properties": {
                    "input": {
                        "type": "string",
                        "description": "The input to process.",
                    },
                },
                "required": ["input"],
            },
            category="custom",
        )

    def execute(self, **params) -> ToolResult:
        value = params.get("input", "")
        return ToolResult(
            tool_name="my_tool",
            content=f"Processed: {value}",
            success=True,
        )

After registration, use the tool with an agent:

jarvis ask --agent orchestrator --tools my_tool "Process this data"

---

Using Tools with Agents

Via CLI

Tools are specified as a comma-separated list with the --tools flag. An agent (typically orchestrator) must be selected:

# Single tool
jarvis ask --agent orchestrator --tools calculator "What is 15% of 340?"

# Multiple tools
jarvis ask --agent orchestrator --tools calculator,think "Solve: 2x + 5 = 13"

# All available tools (list them)
jarvis ask --agent orchestrator --tools calculator,think,retrieval,file_read "..."

Via Python SDK

Tools are passed as a list of name strings:

from openjarvis import Jarvis

j = Jarvis()

# Use calculator and think tools
result = j.ask_full(
    "What is the area of a circle with radius 7?",
    agent="orchestrator",
    tools=["calculator", "think"],
)

for tr in result["tool_results"]:
    print(f"  {tr['tool_name']}: {tr['content']} (success={tr['success']})")

j.close()

The SDK automatically instantiates tool objects with appropriate dependencies. For example, the retrieval tool receives the configured memory backend, and the llm tool receives the active engine and model.