llm4s-docs
API
Generated with
llm4s-docs/org.llm4s/org.llm4s.toolapi

org.llm4s.toolapi

package org.llm4s.toolapi

Members list

Packages

package org.llm4s.toolapi.builtin

Built-in tools for common agent operations.

Built-in tools for common agent operations.

This package provides production-ready tools that can be used out of the box:

== Core Utilities (No API Keys Required) ==

import org.llm4s.toolapi.builtin.core._

val tools = new ToolRegistry(Seq(
 DateTimeTool.tool,
 CalculatorTool.tool,
 UUIDTool.tool,
 JSONTool.tool
))

== File System Tools ==

import org.llm4s.toolapi.builtin.filesystem._

val fileTools = new ToolRegistry(Seq(
 ReadFileTool.create(FileConfig(
   maxFileSize = 512 * 1024,
   allowedPaths = Some(Seq("/tmp"))
 )),
 ListDirectoryTool.tool,
 FileInfoTool.tool
))

== HTTP Tools ==

import org.llm4s.toolapi.builtin.http._

val httpTools = new ToolRegistry(Seq(
 HTTPTool.create(HttpConfig(
   timeout = 10.seconds,
   allowedDomains = Some(Seq("api.example.com"))
 ))
))

== Shell Tools ==

import org.llm4s.toolapi.builtin.shell._

// Read-only shell (safe commands)
val shellTools = new ToolRegistry(Seq(
 ShellTool.create(ShellConfig.readOnly())
))

// Development shell with common dev tools
val devShellTools = new ToolRegistry(Seq(
 ShellTool.create(ShellConfig.development())
))

== Search Tools ==

import org.llm4s.toolapi.builtin.search._

val searchTools = new ToolRegistry(Seq(
 DuckDuckGoSearchTool.tool
))

== All Built-in Tools ==

import org.llm4s.toolapi.builtin.BuiltinTools

// Get all safe tools (no shell, restricted filesystem)
val tools = BuiltinTools.withHttpSafe()

// Get all tools with custom config
val allTools = BuiltinTools.all(
 fileConfig = FileConfig(allowedPaths = Some(Seq("/tmp")))
)

Attributes

See also
package org.llm4s.toolapi.tools

Type members

Classlikes

@Stable
final case class ArraySchema[A] extends SchemaDefinition[Seq[A]]

Array schema with item type and size constraints.

Array schema with item type and size constraints.

Value parameters

description

Human-readable description shown to the LLM

itemSchema

Schema applied to every element of the array

maxItems

Maximum number of elements (inclusive)

minItems

Minimum number of elements (inclusive)

uniqueItems

When true, all elements must be distinct

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait SchemaDefinition[Seq[A]]
class Object
trait Matchable
class Any
Show all
object ArraySchema

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
@Stable
final case class BooleanSchema extends SchemaDefinition[Boolean]

Boolean schema.

Boolean schema.

Value parameters

description

Human-readable description shown to the LLM

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait SchemaDefinition[Boolean]
class Object
trait Matchable
class Any
Show all
object BooleanSchema

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
@Stable
final case class IntegerSchema extends SchemaDefinition[Int]

Integer schema with range and divisibility constraints.

Integer schema with range and divisibility constraints.

Value parameters

description

Human-readable description shown to the LLM

exclusiveMaximum

Exclusive upper bound

exclusiveMinimum

Exclusive lower bound

maximum

Inclusive upper bound

minimum

Inclusive lower bound

multipleOf

Value must be a multiple of this integer

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait SchemaDefinition[Int]
class Object
trait Matchable
class Any
Show all
object IntegerSchema

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
@Stable
case class NullableSchema[T](underlying: SchemaDefinition[T]) extends SchemaDefinition[Option[T]]

Nullable schema wrapper that widens an existing schema to also accept null.

Nullable schema wrapper that widens an existing schema to also accept null.

Emits "type": ["<original>", "null"] in the JSON Schema output.

Value parameters

underlying

The non-nullable schema to wrap

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait SchemaDefinition[Option[T]]
class Object
trait Matchable
class Any
Show all
@Stable
final case class NumberSchema extends SchemaDefinition[Double]

Number schema (floating-point) with range and divisibility constraints.

Number schema (floating-point) with range and divisibility constraints.

Value parameters

description

Human-readable description shown to the LLM

exclusiveMaximum

Exclusive upper bound

exclusiveMinimum

Exclusive lower bound

isInteger

When true the JSON type is "integer" instead of "number"

maximum

