# `Sycophant.Tool`

Defines a tool that can be provided to an LLM.

Tools describe callable functions that the LLM can invoke during generation.
Parameters are defined as a Zoi schema, which wire protocol adapters convert
to provider-specific JSON Schema.

## Auto-execution

When `function` is set, Sycophant automatically executes the tool when the
LLM returns a tool call, feeds the result back, and continues the loop
(up to `:max_steps` iterations). When `function` is `nil`, tool calls are
returned in `response.tool_calls` for manual handling.

## Examples

    # Zoi-defined tool (receives atom keys after validation)
    weather_tool = %Sycophant.Tool{
      name: "get_weather",
      description: "Get current weather for a city",
      parameters: Zoi.object(%{city: Zoi.string()}),
      function: fn %{city: city} -> "72F and sunny in #{city}" end
    }

    # JSON Schema-defined tool (receives string keys)
    search_tool = %Sycophant.Tool{
      name: "search",
      description: "Search the web",
      parameters: %{
        "type" => "object",
        "properties" => %{"query" => %{"type" => "string"}},
        "required" => ["query"]
      },
      function: fn %{"query" => q} -> "Results for #{q}" end
    }

    {:ok, response} = Sycophant.generate_text("openai:gpt-4o-mini", messages,
      tools: [weather_tool, search_tool]
    )

# `t`

```elixir
@type t() :: %Sycophant.Tool{
  description: String.t(),
  function: (map() -> String.t()) | nil,
  name: String.t(),
  parameters: Zoi.schema() | map(),
  resolved_schema: Sycophant.Schema.NormalizedSchema.t() | nil,
  schema_source: :zoi | :json_schema | nil,
  strict: boolean()
}
```

# `from_map`

```elixir
@spec from_map(map()) :: t()
```

Reconstructs a Tool struct from a serialized map.

---

*Consult [api-reference.md](api-reference.md) for complete listing*