Skip to main content
Version: Next

Tool calls

The villager conversation API supports OpenAI-compatible function/tool calls. Tools are sent with the request, and the mod executes requested tools before asking the model for its final response.

Built-in villager tools​

Every villager conversation includes these tools:

ToolPurpose
get_villager_professionReturns the villager's current profession
get_villager_world_timeReturns formatted world time and world ticks
get_villager_happinessReturns the villager's happiness value
get_villager_reputationReturns the villager's reputation with the player
get_villager_experienceReturns villager trading experience
get_villager_ageReturns the villager's age
get_villager_tradesReturns the villager's current trades

These values are no longer copied into every system prompt. The model should call the relevant tool when it needs current game state.

Defining a tool​

Implement Tool and provide a stable name, a description, a JSON Schema object for parameters, and an execution method:

public final class GetWeatherTool implements Tool {
@Override
public String getName() {
return "get_weather";
}

@Override
public String getDescription() {
return "Get the current weather near the villager.";
}

@Override
public JsonObject getParameters() {
var schema = new JsonObject();
schema.addProperty("type", "object");
schema.add("properties", new JsonObject());
schema.add("required", new JsonArray());
return schema;
}

@Override
public String execute(JsonObject arguments) {
if (arguments == null) {
throw new IllegalArgumentException("Tool arguments cannot be null");
}
return "clear";
}
}

Tool results are strings. Throw an IllegalArgumentException for invalid arguments instead of returning a misleading success value.

Registering a tool​

Tools are registered per villager request in VillagerManager.createVillagerTools. Add a tool to that list when it needs access to the current villager or player:

tools.add(new GetWeatherTool(villager, player));

The manager permits up to five tool-call rounds per request. Unknown tool names are returned to the model as an error result, and the tool-call conversation messages are retained only for the current request.

Adding prompt context​

Use VillagerSystemPromptHook for context that should be injected into the temporary system prompt rather than queried by the model:

Main.VILLAGER_MANAGER.addSystemPromptHook((villager, player, memory) ->
Optional.of("The player is currently inside the village."));

Return Optional.empty() when there is no context to add. Blank values are ignored. Prompt hooks should not be used for rapidly changing values that the model can retrieve through a tool.