Inclusive upper bound

minimum

Inclusive lower bound

multipleOf

Value must be a multiple of this number

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait SchemaDefinition[Double]
class Object
trait Matchable
class Any
Show all
object NumberSchema

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
@Stable
final case class ObjectSchema[T] extends SchemaDefinition[T]

Object schema with a fixed set of typed properties.

Object schema with a fixed set of typed properties.

In strict mode all properties are emitted as required regardless of the individual PropertyDefinition.required flag, matching the behaviour expected by OpenAI strict-mode tool definitions.

Value parameters

additionalProperties

Whether to allow extra keys beyond those listed

description

Human-readable description shown to the LLM

properties

Ordered sequence of property definitions

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait SchemaDefinition[T]
class Object
trait Matchable
class Any
Show all
object ObjectSchema

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
@Stable
final case class PropertyDefinition[T]

A named property within an ObjectSchema.

A named property within an ObjectSchema.

Value parameters

name

Property key in the JSON object

required

Whether the property is required

schema

Schema applied to the property value

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object PropertyDefinition

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
@Stable
final case class SafeParameterExtractor

Safe parameter extraction with type checking and path navigation.

Safe parameter extraction with type checking and path navigation.

This extractor provides two modes of operation:

  1. Simple mode: Returns Either[String, T] for backward compatibility
  2. Enhanced mode: Returns Either[ToolParameterError, T] for structured error reporting

Value parameters

call

The tool call being run, when the caller knows it: an agent sets it for every call, with the call's id and idempotency key (ToolCallInfo); plain ToolRegistry tool calling leaves it None.

params

The JSON parameters to extract from

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object SafeParameterExtractor

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
@Stable
object Schema

Schema builder — fluent API for creating JSON Schema SchemaDefinition values.

Schema builder — fluent API for creating JSON Schema SchemaDefinition values.

Attributes

Example 
import org.llm4s.toolapi.Schema
val schema = Schema.`object`[Map[String, Any]]("Query parameters")
 .withProperty(Schema.property("q",    Schema.string("Search query")))
 .withProperty(Schema.property("limit", Schema.integer("Max results"), required = false))
Supertypes
class Object
trait Matchable
class Any
Self type
Schema.type
@Stable
sealed trait SchemaDefinition[T]

Base trait for all JSON Schema definitions used in tool parameter specifications.

Base trait for all JSON Schema definitions used in tool parameter specifications.

Each concrete subclass corresponds to a JSON Schema type and can be converted to a ujson.Value for inclusion in OpenAI-compatible tool definitions via SchemaDefinition.toJsonSchema.

Attributes

Supertypes
class Object
trait Matchable
class Any
Known subtypes
class ArraySchema[A]
class NullableSchema[T]
class NumberSchema
class ObjectSchema[T]
class StringSchema
Show all
@Stable
final case class StringSchema extends SchemaDefinition[String]

String schema with validation options.

String schema with validation options.

Value parameters

description

Human-readable description shown to the LLM

enumValues

Restricts valid values to this closed set

maxLength

Maximum allowed string length

minLength

Minimum allowed string length

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait SchemaDefinition[String]
class Object
trait Matchable
class Any
Show all
object StringSchema

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
@Stable
class ToolBuilder[T, R]

Builder for ToolFunction definitions using a fluent API.

Builder for ToolFunction definitions using a fluent API.

Obtained via the companion ToolBuilder object:

ToolBuilder[Map[String, Any], MyResult]("my_tool", "Does something", schema)
 .withHandler(extractor => Right(MyResult(...)))
 .buildSafe()

Value parameters

description

Natural-language description for the LLM

handler

Optional handler; must be set before calling buildSafe

name

Tool name

schema

Parameter schema

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
object ToolBuilder

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
@Stable
sealed trait ToolCallError

Enhanced tool call errors with consistent formatting.

Enhanced tool call errors with consistent formatting.

Covers the full lifecycle of a tool invocation: unknown function, null arguments, invalid arguments, handler errors, and execution exceptions.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class Cancelled
class HandlerError
class Timeout
Show all
object ToolCallError

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
@Stable
object ToolCallErrorJson

JSON serialization helpers for structured tool error payloads.

JSON serialization helpers for structured tool error payloads.

Converts ToolCallError and ToolParameterError instances to machine-readable JSON format for ToolMessage.content, enabling LLMs and consumers to programmatically parse validation errors and self-correct tool arguments.

Output schema:

