Copilot.DefineTool (Copilot SDK v2.3.0)

Copy Markdown

Helper for defining tools to expose to the Copilot CLI.

Provides a convenient function for creating Copilot.Types.Tool structs with proper JSON schema parameters.

Examples

Simple tool (no parameters)

tool = Copilot.DefineTool.define("get_time",
  description: "Returns the current UTC time",
  handler: fn _args, _inv -> DateTime.utc_now() |> DateTime.to_iso8601() end
)

Tool with JSON schema parameters

tool = Copilot.DefineTool.define("lookup_fact",
  description: "Returns a fun fact about a given topic.",
  parameters: %{
    "type" => "object",
    "properties" => %{
      "topic" => %{
        "type" => "string",
        "description" => "Topic to look up (e.g. 'javascript', 'node')"
      }
    },
    "required" => ["topic"]
  },
  handler: fn %{"topic" => topic}, _invocation ->
    facts = %{
      "javascript" => "JavaScript was created in 10 days by Brendan Eich.",
      "node" => "Node.js uses the V8 engine."
    }
    Map.get(facts, String.downcase(topic), "No fact stored for #{topic}.")
  end
)

Using the macro for cleaner syntax

use Copilot.DefineTool

deftool :weather, "Get weather for a city",
  parameters: %{
    "type" => "object",
    "properties" => %{
      "city" => %{"type" => "string", "description" => "City name"}
    },
    "required" => ["city"]
  } do
  fn %{"city" => city}, _inv ->
    "The weather in #{city} is sunny, 72F."
  end
end

Summary

Functions

define(opts)

Convenience for defining a tool from a keyword list that includes :name.

define(name, opts)

Define a tool with the given name and options.

deftool(name, description, opts, list)

Macro for defining a tool inline.

Functions

define(opts)

@spec define(keyword()) :: Copilot.Types.Tool.t()

Convenience for defining a tool from a keyword list that includes :name.

define(name, opts)

@spec define(
  String.t(),
  keyword()
) :: Copilot.Types.Tool.t()

Define a tool with the given name and options.

Options

  • :description - Description shown to the LLM (required).
  • :parameters - JSON schema map for tool parameters (optional).
  • :handler - A 2-arity function (args, invocation) -> result. The result can be:

deftool(name, description, opts, list)

(macro)

Macro for defining a tool inline.

Example

use Copilot.DefineTool

deftool :echo, "Echoes back the input",
  parameters: %{
    "type" => "object",
    "properties" => %{
      "text" => %{"type" => "string"}
    },
    "required" => ["text"]
  } do
  fn %{"text" => text}, _inv -> text end
end

Returns a Copilot.Types.Tool struct bound to a variable with the tool name.