@effect/ai-anthropic 4.0.0-beta.70 → 4.0.0-beta.71

package/dist/AnthropicTool.js

@@ -1,8 +1,58 @@
 /**
- * Anthropic provider-defined tools for use with the LanguageModel.
+ * The `AnthropicTool` module defines Anthropic provider tools that can be
+ * attached to Anthropic-backed Effect AI language model requests. These are
+ * provider-defined tools: Anthropic owns the tool names, argument formats,
+ * beta headers, and in some cases the execution environment.
+ *
+ * **Mental model**
+ *
+ * - Exports such as {@link Bash_20250124}, {@link CodeExecution_20250825},
+ *   {@link ComputerUse_20250124}, and {@link WebSearch_20250305} create
+ *   versioned provider-defined tool values understood by the Anthropic
+ *   language model integration
+ * - Tool-specific `Schema` exports describe the arguments Claude may provide
+ *   when invoking that provider tool
+ * - Some tools run on Anthropic infrastructure, such as
+ *   {@link WebSearch_20250305}, {@link WebFetch_20250910}, and
+ *   {@link CodeExecution_20250825}; handler-backed tools such as Bash,
+ *   Computer Use, and Text Editor variants require application-side execution
+ * - Selecting a versioned tool lets the Anthropic model layer add the beta
+ *   header required by that exact Anthropic API version
+ *
+ * **Common tasks**
+ *
+ * - Enable terminal-style actions with {@link Bash_20250124}
+ * - Enable sandboxed code execution with {@link CodeExecution_20250825}
+ * - Enable desktop automation payloads with {@link ComputerUse_20250124}
+ * - Enable persistent memory file operations with {@link Memory_20250818}
+ * - Enable text-editor commands with {@link TextEditor_20250728}
+ * - Enable hosted web capabilities with {@link WebSearch_20250305} or
+ *   {@link WebFetch_20250910}
+ * - Restrict tool discovery with {@link ToolSearchRegex_20251119} or
+ *   {@link ToolSearchBM25_20251119}
+ *
+ * **Quickstart**
+ *
+ * **Example** (Creating hosted Anthropic tools)
+ *
+ * ```ts
+ * import { AnthropicTool } from "@effect/ai-anthropic"
+ *
+ * const tools = [
+ *   AnthropicTool.WebSearch_20250305({ maxUses: 3 }),
+ *   AnthropicTool.WebFetch_20250910({
+ *     citations: { enabled: true }
+ *   })
+ * ]
+ * ```
  *
- * Provides tools that are natively supported by Anthropic's API, including
- * Bash, Code Execution, Computer Use, Memory, and Text Editor functionality.
+ * **Gotchas**
+ *
+ * - The suffix date is part of the Anthropic tool contract; choose the version
+ *   that matches the model and beta behavior you intend to use
+ * - Handler-backed tools expose schemas for Claude's requested actions, but
+ *   your runtime is responsible for performing those actions and returning
+ *   results
  *
  * @since 4.0.0
  */
@@ -15,11 +65,18 @@ import * as Generated from "./Generated.js";
 /**
  * Anthropic Bash tool (2024-10-22 version).
  *
+ * **When to use**
+ *
+ * Use when you need the model to execute bash commands and require the 2024-10-22
+ * version of the Anthropic computer-use beta.
+ *
  * **Details**
  *
  * Allows the model to execute bash commands in a sandboxed environment.
  * Requires the "computer-use-2024-10-22" beta header.
  *
+ * @see {@link Bash_20250124} for the newer 2025-01-24 version of the bash tool
+ *
  * @category Bash
  * @since 4.0.0
  */