{
 "isError": true,
 "toolName": "<string>",
 "errorType": "<unknown_function|null_arguments|invalid_arguments|handler_error|execution_error|timeout|cancelled>",
 "message": "<human readable summary>",
 "parameterErrors": [   // optional: only present for invalid_arguments
   {
     "parameterName": "<string>",
     "kind": "<missing_parameter|null_parameter|type_mismatch|invalid_nesting>",
     "expectedType": "<string|null>",
     "receivedType": "<string|null>",
     "availableParameters": ["<string>", ...]  // optional hint
   }
 ],
 "error": "<legacy error string for older consumers>"
}

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
@Stable
final case class ToolCallInfo

The tool call a ToolFunction handler is running, when its caller knows it: read as SafeParameterExtractor.call. An agent supplies it for every call it runs; plain ToolRegistry tool calling, outside an agent, has no call to describe and leaves it None.

The tool call a ToolFunction handler is running, when its caller knows it: read as SafeParameterExtractor.call. An agent supplies it for every call it runs; plain ToolRegistry tool calling, outside an agent, has no call to describe and leaves it None.

A tool with an external side effect passes idempotencyKey to the system it calls (an Idempotency-Key header, a client token, a unique column), because an agent may run the same call more than once - a retrying middleware, recover after a failure or crash, an approval - and it is the same in every run of one call. The runtime runs a tool at least once, never exactly once; the key de-duplicates only where the external system honours it.

Growth-prone: build it with ToolCallInfo(...) and change it with the with* setters.

Value parameters

idempotencyKey

the same in every run of this call, and different for every other call

toolCallId

the id the model gave the call

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object ToolCallInfo

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
@Stable
final case class ToolCallRequest

Carries the name and parsed JSON arguments for a single tool invocation.

Carries the name and parsed JSON arguments for a single tool invocation.

Produced by the agent framework from org.llm4s.llmconnect.model.ToolCall values in the LLM response. arguments is a pre-parsed ujson.Value (not a raw JSON string), so tool implementations receive structured data directly.

Value parameters

arguments

Parsed JSON arguments; typically a JSON object whose fields correspond to the tool's declared Schema.

functionName

Name of the tool to invoke; matched against ToolFunction.name in ToolRegistry.execute.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object ToolCallRequest

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
@Stable
final case class ToolExecutionConfig

Controls timeout and retry behaviour for tool calls executed through a ToolRegistry.

Controls timeout and retry behaviour for tool calls executed through a ToolRegistry.

A default configuration applies no timeout and no retry, preserving the original single-attempt execution behaviour. Build one with ToolExecutionConfig.apply (or start from ToolExecutionConfig.default) and change it with the with* setters; the constructor and copy are private, so a new field never breaks callers. Pass a configuration to ToolRegistry.execute, ToolRegistry.executeAsync, or ToolRegistry.executeAll when a tool call should fail after a bounded duration or retry transient failures before returning an error.

Value parameters

retryPolicy

optional retry policy for errors considered retryable by ToolCallError.isRetryable

timeout

optional maximum duration to wait for each individual tool call before returning ToolCallError.Timeout

Attributes

Example 
import org.llm4s.toolapi._
import scala.concurrent.ExecutionContext.Implicits.global
import scala.concurrent.duration._
val config = ToolExecutionConfig.default
 .withTimeout(5.seconds)
 .withRetryPolicy(ToolRetryPolicy(maxAttempts = 3, baseDelay = 200.millis))
val registry = new ToolRegistry(Seq(myTool))
registry.execute(request, config)
registry.executeAll(requests, ToolExecutionStrategy.ParallelWithLimit(2), config)
Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object ToolExecutionConfig

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
@Stable
sealed trait ToolExecutionStrategy

Determines how multiple tool calls in a single agent step are executed by ToolRegistry.executeAll.

Determines how multiple tool calls in a single agent step are executed by ToolRegistry.executeAll.

Choose ToolExecutionStrategy.Sequential when calls depend on one another or mutate shared state. Choose ToolExecutionStrategy.Parallel when calls are independent and mostly wait on I/O. Choose ToolExecutionStrategy.ParallelWithLimit when calls can run concurrently but external systems or local resources need bounded concurrency.

Attributes

Example 
val results = registry.executeAll(
 requests,
 strategy = ToolExecutionStrategy.ParallelWithLimit(2)
)
val agentState = agent.runWithStrategy(
 query = "Get weather in London, Paris, and Tokyo",
 tools = registry,
 toolExecutionStrategy = ToolExecutionStrategy.Parallel,
 maxSteps = Some(5)
)
Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
object Parallel
object Sequential
object ToolExecutionStrategy

