Function: gptel-make-tool

gptel-make-tool is a natively compiled function defined in gptel-request.el.

Signature

(gptel-make-tool &rest SLOTS)

Documentation

Make a gptel tool for LLM use.

The following keyword arguments are available, of which the first four SLOTS are required.

NAME: The name of the tool, recommended to be in Javascript style snake_case.

FUNCTION: The function itself (lambda or symbol) that runs the tool.

DESCRIPTION: A verbose description of what the tool does, how to call it and what it returns.

ARGS: A list of plists specifying the arguments, or nil for a function that takes no arguments. Each plist in ARGS requires the following keys:
- argument :name and :description, as strings.
- argument :type, as a symbol. Allowed types are those understood by the JSON
  schema: string, number, integer, boolean, array, object or null

The following plist keys are conditional/optional:
- :optional, boolean indicating if argument is optional
- :enum for enumerated types, whose value is a vector of strings representing
  allowed values. Note that :type is still required for enums.
- :items, if the :type is array. Its value must be a plist including at least
  the item's :type.
- :properties, if the type is object. Its value must be a plist that can be
  serialized into a JSON object specification by json-serialize.

ASYNC: boolean indicating if the elisp function is asynchronous. If ASYNC is t, the function should take a callback as its first argument, along with the arguments specified in ARGS, and run the callback with the tool call result when it's ready. The callback itself is an implementation detail and must not be included in ARGS.

The following keys are optional

CATEGORY: A string indicating a category for the tool. This is used only for grouping in gptel's UI. Defaults to "misc".

CONFIRM: Whether the tool call should wait for the user to run it. If true, the user will be prompted with the proposed tool call, which can be examined, accepted, deferred or canceled. It can also be a function that receives the same arguments as FUNCTION and returns true if the user should be prompted.

INCLUDE: Whether the tool results should be included as part of the LLM output. This is useful for logging and as context for subsequent requests in the same buffer. This is primarily useful in chat buffers. Possible values:

- t (default): Include both the call parameters and the result.
- symbol call: Include only the call parameters, not the result.
- nil: Exclude the tool call from the buffer entirely.

Here is an example definition:

  (gptel-make-tool
   :function (lambda (location unit)
                (url-retrieve-synchronously "api.weather.com/..."
                                            location unit))
   :name "get_weather"
   :description "Get the current weather in a given location"
   :args (list '(:name "location"
                 :type string
                 :description "The city and state, e.g. San Francisco, CA")
               '(:name "unit"
                 :type string
                 :enum ["celsius" "farenheit"]
                 :description
                 "The unit of temperature, either \\='celsius\\=' or \\='fahrenheit\\='"
                 :optional t)))

If the tool is asynchronous, the function is modified to take a callback as its first argument, which it runs with the result:

   (lambda (callback location unit)
     (url-retrieve "api.weather.com/..."
                   (lambda (_)
                     (let ((result (parse-this-buffer)))
                       (funcall callback result)))))

Source Code

;; Defined in /nix/store/q3r7g81pvghw7a523kjk2k2zih3pfk8z-emacs-packages-deps/share/emacs/site-lisp/elpa/gptel-20261002.545/gptel-request.el
(defun gptel-make-tool (&rest slots)
  "Make a gptel tool for LLM use.

The following keyword arguments are available, of which the first
four SLOTS are required.

NAME: The name of the tool, recommended to be in Javascript style snake_case.

FUNCTION: The function itself (lambda or symbol) that runs the tool.

DESCRIPTION: A verbose description of what the tool does, how to
call it and what it returns.

ARGS: A list of plists specifying the arguments, or nil for a function that
takes no arguments.  Each plist in ARGS requires the following keys:
- argument :name and :description, as strings.
- argument :type, as a symbol.  Allowed types are those understood by the JSON
  schema: string, number, integer, boolean, array, object or null

The following plist keys are conditional/optional:
- :optional, boolean indicating if argument is optional
- :enum for enumerated types, whose value is a vector of strings representing
  allowed values.  Note that :type is still required for enums.
- :items, if the :type is array.  Its value must be a plist including at least
  the item's :type.
- :properties, if the type is object.  Its value must be a plist that can be
  serialized into a JSON object specification by `json-serialize'.

ASYNC: boolean indicating if the elisp function is asynchronous.
If ASYNC is t, the function should take a callback as its first
argument, along with the arguments specified in ARGS, and run the
callback with the tool call result when it's ready.  The callback
itself is an implementation detail and must not be included in
ARGS.

The following keys are optional

CATEGORY: A string indicating a category for the tool.  This is
used only for grouping in gptel's UI.  Defaults to \"misc\".

CONFIRM: Whether the tool call should wait for the user to run it.  If
true, the user will be prompted with the proposed tool call, which can
be examined, accepted, deferred or canceled.  It can also be a function
that receives the same arguments as FUNCTION and returns true if the
user should be prompted.

INCLUDE: Whether the tool results should be included as part of
the LLM output.  This is useful for logging and as context for
subsequent requests in the same buffer.  This is primarily useful
in chat buffers.  Possible values:

- t (default): Include both the call parameters and the result.
- symbol `call': Include only the call parameters, not the result.
- nil: Exclude the tool call from the buffer entirely.

Here is an example definition:

  (gptel-make-tool
   :function (lambda (location unit)
                (url-retrieve-synchronously \"api.weather.com/...\"
                                            location unit))
   :name \"get_weather\"
   :description \"Get the current weather in a given location\"
   :args (list \\='(:name \"location\"
                 :type string
                 :description \"The city and state, e.g. San Francisco, CA\")
               \\='(:name \"unit\"
                 :type string
                 :enum [\"celsius\" \"farenheit\"]
                 :description
                 \"The unit of temperature, either \\='celsius\\=' or \\='fahrenheit\\='\"
                 :optional t)))

If the tool is asynchronous, the function is modified to take a
callback as its first argument, which it runs with the result:

   (lambda (callback location unit)
     (url-retrieve \"api.weather.com/...\"
                   (lambda (_)
                     (let ((result (parse-this-buffer)))
                       (funcall callback result)))))"
  (let* ((tool (apply #'gptel--make-tool slots))
         (category (or (gptel-tool-category tool) "misc")))
    (setf (alist-get
           (gptel-tool-name tool)
           (alist-get category gptel--known-tools nil nil #'equal)
           nil nil #'equal)
          tool)))