# Class LittleGhost::Tool

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost/Tool.html

Give an agent a validated way to call application code. Every tool declares a
model-visible name, description, and input shape before implementing its
operation.

    class TicketStatusTool < LittleGhost::Tool
      tool_name "ticket_status"
      description "Look up a support ticket's status."
      input_schema type: "object", properties: {
        ticket_id: {type: "string"}
      }, required: ["ticket_id"], additionalProperties: false

      def call(input)
        {ticket_id: input.fetch("ticket_id"), status: "waiting_on_customer"}
      end
    end

    class CustomerSupportAgent < LittleGhost::Agent
      tools TicketStatusTool
    end

    run = CustomerSupportAgent.ask("What is happening with ticket SUP-481?")
    run.response

Use application context for authorization, never model-selected input:

    class OrderStatusTool < LittleGhost::Tool
      description "Look up an order for the current account."
      input_schema type: "object", properties: {
        order_number: {type: "string"}
      }, required: ["order_number"], additionalProperties: false

      def call(input)
        Orders.status_for(
          actor_id: run.invocation.actor_id,
          account_id: run.invocation.context.fetch("account_id"),
          order_number: input.fetch("order_number")
        )
      end
    end

    class OrderSupportAgent < LittleGhost::Agent
      tools OrderStatusTool
    end

    OrderSupportAgent.ask(
      "Where is order 481?",
      actor_id: authenticated_user.id,
      context: {account_id: authenticated_user.account_id}
    )

Each value comes from a different part of the run:

`input`
:   Arguments selected by the model. The schema checks their shape, not their
    permission to perform an operation.

`run.invocation.context`
:   Current request values supplied by the application. Use these for
    authorization after the application authenticates the caller.

`context.state`
:   Mutable working state for the run. It may include values restored from a
    Session, so check saved values again before trusting them.

Tool::Binding
:   Run-scoped objects such as the Agent, Run, Runtime, workspace, and
    sandbox. The Binding supplies #run; it does not contain model arguments.

The class DSL produces the specification sent to models. During an Agent run,
the tool registry creates and binds one Tool instance. Tests and custom
integrations may call `execute` directly; it validates the arguments, calls
`call`, and returns a normalized internal result. Tool.define offers the same
contract for an embedded implementation.

Mutable Tool instance state belongs to one Agent run. Registries close tool
instances that implement `close`; `exclusive true` prevents that tool from
overlapping other exclusive tools in the same run.

Validation and application ToolError failures become error results. A
ToolError message is visible to the model and must be safe to disclose;
unexpected exception messages are replaced with their class name.
Cancellation, deadlines, and cleanup errors propagate instead of becoming
ordinary tool output. The configured sandbox, not Tool itself, enforces
filesystem and process isolation.

See the [Tools guide](../tools.md) for the complete path
from model-selected input to application context, sandbox delegation,
concurrency, and code mode.

## Inheritance

`LittleGhost::Tool < Object`

## Attributes

<a id="attribute-i-context"></a>
### `context` (RW)

RunContext supplied to the current #execute call, or nil outside execution.

## Class methods

<a id="method-c-available-3F"></a>
### `.available?`

```ruby
.available?(binding)
```

Returns whether this Tool should be registered for `binding`.

<a id="method-c-available_if"></a>
### `.available_if`

```ruby
.available_if(&predicate)
```

Declares whether this Tool is available for a run-scoped `binding`. With no
block, returns the configured predicate or nil. ToolRegistry omits a Tool
whose predicate returns false before constructing it.

<a id="method-c-define"></a>
### `.define`

```ruby
.define(name:, description:, input_schema: {}, &implementation)
```

Creates an anonymous Tool subclass backed by `implementation`. The block
receives `input` and may also accept the `context:` keyword.

    tool = LittleGhost::Tool.define(
      name: "echo", description: "Echo text.",
      input_schema: {type: "object"}
    ) { |input| input.fetch("text") }

<a id="method-c-description"></a>
### `.description`

```ruby
description()       -> String
description(value)  -> value
```

The model-visible description used to decide when the tool applies.

<a id="method-c-exclusive"></a>
### `.exclusive`

```ruby
exclusive()       -> true or false
exclusive(value)  -> value
```

Whether calls acquire the run-wide exclusive tool lock.

<a id="method-c-input_schema"></a>
### `.input_schema`

```ruby
input_schema()        -> Hash
input_schema(schema)  -> schema
```

The frozen JSON Schema subset used to validate model input.

Setting a non-Hash schema raises ArgumentError. Keys are normalized to strings
and the entire value is deeply frozen.

<a id="method-c-new"></a>
### `.new`

```ruby
.new(binding: Binding.new)
```

Creates a tool with the run-scoped collaborators in `binding`.

<a id="method-c-specification"></a>
### `.specification`

```ruby
.specification()
```

The frozen model-facing name, description, and input schema.

<a id="method-c-tool_name"></a>
### `.tool_name`

```ruby
tool_name()       -> String
tool_name(value)  -> value
```

The model-visible tool name.

Named classes derive a snake-cased default; passing `value` replaces it.

## Instance methods

<a id="method-i-agent"></a>
### `#agent`

```ruby
#agent()
```

Bound agent, when the tool belongs to an agent run.

<a id="method-i-call"></a>
### `#call`

```ruby
#call(_input)
```

Implements the model-requested operation.

Subclasses must override this method. The current RunContext is available
through `context` while the call executes.

<a id="method-i-close"></a>
### `#close`

```ruby
#close()
```

Releases resources owned by this tool. Subclasses may override it.

<a id="method-i-description"></a>
### `#description`

```ruby
#description()
```

Model-visible description declared by the tool class.

<a id="method-i-exclusive-3F"></a>
### `#exclusive?`

```ruby
#exclusive?()
```

Indicates whether calls use the run-wide exclusive-tool lock.

<a id="method-i-execute"></a>
### `#execute`

```ruby
#execute(input, context: RunContext.new)
```

Validates `input` and invokes the Tool, returning its normalized outcome.

Cancellation, deadline, and cleanup exceptions remain control-flow exceptions.
ToolError and unexpected failures become sanitized error results; unexpected
exception messages are not exposed to the model.

<a id="method-i-input_schema"></a>
### `#input_schema`

```ruby
#input_schema()
```

Normalized JSON input schema declared by the tool class.

<a id="method-i-model"></a>
### `#model`

```ruby
#model()
```

Bound model, when available.

<a id="method-i-run"></a>
### `#run`

```ruby
#run()
```

Bound run, when available.

<a id="method-i-runtime"></a>
### `#runtime`

```ruby
#runtime()
```

Bound runtime, when available.

<a id="method-i-sandbox"></a>
### `#sandbox`

```ruby
#sandbox()
```

Bound sandbox, when available.

<a id="method-i-specification"></a>
### `#specification`

```ruby
#specification()
```

Frozen provider-facing tool specification.

<a id="method-i-tool_name"></a>
### `#tool_name`

```ruby
#tool_name()
```

Model-visible name declared by the tool class.

<a id="method-i-workspace"></a>
### `#workspace`

```ruby
#workspace()
```

Bound workspace, when available.