Tool Calling

Getting Started with LLM APIs in R

R/Pharma 2025

2025-11-03

Recall: How do LLMs work?

Let’s revisit how LLMs work. This is important context for understanding why we need tools.

1. You write some words

2. The LLM writes some more words

3. You use those words

On their own, can LLMs… access the internet? run code? send an email? interact with the world?

Let’s try it

library(ellmer)

chat <- chat("openai/gpt-4.1-nano")

chat$chat("Who are the keynote speakers at R/Pharma 2025?")

My training only includes data up until October 2023, and I do not 
have access to real-time updates or event-specific details beyond that. 

For the most accurate and current information about the keynote 
speakers, I recommend visiting the official R/Pharma 2025 
website or checking their latest event announcements.

Let’s try asking about things the model doesn’t know. This one fails - the model’s training data is old and it doesn’t have real-time event information.

Let’s try it

This one also fails - the model can’t access real-time weather data. No internet connection.

library(ellmer)

chat <- chat("openai/gpt-4.1-nano")

chat$chat("What's the weather like in Minneapolis?")

I'm unable to provide real-time weather updates.
For the most current weather in Minneapolis,
please check a reliable weather service or app like
Weather.com, AccuWeather, or your local weather provider.

Let’s try it

But this one… the model actually gives an answer! It’s wrong (the date is from its training cutoff), but it shows the model will try to answer with what it knows.

library(ellmer)

chat <- chat("openai/gpt-4.1-nano")

chat$chat("What day is it?")

Today is October 27, 2023.

Tools

So how do we solve these problems? Tools! Also called functions or function calling.

a.k.a. functions, tool calling or function calling

• Bring real-time or up-to-date information to the model

• Let the model interact with the world

Tools are extra capabilities that you give to the LLM, like the ability to search the R/Pharma 2025 schedule or check the weather. These capabilities are things that the model can’t do on its own. The goal is to let the model pull in real-time or up-to-date information as needed.

They can also give the model new abilities to take action on behalf of the user.

How does tool calling work?

Let me walk you through exactly how tool calling works step by step. This is the key pattern you need to understand.

The conversation starts with a user sending a message to the chatbot.

In this example, the user asks whether they can go to the pool today - which requires knowing the weather.

The model doesn’t have access to real-time weather data, just like we saw earlier with Minneapolis.

Now imagine we’ve told the LLM that it has access to a tool called get_weather(). Knowing that it needs weather information and doesn’t have access to real-time data, the model decides to use the weather tool.

It sends back a message that includes a tool call - basically instructions to call the get_weather() function with the appropriate location argument. The model uses its training data to figure out the right location format (like a ZIP code).

The programmer takes that tool call message and executes the actual function - in this case, querying a weather API with the location the model specified.

The weather API sends back some data:

• The forecast is mostly sunny
• High of 98ºF
• Low of 78ºF

The programmer sends that data back to the LLM. Note that it’s often in a pretty raw format, like JSON. Not the kind of thing you’d want to read directly unless you’re the kind of person who likes reading computer data formats.

The LLM doesn’t mind JSON though, so it reads the data and generates a response that incorporates the data from the tool call.

The LLM can’t run code by itself!

This is crucial to understand - the LLM doesn’t execute tools. It just asks you to run them.

The LLM also chooses the arguments for the tool. Here it picks the location based on the conversation.

It uses its knowledge to fill in the right values - using information from its training data.

The LLM can also call multiple tools in a single response if it needs to gather different information.

Demo: weather tool

But you’re programmers! You can automate this. Let me show you how to define tools that run automatically.

👩‍💻 _demos/19_tools/19_weather-tool.R

Tools in R

Step 1: Write a (normal) R function

get_weather <- function(zip_code) {
  # use weather API to get weather for that zip
  # ...
}

Step 2: Define the tool

Here’s the pattern for defining tools in ellmer. You provide the function, a description, and argument types.

tool_get_weather <- tool(
  tool_fn,
  description = "How and when to use the tool",
  arguments = list(
    .... = type_string(),
    .... = type_integer(),
    .... = type_enum(
      c("choice1", "choice2"),
      required = FALSE
    )
  )
)

Step 2: Define the tool

Here’s the pattern for defining tools in ellmer. You provide the function, a description, and argument types.

tool_get_weather <- tool(
  get_weather,
  description = 
    "Gets the current weather for a specified zip code",
  arguments = list(
    zip_code = type_string("The zip code.", required = TRUE)
  )
)

Step 3: Register the tool

chat$register_tool(tool_get_weather)

Your Turn 10_quiz-game-2

Now practice - add a tool to the quiz game that plays sounds. This reinforces the pattern we just learned.

1. I’ve given you a function that plays a sound when called (play_sound()).

2. Your job: give the model the ability to play sounds in the Quiz Show game we made earlier.

3. You will need to fill out the tool definition and register the tool.

06:00

Follow up question: why send a string back to the LLM that says the sound was played?

Tools in Shiny

When using tools in Shiny apps, remember these key points - tools can interact with your app’s reactive state.

• Define the tool function inside the server

• You can update reactive values in the tool function!

useful if you want to update a table based on chat input

Learn more

These are the Posit packages for working with AI. We’ve focused on ellmer and shinychat today, but there are others for different use cases.

Learn more

querychat: https://github.com/posit-dev/querychat

• Chat with your data using natural language queries.

ggbot2: https://github.com/tidyverse/ggbot2

• Talk out loud to create and iterate on plots.

Databot: https://positron.posit.co/databot.html

• EDA assistant for Positron.

Posit AI newsletter: https://posit.co/blog/?post_tag=ai-newsletter

Thank you!