class LittleGhost::Tool

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 for the complete path from model-selected input to application context, sandbox delegation, concurrency, and code mode.

Attributes