@@ -37,11 +94,18 @@ export const Bash_20241022 = /*#__PURE__*/Tool.providerDefined({
 /**
  * Anthropic Bash tool (2025-01-24 version).
  *
+ * **When to use**
+ *
+ * Use when you need the model to execute bash commands and require the 2025-01-24
+ * version of the Anthropic computer-use beta.
+ *
  * **Details**
  *
  * Allows the model to execute bash commands in a sandboxed environment.
  * Requires the "computer-use-2025-01-24" beta header.
  *
+ * @see {@link Bash_20241022} for the older 2024-10-22 version of the bash tool
+ *
  * @category Bash
  * @since 4.0.0
  */
@@ -65,6 +129,13 @@ export const Bash_20250124 = /*#__PURE__*/Tool.providerDefined({
 /**
  * Schema for a code execution request that asks Anthropic to run source code as a programmatic tool call.
  *
+ * **When to use**
+ *
+ * Use when constructing or validating a programmatic tool call for the Anthropic
+ * Code Execution tool.
+ *
+ * @see {@link CodeExecution_20250522} for the parent tool definition
+ *
  * @category Code Execution
  * @since 4.0.0
  */
@@ -76,7 +147,19 @@ export const CodeExecutionProgrammaticToolCall = /*#__PURE__*/Schema.Struct({
   code: Schema.String
 });
 /**
- * Schema for a code execution request that runs a bash command.
+ * Schema for the `bash_code_execution` input variant of Anthropic Code Execution.
+ *
+ * **When to use**
+ *
+ * Use when validating or constructing a bash command request for
+ * `CodeExecution_20250522`.
+ *
+ * **Details**
+ *
+ * The schema requires `type` to be `"bash_code_execution"` and `command` to
+ * contain the bash command sent to Anthropic.
+ *
+ * @see {@link CodeExecution_20250522} for the provider-defined tool that consumes this input variant
  *
  * @category Code Execution
  * @since 4.0.0
@@ -89,7 +172,20 @@ export const CodeExecutionBashCommand = /*#__PURE__*/Schema.Struct({
   command: Schema.String
 });
 /**
- * Text editor view command for code execution.
+ * Schema for a code execution text editor request that views a file by path.
+ *
+ * **When to use**
+ *
+ * Use to validate or construct the `view` command for Anthropic code execution
+ * text editor tool calls.
+ *
+ * **Details**
+ *
+ * The encoded payload uses `type: "text_editor_code_execution"`,
+ * `command: "view"`, and a `path` string.
+ *
+ * @see {@link CodeExecutionTextEditorCreate} for the command that creates a file
+ * @see {@link CodeExecutionTextEditorStrReplace} for the command that replaces text in a file
  *
  * @category Code Execution
  * @since 4.0.0
@@ -103,7 +199,22 @@ export const CodeExecutionTextEditorView = /*#__PURE__*/Schema.Struct({
   path: Schema.String
 });
 /**
- * Text editor create command for code execution.
+ * Schema for a text editor code execution request that creates a file at a path.
+ *
+ * **When to use**
+ *
+ * Use when validating or constructing an Anthropic `text_editor_code_execution`
+ * tool call that should create a file.
+ *
+ * **Details**
+ *
+ * The request is discriminated by `type: "text_editor_code_execution"` and
+ * `command: "create"`. It requires `path` and accepts optional `file_text`; the
+ * schema allows `file_text` to be omitted, `null`, or a string.
+ *
+ * @see {@link CodeExecution_20250522} for the provider-defined tool that consumes this request
+ * @see {@link CodeExecutionTextEditorView} for the matching view request
+ * @see {@link CodeExecutionTextEditorStrReplace} for the matching replace request
  *
  * @category Code Execution
  * @since 4.0.0
@@ -121,7 +232,20 @@ export const CodeExecutionTextEditorCreate = /*#__PURE__*/Schema.Struct({
   file_text: /*#__PURE__*/Schema.optional(/*#__PURE__*/Schema.NullOr(Schema.String))
 });
 /**
- * Text editor str_replace command for code execution.
+ * Schema for a code execution text editor request that replaces one exact string in a file.
+ *
+ * **When to use**
+ *
+ * Use when validating or constructing the `str_replace` text editor operation
+ * for the 2025-05-22 Anthropic code execution tool.
+ *
+ * **Gotchas**
+ *
+ * The `old_str` must match the file contents exactly, including whitespace and
+ * indentation, and must identify a single occurrence.
+ *
+ * @see {@link CodeExecutionTextEditorView} for reading file contents before choosing the replacement text
+ * @see {@link CodeExecution_20250522} for the provider-defined tool that consumes this payload
  *
  * @category Code Execution
  * @since 4.0.0
@@ -149,6 +273,13 @@ const CodeExecution_20250522_Parameters = /*#__PURE__*/Schema.Union([CodeExecuti
 /**
  * Schema for the 2025-08-25 code execution tool input, containing the code to execute.
  *
+ * **When to use**
+ *
+ * Use when validating or constructing the input payload for the 2025-08-25
+ * Anthropic code execution tool.
+ *
+ * @see {@link CodeExecution_20250825} for the provider-defined tool that consumes this schema
+ *
  * @category Code Execution
  * @since 4.0.0
  */
@@ -164,12 +295,19 @@ export const CodeExecution_20250825_Parameters = /*#__PURE__*/Schema.Struct({
 /**
  * Anthropic Code Execution tool (2025-05-22 version).
  *
+ * **When to use**
+ *
+ * Use when you need the model to execute code in a sandboxed environment and
+ * require the 2025-05-22 version of the Anthropic code-execution beta.
+ *
  * **Details**
  *
  * Allows the model to execute code in a sandboxed environment with support
  * for multiple execution types including programmatic tool calls, bash
  * execution, and text editor operations.
  *
+ * @see {@link CodeExecutionProgrammaticToolCall} for the programmatic tool call schema
+ *
  * @category Code Execution
  * @since 4.0.0
  */
@@ -184,9 +322,18 @@ export const CodeExecution_20250522 = /*#__PURE__*/Tool.providerDefined({
 /**
  * Anthropic Code Execution tool (2025-08-25 version).
  *
+ * **When to use**
+ *
+ * Use when you need the model to execute code in a sandboxed environment and
+ * require the 2025-08-25 version of the Anthropic code-execution beta.
+ *
  * **Details**
  *
- * Allows the model to execute code in a sandboxed environment.
+ * Requires the `code-execution-2025-08-25` beta header and uses
+ * `CodeExecution_20250825_Parameters` as its input schema.
+ *
+ * @see {@link CodeExecution_20250522} for the older 2025-05-22 code execution tool
+ * @see {@link CodeExecution_20250825_Parameters} for the input schema consumed by this tool
  *
  * @category Code Execution
  * @since 4.0.0
@@ -206,28 +353,52 @@ export const CodeExecution_20250825 = /*#__PURE__*/Tool.providerDefined({
 // Common Types
 // -----------------------------------------------------------------------------
 /**
- * An `[x, y]` pixel position.
+ * Schema for an `[x, y]` screen coordinate in pixels.
+ *
+ * **Details**
+ *
+ * This is a two-number tuple used by computer-use actions that accept screen
+ * positions.
+ *
+ * **Gotchas**
+ *
+ * This schema validates tuple shape only and does not check display bounds.
  *
  * @category Computer Use
  * @since 4.0.0
  */
 export const Coordinate = /*#__PURE__*/Schema.Tuple([Schema.Number, Schema.Number]);
 /**
- * A `[x1, y1, x2, y2]` position defining top-left and bottom-right corners.
+ * Schema for an `[x1, y1, x2, y2]` screen region in pixels.
+ *
+ * **Details**
+ *
+ * The tuple represents top-left and bottom-right corners.
+ *
+ * **Gotchas**
+ *
+ * This schema validates four numbers only and does not check coordinate ordering
+ * or display bounds.
  *
  * @category Computer Use
  * @since 4.0.0
  */
 export const Region = /*#__PURE__*/Schema.Tuple([Schema.Number, Schema.Number, Schema.Number, Schema.Number]);
 /**
- * The direction of the scroll for scroll actions.
+ * Scroll direction literal: `"up"`, `"down"`, `"left"`, or `"right"`.
+ *
+ * @see {@link ComputerUseScrollAction} for the action payload that consumes this schema
  *
  * @category Computer Use
  * @since 4.0.0
  */
 export const ScrollDirection = /*#__PURE__*/Schema.Literals(["up", "down", "left", "right"]);
 /**
- * Modifier keys that can be held during click/scroll actions.
+ * Modifier key literal.
+ *
+ * **Details**
+ *
+ * Allowed values are `"alt"`, `"ctrl"`, `"meta"`, and `"shift"`.
  *
  * @category Computer Use
  * @since 4.0.0
@@ -260,7 +431,16 @@ const ComputerUse_20251124_Args = /*#__PURE__*/Schema.Struct({
 // Computer Use 20241022 Actions
 // -----------------------------------------------------------------------------
 /**
- * Press a key or key combination (e.g. `"Return"`, `"ctrl+c"`, `"ctrl+s"`).
+ * Schema for a computer-use action that presses a key or key combination, such
+ * as `"Return"`, `"ctrl+c"`, or `"ctrl+s"`.
+ *
+ * **When to use**
+ *
+ * Use when validating or constructing a computer-use action for keyboard
+ * shortcuts or non-text key presses.
+ *
+ * @see {@link TypeAction} for entering ordinary text strings
+ * @see {@link ComputerUseHoldKeyAction} for holding a key for a duration
  *
  * @category Computer Use
  * @since 4.0.0
@@ -273,7 +453,27 @@ export const ComputerUseKeyAction = /*#__PURE__*/Schema.Struct({
   text: Schema.String
 });
 /**
- * Perform a left click at the current mouse position or the specified coordinates.
+ * Schema for a computer-use action that performs a left click.
+ *
+ * **When to use**
+ *
+ * Use to validate or construct an Anthropic computer-use payload for clicking
+ * once at the current mouse position or at a specific screen coordinate.
+ *
+ * **Details**
+ *
+ * The encoded payload uses `action: "left_click"`. The optional `coordinate`
+ * field supplies the `[x, y]` pixel position; when omitted, the action uses the
+ * current mouse position.
+ *
+ * **Gotchas**
+ *
+ * The coordinate schema only checks that the value is a two-number tuple. It
+ * does not validate that the point falls within the configured display
+ * dimensions.
+ *
+ * @see {@link ComputerUseDoubleClickAction} for performing a double click
+ * @see {@link ComputerUseMouseMoveAction} for moving the mouse without clicking
  *
  * @category Computer Use
  * @since 4.0.0
@@ -287,7 +487,24 @@ export const ComputerUseLeftClickAction = /*#__PURE__*/Schema.Struct({
   coordinate: /*#__PURE__*/Schema.optional(Coordinate)
 });
 /**
- * Move the mouse cursor to the specified coordinates.
+ * Schema for a computer-use action that moves the mouse cursor to a required
+ * `[x, y]` screen coordinate.
+ *
+ * **When to use**
+ *
+ * Use to validate or construct a mouse movement action for an Anthropic
+ * computer-use tool call.
+ *
+ * **Details**
+ *
+ * The encoded payload has action `"mouse_move"` and a required `coordinate`
+ * field containing the target `[x, y]` pixel position.
+ *
+ * **Gotchas**
+ *
+ * The coordinate schema only checks that the value is a two-number tuple. It
+ * does not validate that the point falls within the configured display
+ * dimensions.
  *
  * @category Computer Use
  * @since 4.0.0
@@ -300,7 +517,19 @@ export const ComputerUseMouseMoveAction = /*#__PURE__*/Schema.Struct({
   coordinate: Coordinate
 });
 /**
- * Capture the current display.
+ * Schema for a computer-use action that requests a screenshot of the current display.
+ *
+ * **When to use**
+ *
+ * Use to validate or construct a computer-use tool action that asks the handler
+ * to capture the full current display.
+ *
+ * **Details**
+ *
+ * The payload contains only `action: "screenshot"` and does not include
+ * coordinates or other options.
+ *
+ * @see {@link ComputerUseZoomAction} for requesting a zoomed-in screenshot of a specific screen region with the 2025-11-24 computer-use tool
  *
  * @category Computer Use
  * @since 4.0.0
@@ -309,7 +538,19 @@ export const ComputerUseScreenshotAction = /*#__PURE__*/Schema.Struct({
   action: /*#__PURE__*/Schema.Literal("screenshot")
 });
 /**
- * Type a text string.
+ * Schema for a computer-use action that enters text.
+ *
+ * **When to use**
+ *
+ * Use to validate or construct a computer-use action for entering ordinary text
+ * strings.
+ *
+ * **Details**
+ *
+ * The payload uses `action: "type"` and a `text` string containing the text to
+ * enter.
+ *
+ * @see {@link ComputerUseKeyAction} for key presses and keyboard shortcuts
  *
  * @category Computer Use
  * @since 4.0.0
@@ -326,7 +567,26 @@ const ComputerUse_20241022_Actions = /*#__PURE__*/Schema.Union([ComputerUseKeyAc
 // Computer Use 20250124 Actions
 // -----------------------------------------------------------------------------
 /**
- * Perform a double click.
+ * Schema for a computer-use action that performs a double click.
+ *
+ * **When to use**
+ *
+ * Use to validate or construct an Anthropic computer-use payload for double
+ * clicking at the current mouse position or at a specific screen coordinate.
+ *
+ * **Details**
+ *
+ * The encoded payload uses `action: "double_click"`. The optional
+ * `coordinate` field supplies the `[x, y]` pixel position; when omitted, the
+ * action uses the current mouse position.
+ *
+ * **Gotchas**
+ *
+ * The coordinate schema only checks that the value is a two-number tuple. It
+ * does not validate that the point falls within the configured display
+ * dimensions.
+ *
+ * @see {@link ComputerUseLeftClickAction} for performing a single left click
  *
  * @category Computer Use
  * @since 4.0.0
@@ -342,6 +602,25 @@ export const ComputerUseDoubleClickAction = /*#__PURE__*/Schema.Struct({
 /**
  * Hold a key for a specified duration during computer-use execution.
  *
+ * **When to use**
+ *
+ * Use to keep a keyboard key depressed for a fixed number of seconds in a
+ * computer-use action sequence.
+ *
+ * **Details**
+ *
+ * The schema describes objects with `action: "hold_key"`, a `text` field
+ * containing the key to hold, and a `duration` field containing the number of
+ * seconds to hold it.
+ *
+ * **Gotchas**
+ *
+ * The schema only checks that `duration` is a number; it does not require a
+ * positive value.
+ *
+ * @see {@link ComputerUseKeyAction} for pressing a key or key combination without holding it
+ * @see {@link ComputerUseWaitAction} for pausing between actions without holding a key
+ *
  * @category Computer Use
  * @since 4.0.0
  */
@@ -357,7 +636,26 @@ export const ComputerUseHoldKeyAction = /*#__PURE__*/Schema.Struct({
   duration: Schema.Number
 });
 /**
- * Click and drag from start coordinate to end coordinate.
+ * Schema for a computer-use action that drags with the left mouse button.
+ *
+ * **When to use**
+ *
+ * Use to validate or construct an Anthropic computer-use payload for dragging
+ * from one screen coordinate to another in a single action.
+ *
+ * **Details**
+ *
+ * The encoded payload uses `action: "left_click_drag"` and requires both
+ * `start_coordinate` and `coordinate` as `[x, y]` pixel positions.
+ *
+ * **Gotchas**
+ *
+ * The coordinate schema only checks that each value is a two-number tuple. It
+ * does not validate that either point falls within the configured display
+ * dimensions.
+ *
+ * @see {@link ComputerUseLeftMouseDownAction} for starting a manual drag sequence
+ * @see {@link ComputerUseLeftMouseUpAction} for ending a manual drag sequence
  *
  * @category Computer Use
  * @since 4.0.0
@@ -378,7 +676,7 @@ export const ComputerUseLeftClickDragAction = /*#__PURE__*/Schema.Struct({
  *
  * **When to use**
  *
- * Use this for fine-grained click control.
+ * Use when you use this for fine-grained click control.
  *
  * @category Computer Use
  * @since 4.0.0
@@ -396,7 +694,7 @@ export const ComputerUseLeftMouseDownAction = /*#__PURE__*/Schema.Struct({
  *
  * **When to use**
  *
- * Use this for fine-grained click control.
+ * Use when you use this for fine-grained click control.
  *
  * @category Computer Use
  * @since 4.0.0
@@ -410,7 +708,26 @@ export const ComputerUseLeftMouseUpAction = /*#__PURE__*/Schema.Struct({
   coordinate: /*#__PURE__*/Schema.optional(Coordinate)
 });
 /**
- * Perform a middle click.
+ * Schema for a computer-use action that performs a middle click.
+ *
+ * **When to use**
+ *
+ * Use to validate or construct a middle-button click action for Anthropic
+ * computer use, optionally targeting a specific screen coordinate.
+ *
+ * **Details**
+ *
+ * The payload must use `action: "middle_click"`. When `coordinate` is omitted,
+ * the click occurs at the current mouse position.
+ *
+ * **Gotchas**
+ *
+ * This action is available in the 2025-01-24 computer-use action set and later;
+ * it is not part of `ComputerUse_20241022`.
+ *
+ * @see {@link ComputerUse_20250124} for the provider-defined tool version that first accepts this action
+ * @see {@link ComputerUseLeftClickAction} for primary-button clicks
+ * @see {@link ComputerUseRightClickAction} for secondary-button clicks
  *
  * @category Computer Use
  * @since 4.0.0
@@ -424,7 +741,22 @@ export const ComputerUseMiddleClickAction = /*#__PURE__*/Schema.Struct({
   coordinate: /*#__PURE__*/Schema.optional(Coordinate)
 });
 /**
- * Perform a right click.
+ * Schema for a computer-use action that performs a right click, optionally at a
+ * specific screen coordinate.
+ *
+ * **When to use**
+ *
+ * Use to validate or construct the `right_click` action for an Anthropic
+ * computer-use tool call.
+ *
+ * **Details**
+ *
+ * The optional `coordinate` field is an `[x, y]` screen coordinate in pixels.
+ * When omitted, the right click is performed at the current mouse position.
+ *
+ * @see {@link ComputerUse_20250124} for the provider-defined computer-use tool version that introduced this action
+ * @see {@link ComputerUseLeftClickAction} for the corresponding left-click action
+ * @see {@link ComputerUseMiddleClickAction} for the corresponding middle-click action
  *
  * @category Computer Use
  * @since 4.0.0
@@ -438,7 +770,24 @@ export const ComputerUseRightClickAction = /*#__PURE__*/Schema.Struct({
   coordinate: /*#__PURE__*/Schema.optional(Coordinate)
 });
 /**
- * Scroll a given amount in a specified direction.
+ * Schema for a computer-use scroll action.
+ *
+ * **When to use**
+ *
+ * Use when validating or constructing Anthropic computer-use scroll payloads.
+ *
+ * **Details**
+ *
+ * The encoded payload uses `action: "scroll"`, an optional `coordinate`,
+ * `scroll_direction`, and `scroll_amount`.
+ *
+ * **Gotchas**
+ *
+ * `coordinate` only checks a two-number tuple, and `scroll_amount` is only
+ * `Schema.Number`.
+ *
+ * @see {@link ComputerUse_20250124} for the tool version that accepts this action
+ * @see {@link ScrollDirection} for the accepted direction literals
  *
  * @category Computer Use
  * @since 4.0.0
@@ -460,7 +809,26 @@ export const ComputerUseScrollAction = /*#__PURE__*/Schema.Struct({
   scroll_amount: Schema.Number
 });
 /**
- * Perform a triple click.
+ * Schema for a computer-use triple-click action.
+ *
+ * **When to use**
+ *
+ * Use when validating or constructing Anthropic computer-use triple-click
+ * payloads at the current pointer position or an optional coordinate.
+ *
+ * **Details**
+ *
+ * The encoded payload uses `action: "triple_click"` and an optional
+ * `coordinate`.
+ *
+ * **Gotchas**
+ *
+ * `coordinate` only validates as a two-number tuple and does not check display
+ * bounds.
+ *
+ * @see {@link ComputerUse_20250124} for the tool version that accepts this action
+ * @see {@link ComputerUseDoubleClickAction} for the two-click variant
+ * @see {@link ComputerUseLeftClickAction} for a single left click
  *
  * @category Computer Use
  * @since 4.0.0
@@ -474,7 +842,25 @@ export const ComputerUseTripleClickAction = /*#__PURE__*/Schema.Struct({
   coordinate: /*#__PURE__*/Schema.optional(Coordinate)
 });
 /**
- * Pause between performing actions.
+ * Schema for a computer-use wait action.
+ *
+ * **When to use**
+ *
+ * Use when validating or constructing Anthropic computer-use payloads that pause
+ * between actions.
+ *
+ * **Details**
+ *
+ * The encoded payload uses `action: "wait"` and a required `duration` in
+ * seconds.
+ *
+ * **Gotchas**
+ *
+ * `duration` is only `Schema.Number`; it is not constrained to positive or
+ * finite values.
+ *
+ * @see {@link ComputerUseHoldKeyAction} for another duration-based computer-use action
+ * @see {@link ComputerUse_20250124} for the tool version that accepts this action
  *
  * @category Computer Use
  * @since 4.0.0
@@ -495,7 +881,15 @@ const ComputerUse_20250124_Actions = /*#__PURE__*/Schema.Union([...ComputerUse_2
  *
  * **Details**
  *
- * Requires `enableZoom: true` in the tool definition.
+ * The encoded payload uses `action: "zoom"` and a `region` tuple.
+ *
+ * **Gotchas**
+ *
+ * Requires `enableZoom: true` in the tool definition. `region` is only a
+ * four-number tuple and does not validate corner ordering or display bounds.
+ *
+ * @see {@link ComputerUse_20251124} for the tool version that accepts this action
+ * @see {@link ComputerUseScreenshotAction} for capturing the full screen instead
  *
  * @category Computer Use
  * @since 4.0.0
@@ -535,6 +929,11 @@ export const ComputerUse_20241022 = /*#__PURE__*/Tool.providerDefined({
 /**
  * Computer use tool for Claude 4 models and Claude Sonnet 3.7.
  *
+ * **When to use**
+ *
+ * Use when configuring Anthropic computer use for Claude 4 models or Claude
+ * Sonnet 3.7 with the 2025-01-24 action set.
+ *
  * **Details**
  *
  * Requires the "computer-use-2025-01-24" beta header.
@@ -542,6 +941,9 @@ export const ComputerUse_20241022 = /*#__PURE__*/Tool.providerDefined({
  * right_click, middle_click, double_click, triple_click, left_mouse_down,
  * left_mouse_up, hold_key, wait.
  *
+ * @see {@link ComputerUse_20241022} for the older basic action set
+ * @see {@link ComputerUse_20251124} for the newer zoom-capable version
+ *
  * @category Computer Use
  * @since 4.0.0
  */
@@ -557,11 +959,23 @@ export const ComputerUse_20250124 = /*#__PURE__*/Tool.providerDefined({
 /**
  * Computer use tool for Claude Opus 4.5 only.
  *
+ * **When to use**
+ *
+ * Use when configuring Anthropic computer use for Claude Opus 4.5 with the
+ * 2025-11-24 action set and zoom-capable screen inspection.
+ *
  * **Details**
  *
  * Requires the "computer-use-2025-11-24" beta header.
  * Includes all actions from computer_20250124 plus the zoom action for
- * detailed screen region inspection. Requires `enableZoom: true` in args.
+ * detailed screen region inspection.
+ *
+ * **Gotchas**
+ *
+ * Zoom actions require `enableZoom: true` in args.
+ *
+ * @see {@link ComputerUse_20250124} for the previous action set without zoom
+ * @see {@link ComputerUseZoomAction} for the zoom action payload
  *
  * @category Computer Use
  * @since 4.0.0
@@ -584,12 +998,20 @@ export const ComputerUse_20251124 = /*#__PURE__*/Tool.providerDefined({
 /**
  * A `[start, end]` line range for viewing file contents.
  *
+ * **When to use**
+ *
+ * Use when constructing or validating `view_range` for memory or text editor
+ * view commands.
+ *
  * **Details**
  *
- * Lines are 1-indexed. Use -1 for end to read to the end of the file. For
+ * Lines are 1-indexed. Use `-1` for end to read to the end of the file. For
  * example, `[1, 50]` views lines 1-50 and `[100, -1]` views from line 100 to
  * the end of the file.
  *
+ * @see {@link MemoryViewCommand} for memory view payloads that use this range
+ * @see {@link TextEditorViewCommand} for text editor view payloads that use this range
+ *
  * @category Memory
  * @since 4.0.0
  */
@@ -598,7 +1020,11 @@ export const ViewRange = /*#__PURE__*/Schema.Tuple([Schema.Number, Schema.Number
 // Memory 20250818 Commands
 // -----------------------------------------------------------------------------
 /**
- * Creates a new file.
+ * Schema for the memory tool command that creates a new file at a path.
+ *
+ * **Details**
+ *
+ * The payload contains `command: "create"` and a `path` string.
  *
  * @category Memory
  * @since 4.0.0
@@ -611,7 +1037,7 @@ export const MemoryCreateCommand = /*#__PURE__*/Schema.Struct({
   path: Schema.String
 });
 /**
- * Delete a file or directory.
+ * Schema for a memory command that deletes a file or directory.
  *
  * @category Memory
  * @since 4.0.0
@@ -619,12 +1045,24 @@ export const MemoryCreateCommand = /*#__PURE__*/Schema.Struct({
 export const MemoryDeleteCommand = /*#__PURE__*/Schema.Struct({
   command: /*#__PURE__*/Schema.Literal("delete"),
   /**
-   * The path to the file to delete.
+   * The path to the file or directory to delete.
    */
   path: Schema.String
 });
 /**
- * Insert text at a specific line.
+ * Schema for the memory `insert` command.
+ *
+ * **When to use**
+ *
+ * Use when validating or constructing `insert` payloads for `Memory_20250818`.
+ *
+ * **Details**
+ *
+ * The payload is discriminated by `command: "insert"` and requires `path`,
+ * `insert_line`, and `insert_text`.
+ *
+ * @see {@link Memory_20250818} for the provider-defined tool that consumes this command
+ * @see {@link MemoryStrReplaceCommand} for replacing existing text instead
  *
  * @category Memory
  * @since 4.0.0
@@ -645,7 +1083,12 @@ export const MemoryInsertCommand = /*#__PURE__*/Schema.Struct({
   insert_text: Schema.String
 });
 /**
- * Rename or move a file or directory.
+ * Schema for the memory command that renames or moves a file or directory.
+ *
+ * **Details**
+ *
+ * The payload uses `command: "rename"` and requires `old_path` as the current
+ * path plus `new_path` as the new destination path.
  *
  * @category Memory
  * @since 4.0.0
@@ -662,7 +1105,19 @@ export const MemoryRenameCommand = /*#__PURE__*/Schema.Struct({
   new_path: Schema.String
 });
 /**
- * Replace text in a file.
+ * Schema for the memory `str_replace` command.
+ *
+ * **When to use**
+ *
+ * Use when validating or constructing `str_replace` payloads for
+ * `Memory_20250818`.
+ *
+ * **Details**
+ *
+ * The payload is discriminated by `command: "str_replace"` and requires `path`,
+ * `old_str`, and `new_str`.
+ *
+ * @see {@link Memory_20250818} for the provider-defined tool that consumes this command
  *
  * @category Memory
  * @since 4.0.0
@@ -685,13 +1140,18 @@ export const MemoryStrReplaceCommand = /*#__PURE__*/Schema.Struct({
 /**
  * Shows directory contents or file contents with optional line ranges.
  *
+ * **Details**
+ *
+ * When used on a file, returns file contents optionally limited by `view_range`.
+ * When used on a directory, lists contents.
+ *
  * @category Memory
  * @since 4.0.0
  */
 export const MemoryViewCommand = /*#__PURE__*/Schema.Struct({
   command: /*#__PURE__*/Schema.Literal("view"),
   /**
-   * The path to the file to view.
+   * The path to the file or directory to view.
    */
   path: Schema.String,
   /**
@@ -730,10 +1190,19 @@ export const Memory_20250818 = /*#__PURE__*/Tool.providerDefined({
 /**
  * View the contents of a file or list directory contents.
  *
+ * **When to use**
+ *
+ * Use when validating or constructing the standalone Anthropic Text Editor
+ * `view` command.
+ *
  * **Details**
  *
  * When used on a file, returns the file contents, optionally limited to a line
  * range. When used on a directory, lists all files and subdirectories.
+ * `view_range` is a 1-indexed `[start, end]` tuple where `-1` means through
+ * the end of the file.
+ *
+ * @see {@link CodeExecutionTextEditorView} for the code-execution variant without `view_range`
  *
  * @category Text Editor
  * @since 4.0.0
@@ -753,6 +1222,16 @@ export const TextEditorViewCommand = /*#__PURE__*/Schema.Struct({
 /**
  * Create a new file with specified content.
  *
+ * **When to use**
+ *
+ * Use when validating or constructing an Anthropic text editor `create`
+ * command.
+ *
+ * **Details**
+ *
+ * The payload is discriminated by `command: "create"` and requires both `path`
+ * and `file_text`.
+ *
  * **Gotchas**
  *
  * Fails if the file already exists. Parent directories must exist.
@@ -774,11 +1253,24 @@ export const TextEditorCreateCommand = /*#__PURE__*/Schema.Struct({
 /**
  * Replace a specific string in a file with a new string.
  *
+ * **When to use**
+ *
+ * Use when validating or constructing standalone Anthropic text editor
+ * `str_replace` commands.
+ *
+ * **Details**
+ *
+ * The payload uses `command: "str_replace"`, `path`, `old_str`, and `new_str`.
+ * `new_str` may be empty to delete text.
+ *
  * **Gotchas**
  *
  * The `old_str` must match exactly (including whitespace and indentation)
  * and must be unique in the file.
  *
+ * @see {@link TextEditorViewCommand} for reading contents before choosing `old_str`
+ * @see {@link CodeExecutionTextEditorStrReplace} for the code-execution variant
+ *
  * @category Text Editor
  * @since 4.0.0
  */
@@ -802,7 +1294,8 @@ export const TextEditorStrReplaceCommand = /*#__PURE__*/Schema.Struct({
  *
  * **Details**
  *
- * Inserts the new text AFTER the specified line number.
+ * Inserts the new text after the specified line number. Use `0` to insert at
+ * the beginning of the file; other values are 1-indexed.
  *
  * @category Text Editor
  * @since 4.0.0
@@ -827,12 +1320,14 @@ export const TextEditorInsertCommand = /*#__PURE__*/Schema.Struct({
  *
  * **Details**
  *
- * Reverts the most recent str_replace, insert, or create operation on the file.
+ * Reverts the most recent `str_replace`, `insert`, or `create` operation on the
+ * file.
  *
  * **Gotchas**
  *
- * This command is available in text_editor_20241022 and text_editor_20250124,
- * but not in text_editor_20250728 (Claude 4 models).
+ * This command is available in `text_editor_20241022` and
+ * `text_editor_20250124`, but not in `text_editor_20250429` or
+ * `text_editor_20250728`.
  *
  * @category Text Editor
  * @since 4.0.0
@@ -862,9 +1357,18 @@ const TextEditor_StrReplaceBasedEdit_Args = /*#__PURE__*/Schema.Struct({
 /**
  * Text editor tool for Claude 3.5 Sonnet (deprecated).
  *
+ * **When to use**
+ *
+ * Use when configuring the 2024-10-22 `str_replace_editor` compatibility path
+ * for Claude 3.5 Sonnet.
+ *
  * **Details**
  *
- * Requires the "computer-use-2024-10-22" beta header.
+ * Requires the "computer-use-2024-10-22" beta header and supports `view`,
+ * `create`, `str_replace`, `insert`, and `undo_edit` commands.
+ *
+ * @see {@link TextEditor_20250124} for the newer `str_replace_editor` version
+ * @see {@link TextEditor_20250728} for the Claude 4 `str_replace_based_edit_tool` line
  *
  * @category Text Editor
  * @since 4.0.0
@@ -880,9 +1384,18 @@ export const TextEditor_20241022 = /*#__PURE__*/Tool.providerDefined({
 /**
  * Text editor tool for Claude Sonnet 3.7 (deprecated model).
  *
+ * **When to use**
+ *
+ * Use when configuring the 2025-01-24 Claude Sonnet 3.7 text editor tool using
+ * `str_replace_editor`.
+ *
  * **Details**
  *
- * Requires the "computer-use-2025-01-24" beta header.
+ * Requires the "computer-use-2025-01-24" beta header, requires a handler, and
+ * supports `view`, `create`, `str_replace`, `insert`, and `undo_edit` commands.
+ *
+ * @see {@link TextEditor_20241022} for the older `str_replace_editor` version
+ * @see {@link TextEditor_20250429} for the Claude 4 `str_replace_based_edit_tool` line
  *
  * @category Text Editor
  * @since 4.0.0
@@ -898,6 +1411,11 @@ export const TextEditor_20250124 = /*#__PURE__*/Tool.providerDefined({
 /**
  * Text editor tool for Claude 4 models using Anthropic's `str_replace_based_edit_tool`.
  *
+ * **When to use**
+ *
+ * Use when configuring the 2025-04-29 Claude 4 `str_replace_based_edit_tool`
+ * version.
+ *
  * **Details**
  *
  * Requires the "computer-use-2025-01-24" beta header.
@@ -906,6 +1424,9 @@ export const TextEditor_20250124 = /*#__PURE__*/Tool.providerDefined({
  *
  * This version does not support the `undo_edit` command.
  *
+ * @see {@link TextEditor_20250124} for the previous `str_replace_editor` version
+ * @see {@link TextEditor_20250728} for the later Claude 4 text editor version
+ *
  * @category Text Editor
  * @since 4.0.0
  */
@@ -921,6 +1442,11 @@ export const TextEditor_20250429 = /*#__PURE__*/Tool.providerDefined({
 /**
  * Text editor tool for Claude 4 models.
  *
+ * **Details**
+ *
+ * Uses Anthropic's `str_replace_based_edit_tool`. `max_characters` can limit
+ * file-view output for this version.
+ *
  * **Gotchas**
  *
  * This version does not support the `undo_edit` command.
@@ -948,8 +1474,16 @@ export const TextEditor_20250728 = /*#__PURE__*/Tool.providerDefined({
  *
  * **When to use**
  *
- * Providing location helps return more relevant results for location-dependent
- * queries like weather, local businesses, events, etc.
+ * Use when providing location helps return more relevant results for
+ * location-dependent queries like weather, local businesses, or events.
+ *
+ * **Details**
+ *
+ * The schema uses `type: "approximate"` plus optional `city`, `region`,
+ * `country`, and `timezone`. `country` is an ISO 3166-1 alpha-2 code, and
+ * `timezone` is an IANA time zone identifier.
+ *
+ * @see {@link WebSearch_20250305_Args} for the argument schema that consumes this location
  *
  * @category Web Search
  * @since 4.0.0
@@ -982,6 +1516,23 @@ export const WebSearchUserLocation = /*#__PURE__*/Schema.Struct({
 /**
  * Configuration arguments for the web search tool.
  *
+ * **When to use**
+ *
+ * Use when configuring `WebSearch_20250305` with search limits, domain filters,
+ * or user location.
+ *
+ * **Details**
+ *
+ * The payload can set `maxUses`, `allowedDomains`, `blockedDomains`, and
+ * `userLocation`.
+ *
+ * **Gotchas**
+ *
+ * `allowedDomains` and `blockedDomains` are mutually exclusive.
+ *
+ * @see {@link WebSearch_20250305} for the provider-defined tool that consumes these arguments
+ * @see {@link WebSearchUserLocation} for localizing search results
+ *
  * @category Web Search
  * @since 4.0.0
  */
@@ -1011,7 +1562,14 @@ export const WebSearch_20250305_Args = /*#__PURE__*/Schema.Struct({
 // Web Search Parameters
 // -----------------------------------------------------------------------------
 /**
- * Input parameters for a web search.
+ * Schema for Claude-supplied web search tool parameters.
+ *
+ * **Details**
+ *
+ * The payload contains the generated `query` string and is consumed by
+ * `WebSearch_20250305`.
+ *
+ * @see {@link WebSearch_20250305} for the provider-defined tool that consumes this payload
  *
  * @category Web Search
  * @since 4.0.0
@@ -1028,12 +1586,18 @@ export const WebSearchParameters = /*#__PURE__*/Schema.Struct({
 /**
  * Web search tool for Claude models.
  *
+ * **When to use**
+ *
+ * Use when Claude should search the web for real-time information.
+ *
  * **Details**
  *
  * Enables Claude to search the web for real-time information. This is a
  * server-side tool executed by Anthropic's infrastructure.
  * Generally available (no beta header required).
  *
+ * @see {@link WebFetch_20250910} for retrieving known URLs after discovery
+ *
  * @category Web Search
  * @since 4.0.0
  */
@@ -1055,6 +1619,17 @@ export const WebSearch_20250305 = /*#__PURE__*/Tool.providerDefined({
 /**
  * Citation configuration for web fetch.
  *
+ * **When to use**
+ *
+ * Use when configuring whether web fetch results should include citations.
+ *
+ * **Details**
+ *
+ * The payload contains the `enabled` flag. `citations` is optional on
+ * `WebFetch_20250910_Args`, and citations are disabled by default.
+ *
+ * @see {@link WebFetch_20250910_Args} for the argument schema that consumes this configuration
+ *
  * @category Web Fetch
  * @since 4.0.0
  */
@@ -1070,6 +1645,25 @@ export const WebFetchCitationsConfig = /*#__PURE__*/Schema.Struct({
 /**
  * Configuration arguments for the web fetch tool.
  *
+ * **When to use**
+ *
+ * Use when configuring `WebFetch_20250910` with usage limits, domain filters,
+ * citations, or content token limits.
+ *
+ * **Details**
+ *
+ * The payload can set `maxUses`, domain filters, `citations`, and
+ * `maxContentTokens`, which map to Anthropic web fetch request fields.
+ *
+ * **Gotchas**
+ *
+ * `allowedDomains` and `blockedDomains` are mutually exclusive.
+ * `maxContentTokens` is approximate and does not apply to binary content such
+ * as PDFs.
+ *
+ * @see {@link WebFetch_20250910} for the provider-defined tool that consumes these arguments
+ * @see {@link WebFetchCitationsConfig} for configuring citations
+ *
  * @category Web Fetch
  * @since 4.0.0
  */
@@ -1103,7 +1697,23 @@ export const WebFetch_20250910_Args = /*#__PURE__*/Schema.Struct({
 // Web Fetch Parameters
 // -----------------------------------------------------------------------------
 /**
- * Input parameters for a web fetch.
+ * Schema for Claude-supplied web fetch parameters.
+ *
+ * **When to use**
+ *
+ * Use when validating or constructing the `url` payload consumed by
+ * `WebFetch_20250910`.
+ *
+ * **Details**
+ *
+ * The payload contains the single `url` parameter for Anthropic web fetch.
+ *
+ * **Gotchas**
+ *
+ * The URL must be user-provided or from prior search/fetch results. Maximum URL
+ * length is 250 characters.
+ *
+ * @see {@link WebFetch_20250910} for the provider-defined tool that consumes this payload
  *
  * @category Web Fetch
  * @since 4.0.0
@@ -1121,11 +1731,17 @@ export const WebFetchParameters = /*#__PURE__*/Schema.Struct({
 /**
  * Web fetch tool for Claude models.
  *
+ * **When to use**
+ *
+ * Use when Claude should retrieve the content of a specific web page or PDF.
+ *
  * **Details**
  *
  * Allows Claude to retrieve full content from web pages and PDF documents.
- * This is a server-side tool executed by Anthropic's infrastructure.
- * Requires the "web-fetch-2025-09-10" beta header.
+ * This is a server-side tool executed by Anthropic's infrastructure. Selecting
+ * this tool adds the "web-fetch-2025-09-10" beta header.
+ *
+ * @see {@link WebSearch_20250305} for discovering URLs before fetching specific content
  *
  * @category Web Fetch
  * @since 4.0.0
@@ -1165,6 +1781,18 @@ export const ToolSearchRegexParameters = /*#__PURE__*/Schema.Struct({
 /**
  * Input parameters for BM25/natural language tool search.
  *
+ * **When to use**
+ *
+ * Use when validating or constructing the natural-language query payload for
+ * `ToolSearchBM25_20251119`.
+ *
+ * **Details**
+ *
+ * The payload contains Claude's natural-language `query`. BM25 searches tool
+ * names, descriptions, argument names, and argument descriptions.
+ *
+ * @see {@link ToolSearchBM25_20251119} for the provider-defined tool that consumes these parameters
+ *
  * @category Tool Search
  * @since 4.0.0
  */
@@ -1201,6 +1829,11 @@ export const ToolSearchRegex_20251119 = /*#__PURE__*/Tool.providerDefined({
 /**
  * BM25/natural language tool search for Claude models.
  *
+ * **When to use**
+ *
+ * Use when you want Claude to find relevant tools from a natural-language query
+ * instead of a regex pattern.
+ *
  * **Details**
  *
  * Claude uses natural language queries to search for tools using the
@@ -1208,6 +1841,8 @@ export const ToolSearchRegex_20251119 = /*#__PURE__*/Tool.providerDefined({
  * argument names, and argument descriptions.
  * Requires the "advanced-tool-use-2025-11-20" beta header.
  *
+ * @see {@link ToolSearchRegex_20251119} for the regex-pattern alternative
+ *
  * @category Tool Search
  * @since 4.0.0
  */