Define a tool

A tool is one capability the model can use: declared directly in the request's tool array (exposure = "direct"), callable from R code as peter$<namespace>$<name>() ("r", one signature line in the prompt), found through peter$search() ("deferred") or callable only by gptr code ("hidden"). Give execute (function(input, ctx), the direct-tool form), fun (an R function whose formals match the schema properties, the member form), or both. A direct tool with only fun gets a generated execute that prints the value within output_tokens; an r member with only execute gets a generated fun.

Usage

gptr_tool(
  name,
  description,
  parameters = NULL,
  execute = NULL,
  fun = NULL,
  exposure = c("direct", "r", "deferred", "hidden"),
  namespace = NULL,
  execution = c("sequential", "concurrent"),
  risk = NULL,
  snippet = NULL,
  guidelines = NULL,
  signature = NULL,
  output_tokens = NULL,
  record = TRUE,
  available = NULL,
  annotations = list()
)

Arguments

name

Tool name, ^[a-zA-Z0-9_-]{1,64}$.

description

Model-facing description; direct tools stay under 400 estimated tokens.

parameters

A JSON Schema list with type = "object", a function(ctx) evaluated once when a session freezes its prompt, or NULL to derive the schema from fun's formals.

execute

function(input, ctx) returning a gptr_tool_result(), text, a list or NULL.

fun

The R-callable form of the tool.

exposure

One of "direct", "r", "deferred", "hidden".

namespace

Namespace of an r member (plugins must set it to their package name).

execution

"sequential" (tools that evaluate R or write files) or "concurrent".

risk

function(input, ctx) returning a risk level, or NULL.

snippet

One line shown in the prompt's tool list (direct tools).

guidelines

Bullet lines added to the prompt's rules (direct tools).

signature

Catalog line for r members; NULL derives it from the schema.

output_tokens

Budget for printed results; NULL uses the gptr defaults.

record

Keep calls of this member in recorded code.

available

function(ctx) deciding at freeze whether a direct tool is offered.

annotations

Named list: read_only, destructive, idempotent, open_world, requires_user (MCP readOnlyHint-style names are mapped).

Value

A spec of class c("gptr_tool", "gptr_spec").

See also

gptr_register, gptr_check; vignette("extending-gptr", package = "gptr") for complete tool and policy examples.

Examples

gptr_tool("nrow_of", "Number of rows of a data frame in the session",
          fun = function(name) nrow(get(name, envir = globalenv())),
          exposure = "r", namespace = "demo")
#> <gptr_tool nrow_of>
#>   description: Number of rows of a data frame in the session
#>   parameters: <list of 3>
#>   fun: <fn>
#>   exposure: r
#>   namespace: demo
#>   execution: sequential
#>   record: TRUE
#>   annotations: <list of 0>
#>   api_version: 1.0