1/**
2 * The `AnthropicTool` module defines Anthropic provider tools and the schemas
3 * for their inputs and results. It covers Anthropic-owned tools such as Bash,
4 * Code Execution, Computer Use, Memory, Text Editor, Web Search, Web Fetch, and
5 * Tool Search, which can be attached to Anthropic-backed Effect AI language
6 * model requests.
7 *
8 * @stability unstable
9 * @since 4.0.0
10 */
11import * as Tool from "effect/ai/Tool"
12import * as Schema from "effect/Schema"
13import * as Generated from "./Generated.ts"
14
15/**
16 * Union of all Anthropic provider-defined tool definitions exported by this module.
17 *
18 * **When to use**
19 *
20 * Use when a helper, collection, or option accepts any Anthropic
21 * provider-defined tool value created by this module.
22 *
23 * **Details**
24 *
25 * The union is built from the return types of the exported constructors,
26 * including Bash, Code Execution, Computer Use, Memory, Text Editor, Tool
27 * Search, Web Fetch, and Web Search tool versions.
28 *
29 * @stability unstable
30 * @category models
31 * @since 4.0.0
32 */
33export type AnthropicTool =
34 | ReturnType<typeof Bash_20241022>
35 | ReturnType<typeof Bash_20250124>
36 | ReturnType<typeof CodeExecution_20250522>
37 | ReturnType<typeof CodeExecution_20250825>
38 | ReturnType<typeof ComputerUse_20241022>
39 | ReturnType<typeof ComputerUse_20250124>
40 | ReturnType<typeof ComputerUse_20251124>
41 | ReturnType<typeof Memory_20250818>
42 | ReturnType<typeof TextEditor_20241022>
43 | ReturnType<typeof TextEditor_20250124>
44 | ReturnType<typeof TextEditor_20250429>
45 | ReturnType<typeof TextEditor_20250728>
46 | ReturnType<typeof ToolSearchRegex_20251119>
47 | ReturnType<typeof ToolSearchBM25_20251119>
48 | ReturnType<typeof WebFetch_20250910>
49 | ReturnType<typeof WebSearch_20250305>
50
51// =============================================================================
52// Bash
53// =============================================================================
54
55/**
56 * Defines the Anthropic Bash tool (2024-10-22 version).
57 *
58 * **When to use**
59 *
60 * Use when you want the model to execute bash commands with the 2024-10-22
61 * Anthropic computer-use beta.
62 *
63 * **Details**
64 *
65 * Allows the model to execute bash commands in a sandboxed environment.
66 * Requires the "computer-use-2024-10-22" beta header.
67 *
68 * @see {@link Bash_20250124} for the newer 2025-01-24 version of the bash tool
69 *
70 * @stability unstable
71 * @category tools
72 * @since 4.0.0
73 */
74export const Bash_20241022 = Tool.providerDefined({
75 id: "anthropic.bash_20241022",
76 customName: "AnthropicBash",
77 providerName: "bash",
78 requiresHandler: true,
79 success: Schema.String,
80 parameters: Schema.Struct({
81 command: Schema.String,
82 restart: Schema.optionalKey(Schema.Boolean)
83 })
84})
85
86/**
87 * Defines the Anthropic Bash tool (2025-01-24 version).
88 *
89 * **When to use**
90 *
91 * Use when you want the model to execute bash commands with the 2025-01-24
92 * Anthropic computer-use beta.
93 *
94 * **Details**
95 *
96 * Allows the model to execute bash commands in a sandboxed environment.
97 * Requires the "computer-use-2025-01-24" beta header.
98 *
99 * @see {@link Bash_20241022} for the older 2024-10-22 version of the bash tool
100 *
101 * @stability unstable
102 * @category tools
103 * @since 4.0.0
104 */
105export const Bash_20250124 = Tool.providerDefined({
106 id: "anthropic.bash_20250124",
107 customName: "AnthropicBash",
108 providerName: "bash",
109 requiresHandler: true,
110 success: Schema.String,
111 parameters: Schema.Struct({
112 command: Schema.String,
113 restart: Schema.optionalKey(Schema.Boolean)
114 })
115})
116
117// =============================================================================
118// Code Execution
119// =============================================================================
120
121// -----------------------------------------------------------------------------
122// Code Execution 20250522 Parameters
123// -----------------------------------------------------------------------------
124
125/**
126 * Schema for a code execution request that asks Anthropic to run source code as a programmatic tool call.
127 *
128 * **When to use**
129 *
130 * Use when constructing or validating a programmatic tool call for the Anthropic
131 * Code Execution tool.
132 *
133 * @see {@link CodeExecution_20250522} for the parent tool definition
134 *
135 * @stability unstable
136 * @category schemas
137 * @since 4.0.0
138 */
139export const CodeExecutionProgrammaticToolCall = Schema.Struct({
140 type: Schema.Literal("programmatic-tool-call"),
141 /**
142 * The code to execute.
143 */
144 code: Schema.String
145})
146/**
147 * Input payload for a programmatic code execution tool call, including the source code to execute.
148 *
149 * @stability unstable
150 * @category models
151 * @since 4.0.0
152 */
153export type CodeExecutionProgrammaticToolCall = typeof CodeExecutionProgrammaticToolCall.Type
154
155/**
156 * Schema for the `bash_code_execution` input variant of Anthropic Code Execution.
157 *
158 * **When to use**
159 *
160 * Use when validating or constructing a bash command request for
161 * `CodeExecution_20250522`.
162 *
163 * **Details**
164 *
165 * The schema requires `type` to be `"bash_code_execution"` and `command` to
166 * contain the bash command sent to Anthropic.
167 *
168 * @see {@link CodeExecution_20250522} for the provider-defined tool that consumes this input variant
169 *
170 * @stability unstable
171 * @category schemas
172 * @since 4.0.0
173 */
174export const CodeExecutionBashCommand = Schema.Struct({
175 type: Schema.Literal("bash_code_execution"),
176 /**
177 * The bash command to execute.
178 */
179 command: Schema.String
180})
181/**
182 * Input payload for a bash command routed through the Anthropic code execution tool.
183 *
184 * **When to use**
185 *
186 * Use when representing a provider-executed bash command request for the
187 * 2025-05-22 code execution tool.
188 *
189 * **Details**
190 *
191 * The payload uses `type: "bash_code_execution"` to distinguish bash execution
192 * from programmatic code and text editor operations, and `command` contains the
193 * bash command to run.
194 *
195 * @see {@link CodeExecutionProgrammaticToolCall} for programmatic code execution input
196 * @see {@link CodeExecutionTextEditorView} for viewing files through text editor code execution
197 * @see {@link CodeExecutionTextEditorCreate} for creating files through text editor code execution
198 * @see {@link CodeExecutionTextEditorStrReplace} for replacing text through text editor code execution
199 * @see {@link CodeExecution_20250522} for the provider-defined tool that consumes this payload
200 *
201 * @stability unstable
202 * @category models
203 * @since 4.0.0
204 */
205export type CodeExecutionBashCommand = typeof CodeExecutionBashCommand.Type
206
207/**
208 * Schema for a code execution text editor request that views a file by path.
209 *
210 * **When to use**
211 *
212 * Use when you need the schema for provider-bound code-execution view requests
213 * before distinguishing them from create or replace text-editor commands.
214 *
215 * **Details**
216 *
217 * The encoded payload uses `type: "text_editor_code_execution"`,
218 * `command: "view"`, and a `path` string.
219 *
220 * @see {@link CodeExecutionTextEditorCreate} for the command that creates a file
221 * @see {@link CodeExecutionTextEditorStrReplace} for the command that replaces text in a file
222 *
223 * @stability unstable
224 * @category schemas
225 * @since 4.0.0
226 */
227export const CodeExecutionTextEditorView = Schema.Struct({
228 type: Schema.Literal("text_editor_code_execution"),
229 command: Schema.Literal("view"),
230 /**
231 * Path to the file to view.
232 */
233 path: Schema.String
234})
235/**
236 * Input payload for the `view` command of Anthropic's text editor code execution tool.
237 *
238 * **When to use**
239 *
240 * Use when working at the Anthropic protocol boundary and the code-execution
241 * view request must be distinguished from standalone text-editor view requests.
242 *
243 * **Details**
244 *
245 * The payload is discriminated by `type: "text_editor_code_execution"` and
246 * `command: "view"`. The `path` field identifies the file to view.
247 *
248 * **Gotchas**
249 *
250 * This code execution view payload does not include `view_range`; line ranges
251 * are part of the standalone text editor view payload, not this code execution
252 * payload.
253 *
254 * @see {@link CodeExecution_20250522} for the provider-defined code execution tool that includes this payload
255 * @see {@link TextEditorViewCommand} for the standalone text editor view payload
256 *
257 * @stability unstable
258 * @category models
259 * @since 4.0.0
260 */
261export type CodeExecutionTextEditorView = typeof CodeExecutionTextEditorView.Type
262
263/**
264 * Schema for a text editor code execution request that creates a file at a path.
265 *
266 * **When to use**
267 *
268 * Use when validating or constructing an Anthropic `text_editor_code_execution`
269 * tool call that should create a file.
270 *
271 * **Details**
272 *
273 * The request is discriminated by `type: "text_editor_code_execution"` and
274 * `command: "create"`. It requires `path` and accepts optional `file_text`; the
275 * schema allows `file_text` to be omitted, `null`, or a string.
276 *
277 * @see {@link CodeExecution_20250522} for the provider-defined tool that consumes this request
278 * @see {@link CodeExecutionTextEditorView} for the matching view request
279 * @see {@link CodeExecutionTextEditorStrReplace} for the matching replace request
280 *
281 * @stability unstable
282 * @category schemas
283 * @since 4.0.0
284 */
285export const CodeExecutionTextEditorCreate = Schema.Struct({
286 type: Schema.Literal("text_editor_code_execution"),
287 command: Schema.Literal("create"),
288 /**
289 * Path where the file should be created.
290 */
291 path: Schema.String,
292 /**
293 * The content to write to the new file.
294 */
295 file_text: Schema.optional(Schema.NullOr(Schema.String))
296})
297/**
298 * Input payload for creating a file through the text editor code execution tool, optionally including initial file text.
299 *
300 * @stability unstable
301 * @category models
302 * @since 4.0.0
303 */
304export type CodeExecutionTextEditorCreate = typeof CodeExecutionTextEditorCreate.Type
305
306/**
307 * Schema for a code execution text editor request that replaces one exact string in a file.
308 *
309 * **When to use**
310 *
311 * Use when validating or constructing the `str_replace` text editor operation
312 * for the 2025-05-22 Anthropic code execution tool.
313 *
314 * **Gotchas**
315 *
316 * The `old_str` must match the file contents exactly, including whitespace and
317 * indentation, and must identify a single occurrence.
318 *
319 * @see {@link CodeExecutionTextEditorView} for reading file contents before choosing the replacement text
320 * @see {@link CodeExecution_20250522} for the provider-defined tool that consumes this payload
321 *
322 * @stability unstable
323 * @category schemas
324 * @since 4.0.0
325 */
326export const CodeExecutionTextEditorStrReplace = Schema.Struct({
327 type: Schema.Literal("text_editor_code_execution"),
328 command: Schema.Literal("str_replace"),
329 /**
330 * Path to the file to modify.
331 */
332 path: Schema.String,
333 /**
334 * The text to replace.
335 */
336 old_str: Schema.String,
337 /**
338 * The replacement text.
339 */
340 new_str: Schema.String
341})
342/**
343 * Input payload for replacing text in a file through the text editor code execution tool.
344 *
345 * @stability unstable
346 * @category models
347 * @since 4.0.0
348 */
349export type CodeExecutionTextEditorStrReplace = typeof CodeExecutionTextEditorStrReplace.Type
350
351const CodeExecution_20250522_Parameters = Schema.Union([
352 CodeExecutionProgrammaticToolCall,
353 CodeExecutionBashCommand,
354 CodeExecutionTextEditorView,
355 CodeExecutionTextEditorCreate,
356 CodeExecutionTextEditorStrReplace
357])
358
359// -----------------------------------------------------------------------------
360// Code Execution 20250825 Parameters
361// -----------------------------------------------------------------------------
362
363/**
364 * Schema for the 2025-08-25 code execution tool input, containing the code to execute.
365 *
366 * **When to use**
367 *
368 * Use when you need the schema for code-execution input at the Anthropic
369 * protocol boundary before sending source code to the 2025-08-25 tool.
370 *
371 * @see {@link CodeExecution_20250825} for the provider-defined tool that consumes this schema
372 *
373 * @stability unstable
374 * @category schemas
375 * @since 4.0.0
376 */
377export const CodeExecution_20250825_Parameters = Schema.Struct({
378 /**
379 * The code to execute.
380 */
381 code: Schema.String
382})
383/**
384 * Input payload for the 2025-08-25 Anthropic code execution tool.
385 *
386 * **When to use**
387 *
388 * Use when exposing the 2025-08-25 code-execution payload separately from the
389 * provider tool definition, such as at a transport or persistence boundary.
390 *
391 * **Details**
392 *
393 * The payload has a single `code` field containing the source code string to
394 * execute.
395 *
396 * @see {@link CodeExecution_20250825} for the provider-defined tool that consumes this payload
397 *
398 * @stability unstable
399 * @category models
400 * @since 4.0.0
401 */
402export type CodeExecution_20250825_Parameters = typeof CodeExecution_20250825_Parameters.Type
403
404// -----------------------------------------------------------------------------
405// Code Execution Tool Definitions
406// -----------------------------------------------------------------------------
407
408/**
409 * Defines the Anthropic Code Execution tool (2025-05-22 version).
410 *
411 * **When to use**
412 *
413 * Use when you want the model to execute code in a sandboxed environment with
414 * the 2025-05-22 Anthropic code-execution beta.
415 *
416 * **Details**
417 *
418 * Allows the model to execute code in a sandboxed environment with support
419 * for multiple execution types including programmatic tool calls, bash
420 * execution, and text editor operations.
421 *
422 * @see {@link CodeExecutionProgrammaticToolCall} for the programmatic tool call schema
423 *
424 * @stability unstable
425 * @category tools
426 * @since 4.0.0
427 */
428export const CodeExecution_20250522 = Tool.providerDefined({
429 id: "anthropic.code_execution_20250522",
430 customName: "AnthropicCodeExecution",
431 providerName: "code_execution",
432 parameters: CodeExecution_20250522_Parameters,
433 success: Generated.BetaResponseCodeExecutionResultBlock,
434 failure: Generated.BetaResponseCodeExecutionToolResultError
435})
436
437/**
438 * Defines the Anthropic Code Execution tool (2025-08-25 version).
439 *
440 * **When to use**
441 *
442 * Use when you want the model to execute code in a sandboxed environment with
443 * the 2025-08-25 Anthropic code-execution beta.
444 *
445 * **Details**
446 *
447 * Requires the `code-execution-2025-08-25` beta header and uses
448 * `CodeExecution_20250825_Parameters` as its input schema.
449 *
450 * @see {@link CodeExecution_20250522} for the older 2025-05-22 code execution tool
451 * @see {@link CodeExecution_20250825_Parameters} for the input schema consumed by this tool
452 *
453 * @stability unstable
454 * @category tools
455 * @since 4.0.0
456 */
457export const CodeExecution_20250825 = Tool.providerDefined({
458 id: "anthropic.code_execution_20250825",
459 customName: "AnthropicCodeExecution",
460 providerName: "code_execution",
461 parameters: CodeExecution_20250825_Parameters,
462 success: Schema.Union([
463 Generated.BetaResponseCodeExecutionResultBlock,
464 Generated.BetaResponseBashCodeExecutionResultBlock,
465 Generated.BetaResponseTextEditorCodeExecutionViewResultBlock,
466 Generated.BetaResponseTextEditorCodeExecutionCreateResultBlock,
467 Generated.BetaResponseTextEditorCodeExecutionStrReplaceResultBlock
468 ]),
469 failure: Schema.Union([
470 Generated.BetaResponseCodeExecutionToolResultError,
471 Generated.BetaResponseBashCodeExecutionToolResultError,
472 Generated.BetaResponseTextEditorCodeExecutionToolResultError
473 ])
474})
475
476// =============================================================================
477// Computer Use
478// =============================================================================
479
480// -----------------------------------------------------------------------------
481// Common Types
482// -----------------------------------------------------------------------------
483
484/**
485 * Schema for an `[x, y]` screen coordinate in pixels.
486 *
487 * **When to use**
488 *
489 * Use when validating computer-use action payloads that carry a single screen
490 * position and provider-side bounds checks remain acceptable.
491 *
492 * **Details**
493 *
494 * This is a two-number tuple used by computer-use actions that accept screen
495 * positions.
496 *
497 * **Gotchas**
498 *
499 * This schema validates tuple shape only and does not check display bounds.
500 *
501 * @stability unstable
502 * @category schemas
503 * @since 4.0.0
504 */
505export const Coordinate = Schema.Tuple([Schema.Int, Schema.Int])
506/**
507 * An `[x, y]` screen coordinate in pixels.
508 *
509 * @stability unstable
510 * @category models
511 * @since 4.0.0
512 */
513export type Coordinate = typeof Coordinate.Type
514
515/**
516 * Schema for an `[x1, y1, x2, y2]` screen region in pixels.
517 *
518 * **When to use**
519 *
520 * Use when validating computer-use action payloads that carry a rectangular
521 * screen region and provider-side bounds checks remain acceptable.
522 *
523 * **Details**
524 *
525 * The tuple represents top-left and bottom-right corners.
526 *
527 * **Gotchas**
528 *
529 * This schema validates four numbers only and does not check coordinate ordering
530 * or display bounds.
531 *
532 * @stability unstable
533 * @category schemas
534 * @since 4.0.0
535 */
536export const Region = Schema.Tuple([Schema.Int, Schema.Int, Schema.Int, Schema.Int])
537/**
538 * An `[x1, y1, x2, y2]` screen region in pixels, from top-left to bottom-right.
539 *
540 * @stability unstable
541 * @category models
542 * @since 4.0.0
543 */
544export type Region = typeof Region.Type
545
546/**
547 * Schema for scroll direction literals: `"up"`, `"down"`, `"left"`, or `"right"`.
548 *
549 * @see {@link ComputerUseScrollAction} for the action payload that consumes this schema
550 *
551 * @stability unstable
552 * @category schemas
553 * @since 4.0.0
554 */
555export const ScrollDirection = Schema.Literals(["up", "down", "left", "right"])
556/**
557 * Direction used by computer-use scroll actions: `"up"`, `"down"`, `"left"`, or `"right"`.
558 *
559 * @stability unstable
560 * @category models
561 * @since 4.0.0
562 */
563export type ScrollDirection = typeof ScrollDirection.Type
564
565/**
566 * Schema for modifier key literals.
567 *
568 * **Details**
569 *
570 * Allowed values are `"alt"`, `"ctrl"`, `"meta"`, and `"shift"`.
571 *
572 * @stability unstable
573 * @category schemas
574 * @since 4.0.0
575 */
576export const ModifierKey = Schema.Literals(["alt", "ctrl", "meta", "shift"])
577/**
578 * Modifier key literals.
579 *
580 * **Details**
581 *
582 * Allowed values are `"alt"`, `"ctrl"`, `"meta"`, and `"shift"`.
583 *
584 * @stability unstable
585 * @category models
586 * @since 4.0.0
587 */
588export type ModifierKey = typeof ModifierKey.Type
589
590// -----------------------------------------------------------------------------
591// ComputerUse_20241022_Args
592// -----------------------------------------------------------------------------
593
594const ComputerUse_20241022_Args = Schema.Struct({
595 /**
596 * The width of the display being controlled by the model in pixels.
597 */
598 displayWidthPx: Schema.Int,
599
600 /**
601 * The height of the display being controlled by the model in pixels.
602 */
603 displayHeightPx: Schema.Int,
604
605 /**
606 * The display number to control (only relevant for X11 environments). If
607 * specified, the tool will be provided a display number in the tool
608 * definition.
609 */
610 displayNumber: Schema.optional(Schema.Int)
611})
612
613const ComputerUse_20251124_Args = Schema.Struct({
614 ...ComputerUse_20241022_Args.fields,
615 enableZoom: Schema.optional(Schema.Boolean)
616})
617
618// -----------------------------------------------------------------------------
619// Computer Use 20241022 Actions
620// -----------------------------------------------------------------------------
621
622/**
623 * Schema for a computer-use action that presses a key or key combination, such
624 * as `"Return"`, `"ctrl+c"`, or `"ctrl+s"`.
625 *
626 * **When to use**
627 *
628 * Use when validating or constructing a computer-use action for keyboard
629 * shortcuts or non-text key presses.
630 *
631 * @see {@link TypeAction} for entering ordinary text strings
632 * @see {@link ComputerUseHoldKeyAction} for holding a key for a duration
633 *
634 * @stability unstable
635 * @category schemas
636 * @since 4.0.0
637 */
638export const ComputerUseKeyAction = Schema.Struct({
639 action: Schema.Literal("key"),
640 /**
641 * The key to press.
642 */
643 text: Schema.String
644})
645/**
646 * Computer-use action payload for pressing a key or key combination.
647 *
648 * **When to use**
649 *
650 * Use when typing parsed computer-use key action payloads after schema
651 * validation, where provider-specific key-name validation is handled outside
652 * TypeScript.
653 *
654 * **Details**
655 *
656 * The payload uses `action: "key"` and stores the key or key combination to
657 * press in `text`, such as `"Return"`, `"ctrl+c"`, or `"ctrl+s"`.
658 *
659 * **Gotchas**
660 *
661 * `text` is typed as `string`; the paired schema does not validate
662 * provider-specific key names or key combinations.
663 *
664 * @stability unstable
665 * @category models
666 * @since 4.0.0
667 */
668export type ComputerUseKeyAction = typeof ComputerUseKeyAction.Type
669
670/**
671 * Schema for a computer-use action that performs a left click.
672 *
673 * **When to use**
674 *
675 * Use to validate or construct an Anthropic computer-use payload for clicking
676 * once at the current mouse position or at a specific screen coordinate.
677 *
678 * **Details**
679 *
680 * The encoded payload uses `action: "left_click"`. The optional `coordinate`
681 * field supplies the `[x, y]` pixel position; when omitted, the action uses the
682 * current mouse position.
683 *
684 * **Gotchas**
685 *
686 * The coordinate schema only checks that the value is a two-number tuple. It
687 * does not validate that the point falls within the configured display
688 * dimensions.
689 *
690 * @see {@link ComputerUseDoubleClickAction} for performing a double click
691 * @see {@link ComputerUseMouseMoveAction} for moving the mouse without clicking
692 *
693 * @stability unstable
694 * @category schemas
695 * @since 4.0.0
696 */
697export const ComputerUseLeftClickAction = Schema.Struct({
698 action: Schema.Literal("left_click"),
699 /**
700 * The `[x, y]` coordinate on the screen to left click (defaults to the current
701 * mouse position if omitted).
702 */
703 coordinate: Schema.optionalKey(Coordinate)
704})
705/**
706 * Computer-use action payload for performing a left click, optionally at a specific coordinate.
707 *
708 * @stability unstable
709 * @category models
710 * @since 4.0.0
711 */
712export type ComputerUseLeftClickAction = typeof ComputerUseLeftClickAction.Type
713
714/**
715 * Schema for a computer-use action that moves the mouse cursor to a required
716 * `[x, y]` screen coordinate.
717 *
718 * **When to use**
719 *
720 * Use to validate or construct a mouse movement action for an Anthropic
721 * computer-use tool call.
722 *
723 * **Details**
724 *
725 * The encoded payload has action `"mouse_move"` and a required `coordinate`
726 * field containing the target `[x, y]` pixel position.
727 *
728 * **Gotchas**
729 *
730 * The coordinate schema only checks that the value is a two-number tuple. It
731 * does not validate that the point falls within the configured display
732 * dimensions.
733 *
734 * @stability unstable
735 * @category schemas
736 * @since 4.0.0
737 */
738export const ComputerUseMouseMoveAction = Schema.Struct({
739 action: Schema.Literal("mouse_move"),
740 /**
741 * The `[x, y]` coordinate on the screen to move to.
742 */
743 coordinate: Coordinate
744})
745/**
746 * Computer-use action payload for moving the mouse cursor to a specific coordinate.
747 *
748 * @stability unstable
749 * @category models
750 * @since 4.0.0
751 */
752export type ComputerUseMouseMoveAction = typeof ComputerUseMouseMoveAction.Type
753
754/**
755 * Schema for a computer-use action that requests a screenshot of the current display.
756 *
757 * **When to use**
758 *
759 * Use to validate or construct a computer-use tool action that asks the handler
760 * to capture the full current display.
761 *
762 * **Details**
763 *
764 * The payload contains only `action: "screenshot"` and does not include
765 * coordinates or other options.
766 *
767 * @see {@link ComputerUseZoomAction} for requesting a zoomed-in screenshot of a specific screen region with the 2025-11-24 computer-use tool
768 *
769 * @stability unstable
770 * @category schemas
771 * @since 4.0.0
772 */
773export const ComputerUseScreenshotAction = Schema.Struct({
774 action: Schema.Literal("screenshot")
775})
776/**
777 * Computer-use action payload for capturing the current display.
778 *
779 * @stability unstable
780 * @category models
781 * @since 4.0.0
782 */
783export type ComputerUseScreenshotAction = typeof ComputerUseScreenshotAction.Type
784
785/**
786 * Schema for a computer-use action that enters text.
787 *
788 * **When to use**
789 *
790 * Use to validate or construct a computer-use action for entering ordinary text
791 * strings.
792 *
793 * **Details**
794 *
795 * The payload uses `action: "type"` and a `text` string containing the text to
796 * enter.
797 *
798 * @see {@link ComputerUseKeyAction} for key presses and keyboard shortcuts
799 *
800 * @stability unstable
801 * @category schemas
802 * @since 4.0.0
803 */
804export const TypeAction = Schema.Struct({
805 action: Schema.Literal("type"),
806 /**
807 * The text to type.
808 */
809 text: Schema.String
810})
811/**
812 * Computer-use action payload for typing a text string.
813 *
814 * **Details**
815 *
816 * The payload uses `action: "type"` and a `text` string containing the text to
817 * enter.
818 *
819 * @stability unstable
820 * @category models
821 * @since 4.0.0
822 */
823export type TypeAction = typeof TypeAction.Type
824
825const ComputerUse_20241022_Actions = Schema.Union([
826 ComputerUseKeyAction,
827 ComputerUseLeftClickAction,
828 ComputerUseMouseMoveAction,
829 ComputerUseScreenshotAction,
830 TypeAction
831])
832
833// -----------------------------------------------------------------------------
834// Computer Use 20250124 Actions
835// -----------------------------------------------------------------------------
836
837/**
838 * Schema for a computer-use action that performs a double click.
839 *
840 * **When to use**
841 *
842 * Use to validate or construct an Anthropic computer-use payload for double
843 * clicking at the current mouse position or at a specific screen coordinate.
844 *
845 * **Details**
846 *
847 * The encoded payload uses `action: "double_click"`. The optional
848 * `coordinate` field supplies the `[x, y]` pixel position; when omitted, the
849 * action uses the current mouse position.
850 *
851 * **Gotchas**
852 *
853 * The coordinate schema only checks that the value is a two-number tuple. It
854 * does not validate that the point falls within the configured display
855 * dimensions.
856 *
857 * @see {@link ComputerUseLeftClickAction} for performing a single left click
858 *
859 * @stability unstable
860 * @category schemas
861 * @since 4.0.0
862 */
863export const ComputerUseDoubleClickAction = Schema.Struct({
864 action: Schema.Literal("double_click"),
865 /**
866 * The coordinate to double click (defaults to the current mouse position if
867 * omitted).
868 */
869 coordinate: Schema.optionalKey(Coordinate)
870})
871/**
872 * Computer-use action payload for performing a double click, optionally at a specific coordinate.
873 *
874 * @stability unstable
875 * @category models
876 * @since 4.0.0
877 */
878export type ComputerUseDoubleClickAction = typeof ComputerUseDoubleClickAction.Type
879
880/**
881 * Keeps a key pressed for a specified duration during computer-use execution.
882 *
883 * **When to use**
884 *
885 * Use to keep a keyboard key depressed for a fixed number of seconds in a
886 * computer-use action sequence.
887 *
888 * **Details**
889 *
890 * The schema describes objects with `action: "hold_key"`, a `text` field
891 * containing the key to hold, and a `duration` field containing the number of
892 * seconds to hold it.
893 *
894 * **Gotchas**
895 *
896 * The schema only checks that `duration` is a number; it does not require a
897 * positive value.
898 *
899 * @see {@link ComputerUseKeyAction} for pressing a key or key combination without holding it
900 * @see {@link ComputerUseWaitAction} for pausing between actions without holding a key
901 *
902 * @stability unstable
903 * @category schemas
904 * @since 4.0.0
905 */
906export const ComputerUseHoldKeyAction = Schema.Struct({
907 action: Schema.Literal("hold_key"),
908 /**
909 * The key to hold (e.g. `"shift"`, `"ctrl"`).
910 */
911 text: Schema.String,
912 /**
913 * The number of seconds to hold the key.
914 */
915 duration: Schema.Finite
916})
917/**
918 * Computer-use action payload for holding a key for a specified duration.
919 *
920 * **When to use**
921 *
922 * Use to represent a key that should remain pressed for a measured interval.
923 *
924 * **Details**
925 *
926 * Set `action` to `"hold_key"`, `text` to the key to hold, and `duration` to
927 * the number of seconds to hold it.
928 *
929 * @see {@link ComputerUseKeyAction} for a single key press or key combination without a hold duration
930 *
931 * @stability unstable
932 * @category models
933 * @since 4.0.0
934 */
935export type ComputerUseHoldKeyAction = typeof ComputerUseHoldKeyAction.Type
936
937/**
938 * Schema for a computer-use action that drags with the left mouse button.
939 *
940 * **When to use**
941 *
942 * Use to validate or construct an Anthropic computer-use payload for dragging
943 * from one screen coordinate to another in a single action.
944 *
945 * **Details**
946 *
947 * The encoded payload uses `action: "left_click_drag"` and requires both
948 * `start_coordinate` and `coordinate` as `[x, y]` pixel positions.
949 *
950 * **Gotchas**
951 *
952 * The coordinate schema only checks that each value is a two-number tuple. It
953 * does not validate that either point falls within the configured display
954 * dimensions.
955 *
956 * @see {@link ComputerUseLeftMouseDownAction} for starting a manual drag sequence
957 * @see {@link ComputerUseLeftMouseUpAction} for ending a manual drag sequence
958 *
959 * @stability unstable
960 * @category schemas
961 * @since 4.0.0
962 */
963export const ComputerUseLeftClickDragAction = Schema.Struct({
964 action: Schema.Literal("left_click_drag"),
965 /**
966 * The `[x, y]` coordinate to start dragging from.
967 */
968 start_coordinate: Coordinate,
969 /**
970 * The `[x, y]` coordinate to drag to.
971 */
972 coordinate: Coordinate
973})
974/**
975 * Computer-use action payload for dragging from a start coordinate to an end coordinate.
976 *
977 * @stability unstable
978 * @category models
979 * @since 4.0.0
980 */
981export type ComputerUseLeftClickDragAction = typeof ComputerUseLeftClickDragAction.Type
982
983/**
984 * Starts a left mouse button press without releasing it.
985 *
986 * **When to use**
987 *
988 * Use when constructing a manual click or drag sequence that should press and
989 * hold the left mouse button before a later release.
990 *
991 * @stability unstable
992 * @category schemas
993 * @since 4.0.0
994 */
995export const ComputerUseLeftMouseDownAction = Schema.Struct({
996 action: Schema.Literal("left_mouse_down"),
997 /**
998 * The coordinate at which the left mouse button should be held down (defaults
999 * to the current mouse position if omitted).
1000 */
1001 coordinate: Schema.optionalKey(Coordinate)
1002})
1003/**
1004 * Computer-use action payload for pressing and holding the left mouse button, optionally at a specific coordinate.
1005 *
1006 * @stability unstable
1007 * @category models
1008 * @since 4.0.0
1009 */
1010export type ComputerUseLeftMouseDownAction = typeof ComputerUseLeftMouseDownAction.Type
1011
1012/**
1013 * Releases the left mouse button.
1014 *
1015 * **When to use**
1016 *
1017 * Use when constructing a manual click or drag sequence that should release the
1018 * left mouse button after it was previously held down.
1019 *
1020 * @stability unstable
1021 * @category schemas
1022 * @since 4.0.0
1023 */
1024export const ComputerUseLeftMouseUpAction = Schema.Struct({
1025 action: Schema.Literal("left_mouse_up"),
1026 /**
1027 * The coordinate at which the left mouse button should be released (defaults
1028 * to the current mouse position if omitted).
1029 */
1030 coordinate: Schema.optionalKey(Coordinate)
1031})
1032/**
1033 * Computer-use action payload for releasing the left mouse button, optionally at a specific coordinate.
1034 *
1035 * @stability unstable
1036 * @category models
1037 * @since 4.0.0
1038 */
1039export type ComputerUseLeftMouseUpAction = typeof ComputerUseLeftMouseUpAction.Type
1040
1041/**
1042 * Schema for a computer-use action that performs a middle click.
1043 *
1044 * **When to use**
1045 *
1046 * Use to validate or construct a middle-button click action for Anthropic
1047 * computer use, optionally targeting a specific screen coordinate.
1048 *
1049 * **Details**
1050 *
1051 * The payload must use `action: "middle_click"`. When `coordinate` is omitted,
1052 * the click occurs at the current mouse position.
1053 *
1054 * **Gotchas**
1055 *
1056 * This action is available in the 2025-01-24 computer-use action set and later;
1057 * it is not part of `ComputerUse_20241022`.
1058 *
1059 * @see {@link ComputerUse_20250124} for the provider-defined tool version that first accepts this action
1060 * @see {@link ComputerUseLeftClickAction} for primary-button clicks
1061 * @see {@link ComputerUseRightClickAction} for secondary-button clicks
1062 *
1063 * @stability unstable
1064 * @category schemas
1065 * @since 4.0.0
1066 */
1067export const ComputerUseMiddleClickAction = Schema.Struct({
1068 action: Schema.Literal("middle_click"),
1069 /**
1070 * The coordinate to middle click (defaults to the current mouse position if
1071 * omitted).
1072 */
1073 coordinate: Schema.optionalKey(Coordinate)
1074})
1075/**
1076 * Computer-use action payload for performing a middle click, optionally at a specific coordinate.
1077 *
1078 * @stability unstable
1079 * @category models
1080 * @since 4.0.0
1081 */
1082export type ComputerUseMiddleClickAction = typeof ComputerUseMiddleClickAction.Type
1083
1084/**
1085 * Schema for a computer-use action that performs a right click, optionally at a
1086 * specific screen coordinate.
1087 *
1088 * **When to use**
1089 *
1090 * Use to validate or construct the `right_click` action for an Anthropic
1091 * computer-use tool call.
1092 *
1093 * **Details**
1094 *
1095 * The optional `coordinate` field is an `[x, y]` screen coordinate in pixels.
1096 * When omitted, the right click is performed at the current mouse position.
1097 *
1098 * @see {@link ComputerUse_20250124} for the provider-defined computer-use tool version that introduced this action
1099 * @see {@link ComputerUseLeftClickAction} for the corresponding left-click action
1100 * @see {@link ComputerUseMiddleClickAction} for the corresponding middle-click action
1101 *
1102 * @stability unstable
1103 * @category schemas
1104 * @since 4.0.0
1105 */
1106export const ComputerUseRightClickAction = Schema.Struct({
1107 action: Schema.Literal("right_click"),
1108 /**
1109 * The coordinate to right click (defaults to the current mouse position if
1110 * omitted).
1111 */
1112 coordinate: Schema.optionalKey(Coordinate)
1113})
1114/**
1115 * Computer-use action payload for performing a right click, optionally at a specific coordinate.
1116 *
1117 * @stability unstable
1118 * @category models
1119 * @since 4.0.0
1120 */
1121export type ComputerUseRightClickAction = typeof ComputerUseRightClickAction.Type
1122
1123/**
1124 * Schema for a computer-use scroll action.
1125 *
1126 * **When to use**
1127 *
1128 * Use when validating or constructing Anthropic computer-use scroll payloads.
1129 *
1130 * **Details**
1131 *
1132 * The encoded payload uses `action: "scroll"`, an optional `coordinate`,
1133 * `scroll_direction`, and `scroll_amount`.
1134 *
1135 * **Gotchas**
1136 *
1137 * `coordinate` only checks a two-number tuple, and `scroll_amount` is only
1138 * `Schema.Int`.
1139 *
1140 * @see {@link ComputerUse_20250124} for the tool version that accepts this action
1141 * @see {@link ScrollDirection} for the accepted direction literals
1142 *
1143 * @stability unstable
1144 * @category schemas
1145 * @since 4.0.0
1146 */
1147export const ComputerUseScrollAction = Schema.Struct({
1148 action: Schema.Literal("scroll"),
1149 /**
1150 * The coordinate to start scrolling from (defaults to the current mouse
1151 * position if omitted).
1152 */
1153 coordinate: Schema.optionalKey(Coordinate),
1154 /**
1155 * The direction to scroll.
1156 */
1157 scroll_direction: ScrollDirection,
1158 /**
1159 * The amount to scroll (in pixels or scroll units).
1160 */
1161 scroll_amount: Schema.Int
1162})
1163/**
1164 * Computer-use action payload for scrolling by a specified amount in a specified direction, optionally from a coordinate.
1165 *
1166 * @stability unstable
1167 * @category models
1168 * @since 4.0.0
1169 */
1170export type ComputerUseScrollAction = typeof ComputerUseScrollAction.Type
1171
1172/**
1173 * Schema for a computer-use triple-click action.
1174 *
1175 * **When to use**
1176 *
1177 * Use when validating or constructing Anthropic computer-use triple-click
1178 * payloads at the current pointer position or an optional coordinate.
1179 *
1180 * **Details**
1181 *
1182 * The encoded payload uses `action: "triple_click"` and an optional
1183 * `coordinate`.
1184 *
1185 * **Gotchas**
1186 *
1187 * `coordinate` only validates as a two-number tuple and does not check display
1188 * bounds.
1189 *
1190 * @see {@link ComputerUse_20250124} for the tool version that accepts this action
1191 * @see {@link ComputerUseDoubleClickAction} for the two-click variant
1192 * @see {@link ComputerUseLeftClickAction} for a single left click
1193 *
1194 * @stability unstable
1195 * @category schemas
1196 * @since 4.0.0
1197 */
1198export const ComputerUseTripleClickAction = Schema.Struct({
1199 action: Schema.Literal("triple_click"),
1200 /**
1201 * The coordinate to triple click (defaults to the current mouse position if
1202 * omitted).
1203 */
1204 coordinate: Schema.optionalKey(Coordinate)
1205})
1206/**
1207 * Computer-use action payload for performing a triple click, optionally at a specific coordinate.
1208 *
1209 * @stability unstable
1210 * @category models
1211 * @since 4.0.0
1212 */
1213export type ComputerUseTripleClickAction = typeof ComputerUseTripleClickAction.Type
1214
1215/**
1216 * Schema for a computer-use wait action.
1217 *
1218 * **When to use**
1219 *
1220 * Use when validating or constructing Anthropic computer-use payloads that pause
1221 * between actions.
1222 *
1223 * **Details**
1224 *
1225 * The encoded payload uses `action: "wait"` and a required `duration` in
1226 * seconds.
1227 *
1228 * **Gotchas**
1229 *
1230 * `duration` is only `Schema.Finite`; it is not constrained to positive
1231 * values.
1232 *
1233 * @see {@link ComputerUseHoldKeyAction} for another duration-based computer-use action
1234 * @see {@link ComputerUse_20250124} for the tool version that accepts this action
1235 *
1236 * @stability unstable
1237 * @category schemas
1238 * @since 4.0.0
1239 */
1240export const ComputerUseWaitAction = Schema.Struct({
1241 action: Schema.Literal("wait"),
1242 /**
1243 * The number of seconds to wait.
1244 */
1245 duration: Schema.Finite
1246})
1247/**
1248 * Computer-use action payload for pausing for a specified duration.
1249 *
1250 * @stability unstable
1251 * @category models
1252 * @since 4.0.0
1253 */
1254export type ComputerUseWaitAction = typeof ComputerUseWaitAction.Type
1255
1256const ComputerUse_20250124_Actions = Schema.Union([
1257 ...ComputerUse_20241022_Actions.members,
1258 ComputerUseDoubleClickAction,
1259 ComputerUseHoldKeyAction,
1260 ComputerUseLeftClickDragAction,
1261 ComputerUseLeftMouseDownAction,
1262 ComputerUseLeftMouseUpAction,
1263 ComputerUseMiddleClickAction,
1264 ComputerUseRightClickAction,
1265 ComputerUseScrollAction,
1266 ComputerUseTripleClickAction,
1267 ComputerUseWaitAction
1268])
1269
1270// -----------------------------------------------------------------------------
1271// Computer Use 20251124 Actions
1272// -----------------------------------------------------------------------------
1273
1274/**
1275 * Zooms into a specific region of the screen at full resolution.
1276 *
1277 * **When to use**
1278 *
1279 * Use when building or validating the 2025-11-24 computer-use action for a
1280 * zoom-enabled tool definition.
1281 *
1282 * **Details**
1283 *
1284 * The encoded payload uses `action: "zoom"` and a `region` tuple.
1285 *
1286 * **Gotchas**
1287 *
1288 * Requires `enableZoom: true` in the tool definition. `region` is only a
1289 * four-number tuple and does not validate corner ordering or display bounds.
1290 *
1291 * @see {@link ComputerUse_20251124} for the tool version that accepts this action
1292 * @see {@link ComputerUseScreenshotAction} for capturing the full screen instead
1293 *
1294 * @stability unstable
1295 * @category schemas
1296 * @since 4.0.0
1297 */
1298export const ComputerUseZoomAction = Schema.Struct({
1299 action: Schema.Literal("zoom"),
1300 /**
1301 * Region to zoom into, defined as `[x1, y1, x2, y2]` coordinates where
1302 * `(x1, y1)` is the top-left corner and `(x2, y2)` is the bottom-right corner.
1303 */
1304 region: Region
1305})
1306/**
1307 * Computer-use action payload for zooming into a specific screen region.
1308 *
1309 * **Gotchas**
1310 *
1311 * The enclosing computer-use tool must be configured with `enableZoom: true`.
1312 * `region` is only a four-number tuple and does not validate corner ordering or
1313 * display bounds.
1314 *
1315 * @stability unstable
1316 * @category models
1317 * @since 4.0.0
1318 */
1319export type ComputerUseZoomAction = typeof ComputerUseZoomAction.Type
1320
1321const ComputerUse_20251124_Actions = Schema.Union([
1322 ...ComputerUse_20250124_Actions.members,
1323 ComputerUseZoomAction
1324])
1325
1326// -----------------------------------------------------------------------------
1327// Computer Use Tool Definitions
1328// -----------------------------------------------------------------------------
1329
1330/**
1331 * Defines the deprecated computer-use tool for Claude 3.5 Sonnet v2.
1332 *
1333 * **Details**
1334 *
1335 * Requires the "computer-use-2024-10-22" beta header.
1336 * Basic actions only: screenshot, left_click, type, key, mouse_move.
1337 *
1338 * @stability unstable
1339 * @category tools
1340 * @since 4.0.0
1341 */
1342export const ComputerUse_20241022 = Tool.providerDefined({
1343 id: "anthropic.computer_use_20241022",
1344 customName: "AnthropicComputerUse",
1345 providerName: "computer_use",
1346 requiresHandler: true,
1347 args: ComputerUse_20241022_Args,
1348 parameters: ComputerUse_20241022_Actions,
1349 success: Schema.String
1350})
1351
1352/**
1353 * Defines the computer-use tool for Claude 4 models and Claude Sonnet 3.7.
1354 *
1355 * **When to use**
1356 *
1357 * Use when you need Anthropic computer use for Claude 4 models or Claude
1358 * Sonnet 3.7 with the 2025-01-24 action set.
1359 *
1360 * **Details**
1361 *
1362 * Requires the "computer-use-2025-01-24" beta header.
1363 * Includes basic actions plus enhanced actions: scroll, left_click_drag,
1364 * right_click, middle_click, double_click, triple_click, left_mouse_down,
1365 * left_mouse_up, hold_key, wait.
1366 *
1367 * @see {@link ComputerUse_20241022} for the older basic action set
1368 * @see {@link ComputerUse_20251124} for the newer zoom-capable version
1369 *
1370 * @stability unstable
1371 * @category tools
1372 * @since 4.0.0
1373 */
1374export const ComputerUse_20250124 = Tool.providerDefined({
1375 id: "anthropic.computer_20250124",
1376 customName: "AnthropicComputerUse",
1377 providerName: "computer",
1378 requiresHandler: true,
1379 args: ComputerUse_20241022_Args,
1380 parameters: ComputerUse_20250124_Actions,
1381 success: Schema.String
1382})
1383
1384/**
1385 * Defines the computer-use tool for Claude Opus 4.5 only.
1386 *
1387 * **When to use**
1388 *
1389 * Use when you need Anthropic computer use for Claude Opus 4.5 with the
1390 * 2025-11-24 action set and zoom-capable screen inspection.
1391 *
1392 * **Details**
1393 *
1394 * Requires the "computer-use-2025-11-24" beta header.
1395 * Includes all actions from computer_20250124 plus the zoom action for
1396 * detailed screen region inspection.
1397 *
1398 * **Gotchas**
1399 *
1400 * Zoom actions require `enableZoom: true` in args.
1401 *
1402 * @see {@link ComputerUse_20250124} for the previous action set without zoom
1403 * @see {@link ComputerUseZoomAction} for the zoom action payload
1404 *
1405 * @stability unstable
1406 * @category tools
1407 * @since 4.0.0
1408 */
1409export const ComputerUse_20251124 = Tool.providerDefined({
1410 id: "anthropic.computer_20251124",
1411 customName: "AnthropicComputerUse",
1412 providerName: "computer",
1413 requiresHandler: true,
1414 args: ComputerUse_20251124_Args,
1415 parameters: ComputerUse_20251124_Actions,
1416 success: Schema.String
1417})
1418
1419// =============================================================================
1420// Memory
1421// =============================================================================
1422
1423// -----------------------------------------------------------------------------
1424// Common Types
1425// -----------------------------------------------------------------------------
1426
1427/**
1428 * Defines a `[start, end]` line range for viewing file contents.
1429 *
1430 * **When to use**
1431 *
1432 * Use when constructing or validating `view_range` for memory or text editor
1433 * view commands.
1434 *
1435 * **Details**
1436 *
1437 * Lines are 1-indexed. Use `-1` for end to read to the end of the file. For
1438 * example, `[1, 50]` views lines 1-50 and `[100, -1]` views from line 100 to
1439 * the end of the file.
1440 *
1441 * @see {@link MemoryViewCommand} for memory view payloads that use this range
1442 * @see {@link TextEditorViewCommand} for text editor view payloads that use this range
1443 *
1444 * @stability unstable
1445 * @category schemas
1446 * @since 4.0.0
1447 */
1448export const ViewRange = Schema.Tuple([Schema.Int, Schema.Int])
1449/**
1450 * A `[start, end]` 1-indexed line range for viewing file contents, using `-1` as the end value to read through the end of the file.
1451 *
1452 * **When to use**
1453 *
1454 * Use when typing `view_range` for memory or text editor view commands.
1455 *
1456 * @stability unstable
1457 * @category models
1458 * @since 4.0.0
1459 */
1460export type ViewRange = typeof ViewRange.Type
1461
1462// -----------------------------------------------------------------------------
1463// Memory 20250818 Commands
1464// -----------------------------------------------------------------------------
1465
1466/**
1467 * Schema for the memory tool command that creates a new file at a path.
1468 *
1469 * **Details**
1470 *
1471 * The payload contains `command: "create"`, a `path` string, and the
1472 * `file_text` content to write to the file.
1473 *
1474 * @stability unstable
1475 * @category schemas
1476 * @since 4.0.0
1477 */
1478export const MemoryCreateCommand = Schema.Struct({
1479 command: Schema.Literal("create"),
1480 /**
1481 * The path to the file that should be created.
1482 */
1483 path: Schema.String,
1484 /**
1485 * The content to write to the file.
1486 */
1487 file_text: Schema.String
1488})
1489/**
1490 * Memory tool command payload for creating a new file at a path.
1491 *
1492 * @stability unstable
1493 * @category models
1494 * @since 4.0.0
1495 */
1496export type MemoryCreateCommand = typeof MemoryCreateCommand.Type
1497
1498/**
1499 * Schema for a memory command that deletes a file or directory.
1500 *
1501 * @stability unstable
1502 * @category schemas
1503 * @since 4.0.0
1504 */
1505export const MemoryDeleteCommand = Schema.Struct({
1506 command: Schema.Literal("delete"),
1507 /**
1508 * The path to the file or directory to delete.
1509 */
1510 path: Schema.String
1511})
1512/**
1513 * Memory tool command payload for deleting a file or directory at a path.
1514 *
1515 * @stability unstable
1516 * @category models
1517 * @since 4.0.0
1518 */
1519export type MemoryDeleteCommand = typeof MemoryDeleteCommand.Type
1520
1521/**
1522 * Schema for the memory `insert` command.
1523 *
1524 * **When to use**
1525 *
1526 * Use when validating or constructing `insert` payloads for `Memory_20250818`.
1527 *
1528 * **Details**
1529 *
1530 * The payload is discriminated by `command: "insert"` and requires `path`,
1531 * `insert_line`, and `insert_text`.
1532 *
1533 * @see {@link Memory_20250818} for the provider-defined tool that consumes this command
1534 * @see {@link MemoryStrReplaceCommand} for replacing existing text instead
1535 *
1536 * @stability unstable
1537 * @category schemas
1538 * @since 4.0.0
1539 */
1540export const MemoryInsertCommand = Schema.Struct({
1541 command: Schema.Literal("insert"),
1542 /**
1543 * The path to the file to insert text into.
1544 */
1545 path: Schema.String,
1546 /**
1547 * The line at which the text should be inserted.
1548 */
1549 insert_line: Schema.Int,
1550 /**
1551 * The text to insert.
1552 */
1553 insert_text: Schema.String
1554})
1555/**
1556 * Memory tool command payload for inserting text at a specific line in a file.
1557 *
1558 * @stability unstable
1559 * @category models
1560 * @since 4.0.0
1561 */
1562export type MemoryInsertCommand = typeof MemoryInsertCommand.Type
1563
1564/**
1565 * Schema for the memory command that renames or moves a file or directory.
1566 *
1567 * **Details**
1568 *
1569 * The payload uses `command: "rename"` and requires `old_path` as the current
1570 * path plus `new_path` as the new destination path.
1571 *
1572 * @stability unstable
1573 * @category schemas
1574 * @since 4.0.0
1575 */
1576export const MemoryRenameCommand = Schema.Struct({
1577 command: Schema.Literal("rename"),
1578 /**
1579 * The old path to the file or directory.
1580 */
1581 old_path: Schema.String,
1582 /**
1583 * The new path to the file or directory.
1584 */
1585 new_path: Schema.String
1586})
1587/**
1588 * Memory tool command payload for renaming or moving a file or directory.
1589 *
1590 * @stability unstable
1591 * @category models
1592 * @since 4.0.0
1593 */
1594export type MemoryRenameCommand = typeof MemoryRenameCommand.Type
1595
1596/**
1597 * Schema for the memory `str_replace` command.
1598 *
1599 * **When to use**
1600 *
1601 * Use when validating or constructing `str_replace` payloads for
1602 * `Memory_20250818`.
1603 *
1604 * **Details**
1605 *
1606 * The payload is discriminated by `command: "str_replace"` and requires `path`,
1607 * `old_str`, and `new_str`.
1608 *
1609 * @see {@link Memory_20250818} for the provider-defined tool that consumes this command
1610 *
1611 * @stability unstable
1612 * @category schemas
1613 * @since 4.0.0
1614 */
1615export const MemoryStrReplaceCommand = Schema.Struct({
1616 command: Schema.Literal("str_replace"),
1617 /**
1618 * The path to the file in which the replacement should occur.
1619 */
1620 path: Schema.String,
1621 /**
1622 * The text to replace.
1623 */
1624 old_str: Schema.String,
1625 /**
1626 * The replacement text.
1627 */
1628 new_str: Schema.String
1629})
1630/**
1631 * Memory tool command payload for replacing text in a file.
1632 *
1633 * @stability unstable
1634 * @category models
1635 * @since 4.0.0
1636 */
1637export type MemoryStrReplaceCommand = typeof MemoryStrReplaceCommand.Type
1638
1639/**
1640 * Shows directory contents or file contents with optional line ranges.
1641 *
1642 * **Details**
1643 *
1644 * When used on a file, returns file contents optionally limited by `view_range`.
1645 * When used on a directory, lists contents.
1646 *
1647 * @stability unstable
1648 * @category schemas
1649 * @since 4.0.0
1650 */
1651export const MemoryViewCommand = Schema.Struct({
1652 command: Schema.Literal("view"),
1653 /**
1654 * The path to the file or directory to view.
1655 */
1656 path: Schema.String,
1657 /**
1658 * The specific lines to view.
1659 */
1660 view_range: Schema.optionalKey(ViewRange)
1661})
1662/**
1663 * Memory tool command payload for viewing a file or directory, optionally with a file line range.
1664 *
1665 * @stability unstable
1666 * @category models
1667 * @since 4.0.0
1668 */
1669export type MemoryViewCommand = typeof MemoryViewCommand.Type
1670
1671const Memory_20250818_Commands = Schema.Union([
1672 MemoryCreateCommand,
1673 MemoryDeleteCommand,
1674 MemoryInsertCommand,
1675 MemoryRenameCommand,
1676 MemoryStrReplaceCommand,
1677 MemoryViewCommand
1678])
1679
1680// -----------------------------------------------------------------------------
1681// Memory Tool Definitions
1682// -----------------------------------------------------------------------------
1683
1684/**
1685 * Defines the memory tool for persistent file operations across conversations.
1686 *
1687 * **Details**
1688 *
1689 * Provides commands for creating, viewing, editing, renaming, and deleting
1690 * files within the model's memory space.
1691 *
1692 * @stability unstable
1693 * @category tools
1694 * @since 4.0.0
1695 */
1696export const Memory_20250818 = Tool.providerDefined({
1697 id: "anthropic.memory_20250818",
1698 customName: "AnthropicMemory",
1699 providerName: "memory",
1700 requiresHandler: true,
1701 parameters: Memory_20250818_Commands,
1702 success: Schema.String
1703})
1704
1705// =============================================================================
1706// Text Editor
1707// =============================================================================
1708
1709// -----------------------------------------------------------------------------
1710// Text Editor Commands
1711// -----------------------------------------------------------------------------
1712
1713/**
1714 * Reads the contents of a file or lists directory contents.
1715 *
1716 * **When to use**
1717 *
1718 * Use when validating or constructing the standalone Anthropic Text Editor
1719 * `view` command.
1720 *
1721 * **Details**
1722 *
1723 * When used on a file, returns the file contents, optionally limited to a line
1724 * range. When used on a directory, lists all files and subdirectories.
1725 * `view_range` is a 1-indexed `[start, end]` tuple where `-1` means through
1726 * the end of the file.
1727 *
1728 * @see {@link CodeExecutionTextEditorView} for the code-execution variant without `view_range`
1729 *
1730 * @stability unstable
1731 * @category schemas
1732 * @since 4.0.0
1733 */
1734export const TextEditorViewCommand = Schema.Struct({
1735 command: Schema.Literal("view"),
1736 /**
1737 * Absolute or relative path to the file or directory to view.
1738 */
1739 path: Schema.String,
1740 /**
1741 * Optional line range to view (only applies to files, not directories).
1742 * Lines are 1-indexed. Use -1 for end to read to end of file.
1743 */
1744 view_range: Schema.optionalKey(ViewRange)
1745})
1746/**
1747 * Text editor command payload for viewing file contents or listing directory contents.
1748 *
1749 * **Details**
1750 *
1751 * `view_range` is a 1-indexed `[start, end]` tuple where `-1` means through
1752 * the end of the file.
1753 *
1754 * @stability unstable
1755 * @category models
1756 * @since 4.0.0
1757 */
1758export type TextEditorViewCommand = typeof TextEditorViewCommand.Type
1759
1760/**
1761 * Create a new file with specified content.
1762 *
1763 * **When to use**
1764 *
1765 * Use when validating or constructing an Anthropic text editor `create`
1766 * command.
1767 *
1768 * **Details**
1769 *
1770 * The payload is discriminated by `command: "create"` and requires both `path`
1771 * and `file_text`.
1772 *
1773 * **Gotchas**
1774 *
1775 * Fails if the file already exists. Parent directories must exist.
1776 *
1777 * @stability unstable
1778 * @category schemas
1779 * @since 4.0.0
1780 */
1781export const TextEditorCreateCommand = Schema.Struct({
1782 command: Schema.Literal("create"),
1783 /**
1784 * Path where the file should be created.
1785 */
1786 path: Schema.String,
1787 /**
1788 * The content to write to the new file.
1789 */
1790 file_text: Schema.String
1791})
1792/**
1793 * Text editor command payload for creating a new file with the specified content.
1794 *
1795 * **When to use**
1796 *
1797 * Use when typing parsed text-editor create command payloads after schema
1798 * validation and before dispatching to Anthropic tool handlers.
1799 *
1800 * **Gotchas**
1801 *
1802 * The command fails if the file already exists or if parent directories are missing.
1803 *
1804 * @stability unstable
1805 * @category models
1806 * @since 4.0.0
1807 */
1808export type TextEditorCreateCommand = typeof TextEditorCreateCommand.Type
1809
1810/**
1811 * Replaces a specific string in a file with a new string.
1812 *
1813 * **When to use**
1814 *
1815 * Use when validating or constructing standalone Anthropic text editor
1816 * `str_replace` commands.
1817 *
1818 * **Details**
1819 *
1820 * The payload uses `command: "str_replace"`, `path`, `old_str`, and `new_str`.
1821 * `new_str` may be empty to delete text.
1822 *
1823 * **Gotchas**
1824 *
1825 * The `old_str` must match exactly (including whitespace and indentation)
1826 * and must be unique in the file.
1827 *
1828 * @see {@link TextEditorViewCommand} for reading contents before choosing `old_str`
1829 * @see {@link CodeExecutionTextEditorStrReplace} for the code-execution variant
1830 *
1831 * @stability unstable
1832 * @category schemas
1833 * @since 4.0.0
1834 */
1835export const TextEditorStrReplaceCommand = Schema.Struct({
1836 command: Schema.Literal("str_replace"),
1837 /**
1838 * Path to the file to modify.
1839 */
1840 path: Schema.String,
1841 /**
1842 * The exact string to find and replace (must be unique in the file).
1843 */
1844 old_str: Schema.String,
1845 /**
1846 * The string to replace old_str with (can be empty to delete).
1847 */
1848 new_str: Schema.String
1849})
1850/**
1851 * Text editor command payload for replacing one exact, unique string in a file.
1852 *
1853 * **When to use**
1854 *
1855 * Use when typing parsed text-editor replace command payloads that must carry
1856 * one exact `old_str` match.
1857 *
1858 * **Gotchas**
1859 *
1860 * The `old_str` must match exactly, including whitespace and indentation, and
1861 * must be unique in the file.
1862 *
1863 * @stability unstable
1864 * @category models
1865 * @since 4.0.0
1866 */
1867export type TextEditorStrReplaceCommand = typeof TextEditorStrReplaceCommand.Type
1868
1869/**
1870 * Inserts text at a specific line number in a file.
1871 *
1872 * **Details**
1873 *
1874 * Inserts the new text after the specified line number. Use `0` to insert at
1875 * the beginning of the file; other values are 1-indexed.
1876 *
1877 * @stability unstable
1878 * @category schemas
1879 * @since 4.0.0
1880 */
1881export const TextEditorInsertCommand = Schema.Struct({
1882 command: Schema.Literal("insert"),
1883 /**
1884 * Path to the file to modify.
1885 */
1886 path: Schema.String,
1887 /**
1888 * The line number after which to insert (0 = beginning, 1-indexed).
1889 */
1890 insert_line: Schema.Int,
1891 /**
1892 * The text to insert.
1893 */
1894 new_str: Schema.String
1895})
1896/**
1897 * Text editor command payload for inserting text after a specific line number in a file.
1898 *
1899 * @stability unstable
1900 * @category models
1901 * @since 4.0.0
1902 */
1903export type TextEditorInsertCommand = typeof TextEditorInsertCommand.Type
1904
1905/**
1906 * Undoes the last edit made to a file.
1907 *
1908 * **Details**
1909 *
1910 * Reverts the most recent `str_replace`, `insert`, or `create` operation on the
1911 * file.
1912 *
1913 * **Gotchas**
1914 *
1915 * This command is available in `text_editor_20241022` and
1916 * `text_editor_20250124`, but not in `text_editor_20250429` or
1917 * `text_editor_20250728`.
1918 *
1919 * @stability unstable
1920 * @category schemas
1921 * @since 4.0.0
1922 */
1923export const TextEditorUndoEditCommand = Schema.Struct({
1924 command: Schema.Literal("undo_edit"),
1925 /**
1926 * Path to the file to undo the last edit on.
1927 */
1928 path: Schema.String
1929})
1930/**
1931 * Text editor command payload for undoing the most recent edit to a file.
1932 *
1933 * **Gotchas**
1934 *
1935 * Available for `text_editor_20241022` and `text_editor_20250124`, but not for
1936 * `text_editor_20250429` or `text_editor_20250728`.
1937 *
1938 * @stability unstable
1939 * @category models
1940 * @since 4.0.0
1941 */
1942export type TextEditorUndoEditCommand = typeof TextEditorUndoEditCommand.Type
1943
1944const TextEditor_StrReplaceEditor_Commands = Schema.Union([
1945 TextEditorViewCommand,
1946 TextEditorCreateCommand,
1947 TextEditorStrReplaceCommand,
1948 TextEditorInsertCommand,
1949 TextEditorUndoEditCommand
1950])
1951
1952const TextEditor_StrReplaceBasedEdit_Commands = Schema.Union([
1953 TextEditorViewCommand,
1954 TextEditorCreateCommand,
1955 TextEditorStrReplaceCommand,
1956 TextEditorInsertCommand
1957])
1958
1959// -----------------------------------------------------------------------------
1960// Text Editor Args
1961// -----------------------------------------------------------------------------
1962
1963const TextEditor_StrReplaceBasedEdit_Args = Schema.Struct({
1964 /**
1965 * Maximum number of characters to return when viewing large files.
1966 * When a file exceeds this limit, it will be truncated.
1967 */
1968 max_characters: Schema.optional(Schema.Int)
1969})
1970
1971// -----------------------------------------------------------------------------
1972// Text Editor Tool Definitions
1973// -----------------------------------------------------------------------------
1974
1975/**
1976 * Defines the deprecated text editor tool for Claude 3.5 Sonnet.
1977 *
1978 * **When to use**
1979 *
1980 * Use when you need the 2024-10-22 `str_replace_editor` compatibility path for
1981 * Claude 3.5 Sonnet.
1982 *
1983 * **Details**
1984 *
1985 * Requires the "computer-use-2024-10-22" beta header and supports `view`,
1986 * `create`, `str_replace`, `insert`, and `undo_edit` commands.
1987 *
1988 * @see {@link TextEditor_20250124} for the newer `str_replace_editor` version
1989 * @see {@link TextEditor_20250728} for the Claude 4 `str_replace_based_edit_tool` line
1990 *
1991 * @stability unstable
1992 * @category tools
1993 * @since 4.0.0
1994 */
1995export const TextEditor_20241022 = Tool.providerDefined({
1996 id: "anthropic.text_editor_20241022",
1997 customName: "AnthropicTextEditor",
1998 providerName: "str_replace_editor",
1999 requiresHandler: true,
2000 parameters: TextEditor_StrReplaceEditor_Commands,
2001 success: Schema.String
2002})
2003
2004/**
2005 * Defines the text editor tool for deprecated Claude Sonnet 3.7.
2006 *
2007 * **When to use**
2008 *
2009 * Use when you need the 2025-01-24 Claude Sonnet 3.7 text editor tool using
2010 * `str_replace_editor`.
2011 *
2012 * **Details**
2013 *
2014 * Requires the "computer-use-2025-01-24" beta header, requires a handler, and
2015 * supports `view`, `create`, `str_replace`, `insert`, and `undo_edit` commands.
2016 *
2017 * @see {@link TextEditor_20241022} for the older `str_replace_editor` version
2018 * @see {@link TextEditor_20250429} for the Claude 4 `str_replace_based_edit_tool` line
2019 *
2020 * @stability unstable
2021 * @category tools
2022 * @since 4.0.0
2023 */
2024export const TextEditor_20250124 = Tool.providerDefined({
2025 id: "anthropic.text_editor_20250124",
2026 customName: "AnthropicTextEditor",
2027 providerName: "str_replace_editor",
2028 requiresHandler: true,
2029 parameters: TextEditor_StrReplaceEditor_Commands,
2030 success: Schema.String
2031})
2032
2033/**
2034 * Defines the text editor tool for Claude 4 models using Anthropic's `str_replace_based_edit_tool`.
2035 *
2036 * **When to use**
2037 *
2038 * Use when you need the 2025-04-29 Claude 4 `str_replace_based_edit_tool`
2039 * version.
2040 *
2041 * **Details**
2042 *
2043 * Requires the "computer-use-2025-01-24" beta header.
2044 *
2045 * **Gotchas**
2046 *
2047 * This version does not support the `undo_edit` command.
2048 *
2049 * @see {@link TextEditor_20250124} for the previous `str_replace_editor` version
2050 * @see {@link TextEditor_20250728} for the later Claude 4 text editor version
2051 *
2052 * @stability unstable
2053 * @category tools
2054 * @since 4.0.0
2055 */
2056export const TextEditor_20250429 = Tool.providerDefined({
2057 id: "anthropic.text_editor_20250429",
2058 customName: "AnthropicTextEditor",
2059 providerName: "str_replace_based_edit_tool",
2060 requiresHandler: true,
2061 args: TextEditor_StrReplaceBasedEdit_Args,
2062 parameters: TextEditor_StrReplaceBasedEdit_Commands,
2063 success: Schema.String
2064})
2065
2066/**
2067 * Defines the text editor tool for Claude 4 models.
2068 *
2069 * **Details**
2070 *
2071 * Uses Anthropic's `str_replace_based_edit_tool`. `max_characters` can limit
2072 * file-view output for this version.
2073 *
2074 * **Gotchas**
2075 *
2076 * This version does not support the `undo_edit` command.
2077 *
2078 * @stability unstable
2079 * @category tools
2080 * @since 4.0.0
2081 */
2082export const TextEditor_20250728 = Tool.providerDefined({
2083 id: "anthropic.text_editor_20250728",
2084 customName: "AnthropicTextEditor",
2085 providerName: "str_replace_based_edit_tool",
2086 requiresHandler: true,
2087 args: TextEditor_StrReplaceBasedEdit_Args,
2088 parameters: TextEditor_StrReplaceBasedEdit_Commands,
2089 success: Schema.String
2090})
2091
2092// =============================================================================
2093// Web Search
2094// =============================================================================
2095
2096// -----------------------------------------------------------------------------
2097// Web Search Types
2098// -----------------------------------------------------------------------------
2099
2100/**
2101 * Describes user location for localizing search results.
2102 *
2103 * **When to use**
2104 *
2105 * Use when you need to localize search results for location-dependent queries
2106 * like weather, local businesses, or events.
2107 *
2108 * **Details**
2109 *
2110 * The schema uses `type: "approximate"` plus optional `city`, `region`,
2111 * `country`, and `timezone`. `country` is an ISO 3166-1 alpha-2 code, and
2112 * `timezone` is an IANA time zone identifier.
2113 *
2114 * @see {@link WebSearch_20250305_Args} for the argument schema that consumes this location
2115 *
2116 * @stability unstable
2117 * @category schemas
2118 * @since 4.0.0
2119 */
2120export const WebSearchUserLocation = Schema.Struct({
2121 /**
2122 * Location type - currently only "approximate" is supported.
2123 */
2124 type: Schema.Literal("approximate"),
2125 /**
2126 * City name.
2127 */
2128 city: Schema.optional(Schema.String),
2129 /**
2130 * Region/state/province name.
2131 */
2132 region: Schema.optional(Schema.String),
2133 /**
2134 * ISO 3166-1 alpha-2 country code.
2135 */
2136 country: Schema.optional(Schema.String),
2137 /**
2138 * IANA timezone identifier.
2139 */
2140 timezone: Schema.optional(Schema.String)
2141})
2142
2143// -----------------------------------------------------------------------------
2144// Web Search Args
2145// -----------------------------------------------------------------------------
2146
2147/**
2148 * Defines configuration arguments for the web search tool.
2149 *
2150 * **When to use**
2151 *
2152 * Use when you need to configure `WebSearch_20250305` with search limits,
2153 * domain filters, or user location.
2154 *
2155 * **Details**
2156 *
2157 * The payload can set `maxUses`, `allowedDomains`, `blockedDomains`, and
2158 * `userLocation`.
2159 *
2160 * **Gotchas**
2161 *
2162 * `allowedDomains` and `blockedDomains` are mutually exclusive.
2163 *
2164 * @see {@link WebSearch_20250305} for the provider-defined tool that consumes these arguments
2165 * @see {@link WebSearchUserLocation} for localizing search results
2166 *
2167 * @stability unstable
2168 * @category schemas
2169 * @since 4.0.0
2170 */
2171export const WebSearch_20250305_Args = Schema.Struct({
2172 /**
2173 * Maximum number of searches allowed per API request.
2174 */
2175 maxUses: Schema.optional(Schema.Int),
2176 /**
2177 * Restrict search results to only these domains.
2178 *
2179 * Cannot be used together with `blockedDomains`.
2180 */
2181 allowedDomains: Schema.optional(Schema.Array(Schema.String)),
2182 /**
2183 * Exclude results from these domains.
2184 *
2185 * Cannot be used together with `allowedDomains`.
2186 */
2187 blockedDomains: Schema.optional(Schema.Array(Schema.String)),
2188 /**
2189 * User location for localizing search results.
2190 */
2191 userLocation: Schema.optional(WebSearchUserLocation)
2192})
2193/**
2194 * Configuration arguments for the Anthropic web search tool, including usage limits, domain filters, and optional user location.
2195 *
2196 * **Gotchas**
2197 *
2198 * `allowedDomains` and `blockedDomains` are mutually exclusive.
2199 *
2200 * @stability unstable
2201 * @category models
2202 * @since 4.0.0
2203 */
2204export type WebSearch_20250305_Args = typeof WebSearch_20250305_Args.Type
2205
2206// -----------------------------------------------------------------------------
2207// Web Search Parameters
2208// -----------------------------------------------------------------------------
2209
2210/**
2211 * Schema for Claude-supplied web search tool parameters.
2212 *
2213 * **Details**
2214 *
2215 * The payload contains the generated `query` string and is consumed by
2216 * `WebSearch_20250305`.
2217 *
2218 * @see {@link WebSearch_20250305} for the provider-defined tool that consumes this payload
2219 *
2220 * @stability unstable
2221 * @category schemas
2222 * @since 4.0.0
2223 */
2224export const WebSearchParameters = Schema.Struct({
2225 /**
2226 * The search query generated by Claude.
2227 */
2228 query: Schema.String
2229})
2230/**
2231 * Type of the parameters Claude supplies when invoking the Anthropic web search tool.
2232 *
2233 * **Details**
2234 *
2235 * Contains the generated search query used by `WebSearch_20250305`.
2236 *
2237 * @see {@link WebSearch_20250305} for the provider-defined tool that consumes this payload
2238 *
2239 * @stability unstable
2240 * @category models
2241 * @since 4.0.0
2242 */
2243export type WebSearchParameters = typeof WebSearchParameters.Type
2244
2245// -----------------------------------------------------------------------------
2246// Web Search Tool Definitions
2247// -----------------------------------------------------------------------------
2248
2249/**
2250 * Defines the web search tool for Claude models.
2251 *
2252 * **When to use**
2253 *
2254 * Use when you want Claude to search the web for real-time information.
2255 *
2256 * **Details**
2257 *
2258 * Enables Claude to search the web for real-time information. This is a
2259 * server-side tool executed by Anthropic's infrastructure.
2260 * Generally available (no beta header required).
2261 *
2262 * @see {@link WebFetch_20250910} for retrieving known URLs after discovery
2263 *
2264 * @stability unstable
2265 * @category tools
2266 * @since 4.0.0
2267 */
2268export const WebSearch_20250305 = Tool.providerDefined({
2269 id: "anthropic.web_search_20250305",
2270 customName: "AnthropicWebSearch",
2271 providerName: "web_search",
2272 args: WebSearch_20250305_Args,
2273 parameters: WebSearchParameters,
2274 success: Schema.Array(Generated.BetaResponseWebSearchResultBlock),
2275 failure: Generated.BetaResponseWebSearchToolResultError
2276})
2277
2278// =============================================================================
2279// Web Fetch
2280// =============================================================================
2281
2282// -----------------------------------------------------------------------------
2283// Web Fetch Types
2284// -----------------------------------------------------------------------------
2285
2286/**
2287 * Defines citation configuration for web fetch.
2288 *
2289 * **When to use**
2290 *
2291 * Use when you need to enable or disable citations on web fetch results.
2292 *
2293 * **Details**
2294 *
2295 * The payload contains the `enabled` flag. `citations` is optional on
2296 * `WebFetch_20250910_Args`, and citations are disabled by default.
2297 *
2298 * @see {@link WebFetch_20250910_Args} for the argument schema that consumes this configuration
2299 *
2300 * @stability unstable
2301 * @category schemas
2302 * @since 4.0.0
2303 */
2304export const WebFetchCitationsConfig = Schema.Struct({
2305 /**
2306 * Enable citations for fetched content.
2307 */
2308 enabled: Schema.Boolean
2309})
2310/**
2311 * Configuration payload for enabling or disabling citations on web fetch results.
2312 *
2313 * **When to use**
2314 *
2315 * Use when typing parsed web-fetch citation configuration shared between
2316 * request arguments and handler code.
2317 *
2318 * **Details**
2319 *
2320 * The payload contains the `enabled` flag. `citations` is optional on
2321 * `WebFetch_20250910_Args`, and citations are disabled by default.
2322 *
2323 * @see {@link WebFetch_20250910_Args} for the argument schema that consumes this configuration
2324 *
2325 * @stability unstable
2326 * @category models
2327 * @since 4.0.0
2328 */
2329export type WebFetchCitationsConfig = typeof WebFetchCitationsConfig.Type
2330
2331// -----------------------------------------------------------------------------
2332// Web Fetch Args
2333// -----------------------------------------------------------------------------
2334
2335/**
2336 * Defines configuration arguments for the web fetch tool.
2337 *
2338 * **When to use**
2339 *
2340 * Use when you need to configure `WebFetch_20250910` with usage limits, domain
2341 * filters, citations, or content token limits.
2342 *
2343 * **Details**
2344 *
2345 * The payload can set `maxUses`, domain filters, `citations`, and
2346 * `maxContentTokens`, which map to Anthropic web fetch request fields.
2347 *
2348 * **Gotchas**
2349 *
2350 * `allowedDomains` and `blockedDomains` are mutually exclusive.
2351 * `maxContentTokens` is approximate and does not apply to binary content such
2352 * as PDFs.
2353 *
2354 * @see {@link WebFetch_20250910} for the provider-defined tool that consumes these arguments
2355 * @see {@link WebFetchCitationsConfig} for configuring citations
2356 *
2357 * @stability unstable
2358 * @category schemas
2359 * @since 4.0.0
2360 */
2361export const WebFetch_20250910_Args = Schema.Struct({
2362 /**
2363 * Maximum number of fetches allowed per API request.
2364 */
2365 maxUses: Schema.optional(Schema.Int),
2366 /**
2367 * Restrict fetches to only these domains.
2368 *
2369 * Cannot be used together with `blockedDomains`.
2370 */
2371 allowedDomains: Schema.optional(Schema.Array(Schema.String)),
2372 /**
2373 * Exclude fetches from these domains.
2374 *
2375 * Cannot be used together with `allowedDomains`.
2376 */
2377 blockedDomains: Schema.optional(Schema.Array(Schema.String)),
2378 /**
2379 * Enable citations for fetched content.
2380 */
2381 citations: Schema.optional(WebFetchCitationsConfig),
2382 /**
2383 * Maximum content length in tokens.
2384 */
2385 maxContentTokens: Schema.optional(Schema.Int)
2386})
2387/**
2388 * Configuration arguments for the Anthropic web fetch tool, including usage limits, domain filters, citation settings, and token limits.
2389 *
2390 * **When to use**
2391 *
2392 * Use when typing parsed web-fetch tool configuration shared by the
2393 * provider-defined tool and request-building code.
2394 *
2395 * **Gotchas**
2396 *
2397 * `allowedDomains` and `blockedDomains` are mutually exclusive.
2398 * `maxContentTokens` is approximate and does not apply to binary content such
2399 * as PDFs.
2400 *
2401 * @stability unstable
2402 * @category models
2403 * @since 4.0.0
2404 */
2405export type WebFetch_20250910_Args = typeof WebFetch_20250910_Args.Type
2406
2407// -----------------------------------------------------------------------------
2408// Web Fetch Parameters
2409// -----------------------------------------------------------------------------
2410
2411/**
2412 * Schema for Claude-supplied web fetch parameters.
2413 *
2414 * **When to use**
2415 *
2416 * Use when validating or constructing the `url` payload consumed by
2417 * `WebFetch_20250910`.
2418 *
2419 * **Details**
2420 *
2421 * The payload contains the single `url` parameter for Anthropic web fetch.
2422 *
2423 * **Gotchas**
2424 *
2425 * The URL must be user-provided or from prior search/fetch results. Maximum URL
2426 * length is 250 characters.
2427 *
2428 * @see {@link WebFetch_20250910} for the provider-defined tool that consumes this payload
2429 *
2430 * @stability unstable
2431 * @category schemas
2432 * @since 4.0.0
2433 */
2434export const WebFetchParameters = Schema.Struct({
2435 /**
2436 * URL to fetch. Must be a URL provided by the user or from prior search/fetch
2437 * results. Maximum URL length: 250 characters.
2438 */
2439 url: Schema.String
2440})
2441/**
2442 * Type of the parameters Claude supplies when invoking the Anthropic web fetch tool.
2443 *
2444 * **When to use**
2445 *
2446 * Use when typing Claude-supplied web-fetch tool parameters after schema
2447 * validation, before enforcing URL provenance or length constraints.
2448 *
2449 * **Details**
2450 *
2451 * The payload contains the single `url` parameter for Anthropic web fetch.
2452 *
2453 * **Gotchas**
2454 *
2455 * The URL must be user-provided or from prior search/fetch results. Maximum URL
2456 * length is 250 characters.
2457 *
2458 * @stability unstable
2459 * @category models
2460 * @since 4.0.0
2461 */
2462export type WebFetchParameters = typeof WebFetchParameters.Type
2463
2464// -----------------------------------------------------------------------------
2465// Web Fetch Tool Definitions
2466// -----------------------------------------------------------------------------
2467
2468/**
2469 * Defines the web fetch tool for Claude models.
2470 *
2471 * **When to use**
2472 *
2473 * Use when you want Claude to retrieve the content of a specific web page or
2474 * PDF.
2475 *
2476 * **Details**
2477 *
2478 * Allows Claude to retrieve full content from web pages and PDF documents.
2479 * This is a server-side tool executed by Anthropic's infrastructure. Selecting
2480 * this tool adds the "web-fetch-2025-09-10" beta header.
2481 *
2482 * @see {@link WebSearch_20250305} for discovering URLs before fetching specific content
2483 *
2484 * @stability unstable
2485 * @category tools
2486 * @since 4.0.0
2487 */
2488export const WebFetch_20250910 = Tool.providerDefined({
2489 id: "anthropic.web_fetch_20250910",
2490 customName: "AnthropicWebFetch",
2491 providerName: "web_fetch",
2492 args: WebFetch_20250910_Args,
2493 parameters: WebFetchParameters,
2494 success: Generated.BetaResponseWebFetchResultBlock,
2495 failure: Generated.BetaResponseWebFetchToolResultError
2496})
2497
2498// =============================================================================
2499// Tool Search
2500// =============================================================================
2501
2502// -----------------------------------------------------------------------------
2503// Tool Search Parameters
2504// -----------------------------------------------------------------------------
2505
2506/**
2507 * Schema for regex-based tool search input parameters.
2508 *
2509 * **Details**
2510 *
2511 * Claude constructs regex patterns using Python's `re.search()` syntax.
2512 * Maximum query length: 200 characters.
2513 *
2514 * @stability unstable
2515 * @category schemas
2516 * @since 4.0.0
2517 */
2518export const ToolSearchRegexParameters = Schema.Struct({
2519 /**
2520 * Python regex pattern to search for tools.
2521 */
2522 query: Schema.String
2523})
2524/**
2525 * Type of the parameters Claude supplies when invoking regex-based Anthropic tool search.
2526 *
2527 * **Details**
2528 *
2529 * Claude constructs regex patterns using Python's `re.search()` syntax.
2530 * Maximum query length: 200 characters.
2531 *
2532 * @stability unstable
2533 * @category models
2534 * @since 4.0.0
2535 */
2536export type ToolSearchRegexParameters = typeof ToolSearchRegexParameters.Type
2537
2538/**
2539 * Defines input parameters for BM25/natural language tool search.
2540 *
2541 * **When to use**
2542 *
2543 * Use when validating or constructing the natural-language query payload for
2544 * `ToolSearchBM25_20251119`.
2545 *
2546 * **Details**
2547 *
2548 * The payload contains Claude's natural-language `query`. BM25 searches tool
2549 * names, descriptions, argument names, and argument descriptions.
2550 *
2551 * @see {@link ToolSearchBM25_20251119} for the provider-defined tool that consumes these parameters
2552 *
2553 * @stability unstable
2554 * @category schemas
2555 * @since 4.0.0
2556 */
2557export const ToolSearchBM25Parameters = Schema.Struct({
2558 /**
2559 * Natural language query to search for tools.
2560 */
2561 query: Schema.String
2562})
2563/**
2564 * Type of the parameters Claude supplies when invoking BM25 natural-language Anthropic tool search.
2565 *
2566 * @stability unstable
2567 * @category models
2568 * @since 4.0.0
2569 */
2570export type ToolSearchBM25Parameters = typeof ToolSearchBM25Parameters.Type
2571
2572// -----------------------------------------------------------------------------
2573// Tool Search Tool Definitions
2574// -----------------------------------------------------------------------------
2575
2576/**
2577 * Defines regex-based tool search for Claude models.
2578 *
2579 * **Details**
2580 *
2581 * Claude constructs regex patterns using Python's `re.search()` syntax to
2582 * find tools. The regex is matched against tool names, descriptions,
2583 * argument names, and argument descriptions.
2584 * Requires the "advanced-tool-use-2025-11-20" beta header.
2585 *
2586 * @stability unstable
2587 * @category tools
2588 * @since 4.0.0
2589 */
2590export const ToolSearchRegex_20251119 = Tool.providerDefined({
2591 id: "anthropic.tool_search_tool_regex_20251119",
2592 customName: "AnthropicToolSearchRegex",
2593 providerName: "tool_search_tool_regex",
2594 parameters: ToolSearchRegexParameters,
2595 success: Schema.Array(Generated.BetaRequestToolReferenceBlock),
2596 failure: Generated.BetaResponseToolSearchToolResultError
2597})
2598
2599/**
2600 * Defines BM25/natural language tool search for Claude models.
2601 *
2602 * **When to use**
2603 *
2604 * Use when you want Claude to find relevant tools from a natural-language query
2605 * instead of a regex pattern.
2606 *
2607 * **Details**
2608 *
2609 * Claude uses natural language queries to search for tools using the
2610 * BM25 algorithm. The search is performed against tool names, descriptions,
2611 * argument names, and argument descriptions.
2612 * Requires the "advanced-tool-use-2025-11-20" beta header.
2613 *
2614 * @see {@link ToolSearchRegex_20251119} for the regex-pattern alternative
2615 *
2616 * @stability unstable
2617 * @category tools
2618 * @since 4.0.0
2619 */
2620export const ToolSearchBM25_20251119 = Tool.providerDefined({
2621 id: "anthropic.tool_search_tool_bm25_20251119",
2622 customName: "AnthropicToolSearchBM25",
2623 providerName: "tool_search_tool_bm25",
2624 parameters: ToolSearchBM25Parameters,
2625 success: Schema.Array(Generated.BetaRequestToolReferenceBlock),
2626 failure: Generated.BetaResponseToolSearchToolResultError
2627})