Factory and singleton values for ToolExecutionStrategy.

Factory and singleton values for ToolExecutionStrategy.

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
@Stable
final case class ToolFunction[T, R]

A fully-defined, executable tool that can be invoked by an LLM.

A fully-defined, executable tool that can be invoked by an LLM.

Bundles together a name, a natural-language description (shown to the model), a SchemaDefinition that describes the expected JSON parameters, and a handler function that performs the actual work.

Prefer constructing instances via ToolBuilder rather than directly.

Type parameters

R

Return type, must have a uPickle ReadWriter

T

Phantom type for the parameter schema (unused at runtime)

Value parameters

description

Natural-language description of what the tool does and when to use it

handler

Business logic; receives a SafeParameterExtractor and returns Right(result) or Left(errorMessage)

name

Unique tool identifier used by the LLM when calling the tool

schema

Parameter schema describing the expected JSON arguments

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object ToolFunction

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
@Experimental
final case class ToolHints

What a tool is likely to do, with the meanings of the MCP tool annotations and their conservative defaults. These are hints a middleware reads (for example to ask approval for a tool that is not read-only), not guarantees: nothing checks that a tool behaves as it says.

What a tool is likely to do, with the meanings of the MCP tool annotations and their conservative defaults. These are hints a middleware reads (for example to ask approval for a tool that is not read-only), not guarantees: nothing checks that a tool behaves as it says.

It lives in llm4s-core so that both llm4s-agent, whose tool contract carries it, and llm4s-mcp, which reads it from a server's tool annotations, can see it: neither module depends on the other.

Value parameters

destructive

MCP destructiveHint: the tool may perform destructive updates rather than only additive ones; meaningful only when it is not readOnly

idempotent

MCP idempotentHint: calling it again with the same arguments has no further effect; meaningful only when it is not readOnly

openWorld

MCP openWorldHint: the tool may interact with an open world of external entities, such as the web, rather than a closed domain

readOnly

MCP readOnlyHint: the tool does not modify its environment

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
@Experimental
object ToolHints

Factory and default for ToolHints. The defaults are the conservative MCP ones: a tool that does not say what it does is treated as not read-only, destructive, not idempotent and open-world.

Factory and default for ToolHints. The defaults are the conservative MCP ones: a tool that does not say what it does is treated as not read-only, destructive, not idempotent and open-world.

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
ToolHints.type
@Stable
sealed trait ToolParameterError

Structured error information for tool parameter validation.

Structured error information for tool parameter validation.

Represents specific validation failures when parsing tool call arguments, including missing parameters, type mismatches, null values, and invalid nesting.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class TypeMismatch
object ToolParameterError

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
@Stable
class ToolRegistry(initialTools: Seq[ToolFunction[_, _]])

Registry for tool functions with execution capabilities.

Registry for tool functions with execution capabilities.

Acts as the single point of truth for tools available to an agent. Supports synchronous, asynchronous, and batched execution with configurable concurrency strategies (see ToolExecutionStrategy):

  • execute() — synchronous, blocking execution
  • executeAsync() — asynchronous, non-blocking execution
  • executeAll() — batch execution with a configurable ToolExecutionStrategy

Create a registry by passing an initial set of ToolFunction instances:

val registry = new ToolRegistry(Seq(myTool, anotherTool))
// or use the convenience factories:
ToolRegistry.empty
BuiltinTools.coreSafe.map(new ToolRegistry(_))

Value parameters

initialTools

The tools available in this registry

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
object ToolRegistry

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
@Stable
final case class ToolRetryPolicy

Simple retry policy with exponential backoff and optional jitter.

Simple retry policy with exponential backoff and optional jitter.

Build one with ToolRetryPolicy.apply and change it with the with* setters.

Value parameters

backoffFactor

Multiplier for each subsequent delay (e.g. 2.0 => baseDelay, 2baseDelay, 4baseDelay).

baseDelay

Delay after first failure before first retry.

jitter

Fraction of each delay, from 0.0 to 1.0, that is randomised so that many callers retrying on the same schedule do not hit the backend together. The wait before a retry is drawn uniformly between (1 - jitter) * d and d, where d is delayBeforeAttempt: 0.0 (the default) waits exactly d, 0.5 is "equal jitter" and 1.0 is "full jitter" (anywhere from zero to d). The wait is never longer than d.

maxAttempts

Total attempts (first try + retries); must be >= 1.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object ToolRetryPolicy

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
Generated with