1# Tool Use — Java
2 
3For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md).
4 
5## Tool Use (Beta)
6 
7The Java SDK supports beta tool use with annotated classes. Tool classes implement `Supplier<String>` for automatic execution via `BetaToolRunner`.
8 
9### Tool Runner (automatic loop)
10 
11```java
12import com.anthropic.models.beta.messages.MessageCreateParams;
13import com.anthropic.models.beta.messages.BetaMessage;
14import com.anthropic.helpers.BetaToolRunner;
15import com.fasterxml.jackson.annotation.JsonClassDescription;
16import com.fasterxml.jackson.annotation.JsonPropertyDescription;
17import java.util.function.Supplier;
18 
19@JsonClassDescription("Get the weather in a given location")
20static class GetWeather implements Supplier<String> {
21    @JsonPropertyDescription("The city and state, e.g. San Francisco, CA")
22    public String location;
23 
24    @Override
25    public String get() {
26        return "The weather in " + location + " is sunny and 72°F";
27    }
28}
29 
30BetaToolRunner toolRunner = client.beta().messages().toolRunner(
31    MessageCreateParams.builder()
32        .model("claude-opus-4-8")
33        .maxTokens(16000L)
34        .putAdditionalHeader("anthropic-beta", "structured-outputs-2025-11-13")
35        .addTool(GetWeather.class)
36        .addUserMessage("What's the weather in San Francisco?")
37        .build());
38 
39for (BetaMessage message : toolRunner) {
40    System.out.println(message);
41}
42```
43 
44### Memory Tool
45 
46The Java SDK provides `BetaMemoryToolHandler` for implementing the memory tool backend. You supply a handler that manages file storage, and the `BetaToolRunner` handles memory tool calls automatically.
47 
48```java
49import com.anthropic.helpers.BetaMemoryToolHandler;
50import com.anthropic.helpers.BetaToolRunner;
51import com.anthropic.models.beta.messages.BetaMemoryTool20250818;
52import com.anthropic.models.beta.messages.BetaMessage;
53import com.anthropic.models.beta.messages.MessageCreateParams;
54import com.anthropic.models.beta.messages.ToolRunnerCreateParams;
55 
56// Implement BetaMemoryToolHandler with your storage backend (e.g., filesystem)
57BetaMemoryToolHandler memoryHandler = new FileSystemMemoryToolHandler(sandboxRoot);
58 
59MessageCreateParams createParams = MessageCreateParams.builder()
60    .model("claude-opus-4-8")
61    .maxTokens(4096L)
62    .addTool(BetaMemoryTool20250818.builder().build())
63    .addUserMessage("Remember that my favorite color is blue")
64    .build();
65 
66BetaToolRunner toolRunner = client.beta().messages().toolRunner(
67    ToolRunnerCreateParams.builder()
68        .betaMemoryToolHandler(memoryHandler)
69        .initialMessageParams(createParams)
70        .build());
71 
72for (BetaMessage message : toolRunner) {
73    System.out.println(message);
74}
75```
76 
77See the [shared memory tool concepts](../../shared/tool-use-concepts.md) for more details on the memory tool.
78 
79### Non-Beta Tool Declaration (manual JSON schema)
80 
81`Tool.InputSchema.Properties` is a freeform `Map<String, JsonValue>` wrapper — build property schemas via `putAdditionalProperty`. `type: "object"` is the default. The builder has a direct `.addTool(Tool)` overload that wraps in `ToolUnion` automatically.
82 
83```java
84import com.anthropic.core.JsonValue;
85import com.anthropic.models.messages.Tool;
86 
87Tool tool = Tool.builder()
88    .name("get_weather")
89    .description("Get the current weather in a given location")
90    .inputSchema(Tool.InputSchema.builder()
91        .properties(Tool.InputSchema.Properties.builder()
92            .putAdditionalProperty("location", JsonValue.from(Map.of("type", "string")))
93            .build())
94        .required(List.of("location"))
95        .build())
96    .build();
97 
98MessageCreateParams params = MessageCreateParams.builder()
99    .model(Model.CLAUDE_SONNET_4_6)
100    .maxTokens(16000L)
101    .addTool(tool)
102    .addUserMessage("Weather in Paris?")
103    .build();
104```
105 
106For manual tool loops, handle `tool_use` blocks in the response, send `tool_result` back, loop until `stop_reason` is `"end_turn"`. See [shared tool use concepts](../../shared/tool-use-concepts.md).
107 
108### Building `MessageParam` with Content Blocks (Tool Result Round-Trip)
109 
110`MessageParam.Content` is an inner union class (string | list). Use the builder's `.contentOfBlockParams(List<ContentBlockParam>)` alias — there is NO separate `MessageParamContent` class with a static `ofBlockParams`:
111 
112```java
113import com.anthropic.models.messages.MessageParam;
114import com.anthropic.models.messages.ContentBlockParam;
115import com.anthropic.models.messages.ToolResultBlockParam;
116 
117List<ContentBlockParam> results = List.of(
118    ContentBlockParam.ofToolResult(ToolResultBlockParam.builder()
119        .toolUseId(toolUseBlock.id())
120        .content(yourResultString)
121        .build())
122);
123 
124MessageParam toolResultMsg = MessageParam.builder()
125    .role(MessageParam.Role.USER)
126    .contentOfBlockParams(results)   // builder alias for Content.ofBlockParams(...)
127    .build();
128```
129 
130---
131 
132## Structured Output
133 
134The class-based overload auto-derives the JSON schema from your POJO and gives you a typed `.text()` return — no manual schema, no manual parsing.
135 
136```java
137import com.anthropic.models.messages.StructuredMessageCreateParams;
138 
139record Book(String title, String author) {}
140record BookList(List<Book> books) {}
141 
142StructuredMessageCreateParams<BookList> params = MessageCreateParams.builder()
143    .model(Model.CLAUDE_SONNET_4_6)
144    .maxTokens(16000L)
145    .outputConfig(BookList.class)  // returns a typed builder
146    .addUserMessage("List 3 classic novels")
147    .build();
148 
149client.messages().create(params).content().stream()
150    .flatMap(cb -> cb.text().stream())
151    .forEach(typed -> {
152        // typed.text() returns BookList, not String
153        for (Book b : typed.text().books()) System.out.println(b.title());
154    });
155```
156 
157Supports Jackson annotations: `@JsonPropertyDescription`, `@JsonIgnore`, `@ArraySchema(minItems=...)`. Manual schema path: `OutputConfig.builder().format(JsonOutputFormat.builder().schema(...).build())`.
158 
159---
160 
161## Anthropic-Defined Tools
162 
163Version-suffixed types; `name`/`type` auto-set by builder. Direct `.addTool()` overloads exist for most tool types; where one is missing (newer or less-common tools — see the advisor note below), wrap via the union type's static factory: `.addTool(BetaToolUnion.of<ToolName>(builder…build()))`. Web search and code execution are server-executed; bash and text editor are client-executed (you handle the `tool_use` locally — see `shared/tool-use-concepts.md`).
164 
165```java
166import com.anthropic.models.messages.WebSearchTool20260209;
167import com.anthropic.models.messages.ToolBash20250124;
168import com.anthropic.models.messages.ToolTextEditor20250728;
169import com.anthropic.models.messages.CodeExecutionTool20260120;
170 
171.addTool(WebSearchTool20260209.builder()
172    .maxUses(5L)                              // optional
173    .allowedDomains(List.of("example.com"))   // optional
174    .build())
175.addTool(ToolBash20250124.builder().build())
176.addTool(ToolTextEditor20250728.builder().build())
177.addTool(CodeExecutionTool20260120.builder().build())
178```
179 
180Also available: `WebFetchTool20260209`, `MemoryTool20250818`, `ToolSearchToolBm25_20251119`. For the advisor tool, use `BetaAdvisorTool20260301` in the beta namespace with `.addBeta("advisor-tool-2026-03-01")` (server-side; advisor model ≥ executor model). There is no direct `.addTool(BetaAdvisorTool20260301)` overload on the beta builder — wrap it via the `BetaToolUnion` static factory for the advisor type; if `javac` rejects the specific factory method name, `javap com.anthropic.models.beta.messages.BetaToolUnion | grep -i advisor` shows the exact one.
181 
182### Beta namespace (MCP, compaction)
183 
184For beta-only features use `com.anthropic.models.beta.messages.*` — class names have a `Beta` prefix AND live in the beta package. The beta `MessageCreateParams.Builder` has direct `.addTool(BetaToolBash20250124)` overloads AND `.addMcpServer()`:
185 
186```java
187import com.anthropic.models.beta.messages.MessageCreateParams;
188import com.anthropic.models.beta.messages.BetaToolBash20250124;
189import com.anthropic.models.beta.messages.BetaCodeExecutionTool20260120;
190import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
191 
192MessageCreateParams params = MessageCreateParams.builder()
193    .model(Model.CLAUDE_OPUS_4_8)
194    .maxTokens(16000L)
195    .addBeta("mcp-client-2025-11-20")
196    .addTool(BetaToolBash20250124.builder().build())
197    .addTool(BetaCodeExecutionTool20260120.builder().build())
198    .addMcpServer(BetaRequestMcpServerUrlDefinition.builder()
199        .name("my-server")
200        .url("https://example.com/mcp")
201        .build())
202    .addUserMessage("...")
203    .build();
204 
205client.beta().messages().create(params);
206```
207 
208`BetaTool*` types are NOT interchangeable with non-beta `Tool*` — pick one namespace per request.
209 
210**Reading server-tool blocks in the response:** `ServerToolUseBlock` has `.id()`, `.name()` (enum), and `._input()` returning raw `JsonValue` — there is NO typed `.input()`. For code execution results, unwrap two levels:
211 
212```java
213for (ContentBlock block : response.content()) {
214    block.serverToolUse().ifPresent(stu -> {
215        System.out.println("tool: " + stu.name() + " input: " + stu._input());
216    });
217    block.codeExecutionToolResult().ifPresent(r -> {
218        r.content().resultBlock().ifPresent(result -> {
219            System.out.println("stdout: " + result.stdout());
220            System.out.println("stderr: " + result.stderr());
221            System.out.println("exit: " + result.returnCode());
222        });
223    });
224}
225```
226 
227---
228 
229