@effect/ai-anthropic 4.0.0-beta.9 → 4.0.0-beta.90

package/dist/AnthropicTool.d.ts

@@ -1,28 +1,49 @@
 /**
- * Anthropic provider-defined tools for use with the LanguageModel.
+ * The `AnthropicTool` module defines Anthropic provider tools and the schemas
+ * for their inputs and results. It covers Anthropic-owned tools such as Bash,
+ * Code Execution, Computer Use, Memory, Text Editor, Web Search, Web Fetch, and
+ * Tool Search, which can be attached to Anthropic-backed Effect AI language
+ * model requests.
  *
- * Provides tools that are natively supported by Anthropic's API, including
- * Bash, Code Execution, Computer Use, Memory, and Text Editor functionality.
- *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import * as Schema from "effect/Schema";
 import * as Tool from "effect/unstable/ai/Tool";
 /**
- * Union of all Anthropic provider-defined tools.
+ * Union of all Anthropic provider-defined tool definitions exported by this module.
+ *
+ * **When to use**
+ *
+ * Use when a helper, collection, or option accepts any Anthropic
+ * provider-defined tool value created by this module.
+ *
+ * **Details**
+ *
+ * The union is built from the return types of the exported constructors,
+ * including Bash, Code Execution, Computer Use, Memory, Text Editor, Tool
+ * Search, Web Fetch, and Web Search tool versions.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AnthropicTool = ReturnType<typeof Bash_20241022> | ReturnType<typeof Bash_20250124> | ReturnType<typeof CodeExecution_20250522> | ReturnType<typeof CodeExecution_20250825> | ReturnType<typeof ComputerUse_20241022> | ReturnType<typeof ComputerUse_20250124> | ReturnType<typeof ComputerUse_20251124> | ReturnType<typeof Memory_20250818> | ReturnType<typeof TextEditor_20241022> | ReturnType<typeof TextEditor_20250124> | ReturnType<typeof TextEditor_20250429> | ReturnType<typeof TextEditor_20250728> | ReturnType<typeof ToolSearchRegex_20251119> | ReturnType<typeof ToolSearchBM25_20251119> | ReturnType<typeof WebFetch_20250910> | ReturnType<typeof WebSearch_20250305>;
 /**
- * Anthropic Bash tool (2024-10-22 version).
+ * Defines the Anthropic Bash tool (2024-10-22 version).
+ *
+ * **When to use**
+ *
+ * Use when you want the model to execute bash commands with the 2024-10-22
+ * 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.
  *
- * @since 1.0.0
+ * @see {@link Bash_20250124} for the newer 2025-01-24 version of the bash tool
+ *
  * @category Bash
+ * @since 4.0.0
  */
 export declare const Bash_20241022: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly failureMode?: Mode | undefined;
@@ -37,13 +58,22 @@ export declare const Bash_20241022: <Mode extends Tool.FailureMode | undefined =
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, true>;
 /**
- * Anthropic Bash tool (2025-01-24 version).
+ * Defines the Anthropic Bash tool (2025-01-24 version).
+ *
+ * **When to use**
+ *
+ * Use when you want the model to execute bash commands with the 2025-01-24
+ * 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.
  *
- * @since 1.0.0
+ * @see {@link Bash_20241022} for the older 2024-10-22 version of the bash tool
+ *
  * @category Bash
+ * @since 4.0.0
  */
 export declare const Bash_20250124: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly failureMode?: Mode | undefined;
@@ -58,10 +88,17 @@ export declare const Bash_20250124: <Mode extends Tool.FailureMode | undefined =
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, true>;
 /**
- * Programmatic tool call execution parameter.
+ * 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
  *
- * @since 1.0.0
  * @category Code Execution
+ * @since 4.0.0
  */
 export declare const CodeExecutionProgrammaticToolCall: Schema.Struct<{
     readonly type: Schema.Literal<"programmatic-tool-call">;
@@ -71,15 +108,29 @@ export declare const CodeExecutionProgrammaticToolCall: Schema.Struct<{
     readonly code: Schema.String;
 }>;
 /**
- * @since 1.0.0
+ * Input payload for a programmatic code execution tool call, including the source code to execute.
+ *
  * @category Code Execution
+ * @since 4.0.0
  */
 export type CodeExecutionProgrammaticToolCall = typeof CodeExecutionProgrammaticToolCall.Type;
 /**
- * Bash code execution parameter.
+ * 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
  *
- * @since 1.0.0
  * @category Code Execution
+ * @since 4.0.0
  */
 export declare const CodeExecutionBashCommand: Schema.Struct<{
     readonly type: Schema.Literal<"bash_code_execution">;
@@ -89,15 +140,47 @@ export declare const CodeExecutionBashCommand: Schema.Struct<{
     readonly command: Schema.String;
 }>;
 /**
- * @since 1.0.0
+ * Input payload for a bash command routed through the Anthropic code execution tool.
+ *
+ * **When to use**
+ *
+ * Use when representing a provider-executed bash command request for the
+ * 2025-05-22 code execution tool.
+ *
+ * **Details**
+ *
+ * The payload uses `type: "bash_code_execution"` to distinguish bash execution
+ * from programmatic code and text editor operations, and `command` contains the
+ * bash command to run.
+ *
+ * @see {@link CodeExecutionProgrammaticToolCall} for programmatic code execution input
+ * @see {@link CodeExecutionTextEditorView} for viewing files through text editor code execution
+ * @see {@link CodeExecutionTextEditorCreate} for creating files through text editor code execution
+ * @see {@link CodeExecutionTextEditorStrReplace} for replacing text through text editor code execution
+ * @see {@link CodeExecution_20250522} for the provider-defined tool that consumes this payload
+ *
  * @category Code Execution
+ * @since 4.0.0
  */
 export type CodeExecutionBashCommand = typeof CodeExecutionBashCommand.Type;
 /**
- * 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 when you need the schema for provider-bound code-execution view requests
+ * before distinguishing them from create or replace text-editor commands.
+ *
+ * **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
  *
- * @since 1.0.0
  * @category Code Execution
+ * @since 4.0.0
  */
 export declare const CodeExecutionTextEditorView: Schema.Struct<{
     readonly type: Schema.Literal<"text_editor_code_execution">;
@@ -108,15 +191,51 @@ export declare const CodeExecutionTextEditorView: Schema.Struct<{
     readonly path: Schema.String;
 }>;
 /**
- * @since 1.0.0
+ * Input payload for the `view` command of Anthropic's text editor code execution tool.
+ *
+ * **When to use**
+ *
+ * Use when working at the Anthropic protocol boundary and the code-execution
+ * view request must be distinguished from standalone text-editor view requests.
+ *
+ * **Details**
+ *
+ * The payload is discriminated by `type: "text_editor_code_execution"` and
+ * `command: "view"`. The `path` field identifies the file to view.
+ *
+ * **Gotchas**
+ *
+ * This code execution view payload does not include `view_range`; line ranges
+ * are part of the standalone text editor view payload, not this code execution
+ * payload.
+ *
+ * @see {@link CodeExecution_20250522} for the provider-defined code execution tool that includes this payload
+ * @see {@link TextEditorViewCommand} for the standalone text editor view payload
+ *
  * @category Code Execution
+ * @since 4.0.0
  */
 export type CodeExecutionTextEditorView = typeof CodeExecutionTextEditorView.Type;
 /**
- * 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
  *
- * @since 1.0.0
  * @category Code Execution
+ * @since 4.0.0
  */
 export declare const CodeExecutionTextEditorCreate: Schema.Struct<{
     readonly type: Schema.Literal<"text_editor_code_execution">;
@@ -131,15 +250,30 @@ export declare const CodeExecutionTextEditorCreate: Schema.Struct<{
     readonly file_text: Schema.optional<Schema.NullOr<Schema.String>>;
 }>;
 /**
- * @since 1.0.0
+ * Input payload for creating a file through the text editor code execution tool, optionally including initial file text.
+ *
  * @category Code Execution
+ * @since 4.0.0
  */
 export type CodeExecutionTextEditorCreate = typeof CodeExecutionTextEditorCreate.Type;
 /**
- * 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
  *
- * @since 1.0.0
  * @category Code Execution
+ * @since 4.0.0
  */
 export declare const CodeExecutionTextEditorStrReplace: Schema.Struct<{
     readonly type: Schema.Literal<"text_editor_code_execution">;
@@ -158,15 +292,24 @@ export declare const CodeExecutionTextEditorStrReplace: Schema.Struct<{
     readonly new_str: Schema.String;
 }>;
 /**
- * @since 1.0.0
+ * Input payload for replacing text in a file through the text editor code execution tool.
+ *
  * @category Code Execution
+ * @since 4.0.0
  */
 export type CodeExecutionTextEditorStrReplace = typeof CodeExecutionTextEditorStrReplace.Type;
 /**
- * Simple code execution parameter.
+ * Schema for the 2025-08-25 code execution tool input, containing the code to execute.
+ *
+ * **When to use**
+ *
+ * Use when you need the schema for code-execution input at the Anthropic
+ * protocol boundary before sending source code to the 2025-08-25 tool.
+ *
+ * @see {@link CodeExecution_20250825} for the provider-defined tool that consumes this schema
  *
- * @since 1.0.0
  * @category Code Execution
+ * @since 4.0.0
  */
 export declare const CodeExecution_20250825_Parameters: Schema.Struct<{
     /**
@@ -175,19 +318,42 @@ export declare const CodeExecution_20250825_Parameters: Schema.Struct<{
     readonly code: Schema.String;
 }>;
 /**
- * @since 1.0.0
+ * Input payload for the 2025-08-25 Anthropic code execution tool.
+ *
+ * **When to use**
+ *
+ * Use when exposing the 2025-08-25 code-execution payload separately from the
+ * provider tool definition, such as at a transport or persistence boundary.
+ *
+ * **Details**
+ *
+ * The payload has a single `code` field containing the source code string to
+ * execute.
+ *
+ * @see {@link CodeExecution_20250825} for the provider-defined tool that consumes this payload
+ *
  * @category Code Execution
+ * @since 4.0.0
  */
 export type CodeExecution_20250825_Parameters = typeof CodeExecution_20250825_Parameters.Type;
 /**
- * Anthropic Code Execution tool (2025-05-22 version).
+ * Defines the Anthropic Code Execution tool (2025-05-22 version).
+ *
+ * **When to use**
+ *
+ * Use when you want the model to execute code in a sandboxed environment with
+ * the 2025-05-22 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.
  *
- * @since 1.0.0
+ * @see {@link CodeExecutionProgrammaticToolCall} for the programmatic tool call schema
+ *
  * @category Code Execution
+ * @since 4.0.0
  */
 export declare const CodeExecution_20250522: <Mode extends Tool.FailureMode | undefined = undefined>(args: void) => Tool.ProviderDefined<"anthropic.code_execution_20250522", "AnthropicCodeExecution", {
     readonly args: Schema.Void;
@@ -254,12 +420,23 @@ export declare const CodeExecution_20250522: <Mode extends Tool.FailureMode | un
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * Anthropic Code Execution tool (2025-08-25 version).
+ * Defines the Anthropic Code Execution tool (2025-08-25 version).
+ *
+ * **When to use**
+ *
+ * Use when you want the model to execute code in a sandboxed environment with
+ * the 2025-08-25 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
  *
- * @since 1.0.0
  * @category Code Execution
+ * @since 4.0.0
  */
 export declare const CodeExecution_20250825: <Mode extends Tool.FailureMode | undefined = undefined>(args: void) => Tool.ProviderDefined<"anthropic.code_execution_20250825", "AnthropicCodeExecution", {
     readonly args: Schema.Void;
@@ -319,58 +496,113 @@ export declare const CodeExecution_20250825: <Mode extends Tool.FailureMode | un
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * An `[x, y]` pixel position.
+ * Schema for an `[x, y]` screen coordinate in pixels.
+ *
+ * **When to use**
+ *
+ * Use when validating computer-use action payloads that carry a single screen
+ * position and provider-side bounds checks remain acceptable.
+ *
+ * **Details**
+ *
+ * This is a two-number tuple used by computer-use actions that accept screen
+ * positions.
+ *
+ * **Gotchas**
  *
- * @since 1.0.0
- * @category Computer Use
+ * This schema validates tuple shape only and does not check display bounds.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export declare const Coordinate: Schema.Tuple<readonly [Schema.Number, Schema.Number]>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * An `[x, y]` screen coordinate in pixels.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type Coordinate = typeof Coordinate.Type;
 /**
- * A `[x1, y1, x2, y2]` position defining top-left and bottom-right corners.
+ * Schema for an `[x1, y1, x2, y2]` screen region in pixels.
+ *
+ * **When to use**
+ *
+ * Use when validating computer-use action payloads that carry a rectangular
+ * screen region and provider-side bounds checks remain acceptable.
+ *
+ * **Details**
+ *
+ * The tuple represents top-left and bottom-right corners.
+ *
+ * **Gotchas**
  *
- * @since 1.0.0
- * @category Computer Use
+ * This schema validates four numbers only and does not check coordinate ordering
+ * or display bounds.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export declare const Region: Schema.Tuple<readonly [Schema.Number, Schema.Number, Schema.Number, Schema.Number]>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * An `[x1, y1, x2, y2]` screen region in pixels, from top-left to bottom-right.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type Region = typeof Region.Type;
 /**
- * The direction of the scroll for scroll actions.
+ * Schema for scroll direction literals: `"up"`, `"down"`, `"left"`, or `"right"`.
+ *
+ * @see {@link ComputerUseScrollAction} for the action payload that consumes this schema
  *
- * @since 1.0.0
- * @category Computer Use
+ * @category computer use
+ * @since 4.0.0
  */
 export declare const ScrollDirection: Schema.Literals<readonly ["up", "down", "left", "right"]>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * Direction used by computer-use scroll actions: `"up"`, `"down"`, `"left"`, or `"right"`.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type ScrollDirection = typeof ScrollDirection.Type;
 /**
- * Modifier keys that can be held during click/scroll actions.
+ * Schema for modifier key literals.
+ *
+ * **Details**
+ *
+ * Allowed values are `"alt"`, `"ctrl"`, `"meta"`, and `"shift"`.
  *
- * @since 1.0.0
- * @category Computer Use
+ * @category computer use
+ * @since 4.0.0
  */
 export declare const ModifierKey: Schema.Literals<readonly ["alt", "ctrl", "meta", "shift"]>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * Modifier key literals.
+ *
+ * **Details**
+ *
+ * Allowed values are `"alt"`, `"ctrl"`, `"meta"`, and `"shift"`.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type ModifierKey = typeof ModifierKey.Type;
 /**
- * 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
  *
- * @since 1.0.0
- * @category Computer Use
+ * @category computer use
+ * @since 4.0.0
  */
 export declare const ComputerUseKeyAction: Schema.Struct<{
     readonly action: Schema.Literal<"key">;
@@ -380,15 +612,53 @@ export declare const ComputerUseKeyAction: Schema.Struct<{
     readonly text: Schema.String;
 }>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * Computer-use action payload for pressing a key or key combination.
+ *
+ * **When to use**
+ *
+ * Use when typing parsed computer-use key action payloads after schema
+ * validation, where provider-specific key-name validation is handled outside
+ * TypeScript.
+ *
+ * **Details**
+ *
+ * The payload uses `action: "key"` and stores the key or key combination to
+ * press in `text`, such as `"Return"`, `"ctrl+c"`, or `"ctrl+s"`.
+ *
+ * **Gotchas**
+ *
+ * `text` is typed as `string`; the paired schema does not validate
+ * provider-specific key names or key combinations.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type ComputerUseKeyAction = typeof ComputerUseKeyAction.Type;
 /**
- * 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.
  *
- * @since 1.0.0
- * @category Computer Use
+ * @see {@link ComputerUseDoubleClickAction} for performing a double click
+ * @see {@link ComputerUseMouseMoveAction} for moving the mouse without clicking
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export declare const ComputerUseLeftClickAction: Schema.Struct<{
     readonly action: Schema.Literal<"left_click">;
@@ -399,15 +669,34 @@ export declare const ComputerUseLeftClickAction: Schema.Struct<{
     readonly coordinate: Schema.optional<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>;
 }>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * Computer-use action payload for performing a left click, optionally at a specific coordinate.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type ComputerUseLeftClickAction = typeof ComputerUseLeftClickAction.Type;
 /**
- * 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.
  *
- * @since 1.0.0
- * @category Computer Use
+ * **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
  */
 export declare const ComputerUseMouseMoveAction: Schema.Struct<{
     readonly action: Schema.Literal<"mouse_move">;
@@ -417,29 +706,57 @@ export declare const ComputerUseMouseMoveAction: Schema.Struct<{
     readonly coordinate: Schema.Tuple<readonly [Schema.Number, Schema.Number]>;
 }>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * Computer-use action payload for moving the mouse cursor to a specific coordinate.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type ComputerUseMouseMoveAction = typeof ComputerUseMouseMoveAction.Type;
 /**
- * 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**
  *
- * @since 1.0.0
- * @category Computer Use
+ * 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
  */
 export declare const ComputerUseScreenshotAction: Schema.Struct<{
     readonly action: Schema.Literal<"screenshot">;
 }>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * Computer-use action payload for capturing the current display.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type ComputerUseScreenshotAction = typeof ComputerUseScreenshotAction.Type;
 /**
- * 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**
  *
- * @since 1.0.0
- * @category Computer Use
+ * 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
  */
 export declare const TypeAction: Schema.Struct<{
     readonly action: Schema.Literal<"type">;
@@ -449,15 +766,41 @@ export declare const TypeAction: Schema.Struct<{
     readonly text: Schema.String;
 }>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * Computer-use action payload for typing a text string.
+ *
+ * **Details**
+ *
+ * The payload uses `action: "type"` and a `text` string containing the text to
+ * enter.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type TypeAction = typeof TypeAction.Type;
 /**
- * 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.
  *
- * @since 1.0.0
- * @category Computer Use
+ * **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
  */
 export declare const ComputerUseDoubleClickAction: Schema.Struct<{
     readonly action: Schema.Literal<"double_click">;
@@ -468,15 +811,36 @@ export declare const ComputerUseDoubleClickAction: Schema.Struct<{
     readonly coordinate: Schema.optional<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>;
 }>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * Computer-use action payload for performing a double click, optionally at a specific coordinate.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type ComputerUseDoubleClickAction = typeof ComputerUseDoubleClickAction.Type;
 /**
- * Holds a key while performing other actions.
+ * Keeps a key pressed for a specified duration during computer-use execution.
  *
- * @since 1.0.0
- * @category Computer Use
+ * **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
  */
 export declare const ComputerUseHoldKeyAction: Schema.Struct<{
     readonly action: Schema.Literal<"hold_key">;
@@ -490,15 +854,47 @@ export declare const ComputerUseHoldKeyAction: Schema.Struct<{
     readonly duration: Schema.Number;
 }>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * Computer-use action payload for holding a key for a specified duration.
+ *
+ * **When to use**
+ *
+ * Use to represent a key that should remain pressed for a measured interval.
+ *
+ * **Details**
+ *
+ * Set `action` to `"hold_key"`, `text` to the key to hold, and `duration` to
+ * the number of seconds to hold it.
+ *
+ * @see {@link ComputerUseKeyAction} for a single key press or key combination without a hold duration
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type ComputerUseHoldKeyAction = typeof ComputerUseHoldKeyAction.Type;
 /**
- * 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.
  *
- * @since 1.0.0
- * @category Computer Use
+ * @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
  */
 export declare const ComputerUseLeftClickDragAction: Schema.Struct<{
     readonly action: Schema.Literal<"left_click_drag">;
@@ -512,17 +908,22 @@ export declare const ComputerUseLeftClickDragAction: Schema.Struct<{
     readonly coordinate: Schema.Tuple<readonly [Schema.Number, Schema.Number]>;
 }>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * Computer-use action payload for dragging from a start coordinate to an end coordinate.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type ComputerUseLeftClickDragAction = typeof ComputerUseLeftClickDragAction.Type;
 /**
- * Press the left mouse button down (without releasing).
+ * Starts a left mouse button press without releasing it.
+ *
+ * **When to use**
  *
- * Used for fine-grained click control.
+ * Use when constructing a manual click or drag sequence that should press and
+ * hold the left mouse button before a later release.
  *
- * @since 1.0.0
- * @category Computer Use
+ * @category computer use
+ * @since 4.0.0
  */
 export declare const ComputerUseLeftMouseDownAction: Schema.Struct<{
     readonly action: Schema.Literal<"left_mouse_down">;
@@ -533,17 +934,22 @@ export declare const ComputerUseLeftMouseDownAction: Schema.Struct<{
     readonly coordinate: Schema.optional<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>;
 }>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * Computer-use action payload for pressing and holding the left mouse button, optionally at a specific coordinate.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type ComputerUseLeftMouseDownAction = typeof ComputerUseLeftMouseDownAction.Type;
 /**
- * Release the left mouse button.
+ * Releases the left mouse button.
+ *
+ * **When to use**
  *
- * Used for fine-grained click control.
+ * Use when constructing a manual click or drag sequence that should release the
+ * left mouse button after it was previously held down.
  *
- * @since 1.0.0
- * @category Computer Use
+ * @category computer use
+ * @since 4.0.0
  */
 export declare const ComputerUseLeftMouseUpAction: Schema.Struct<{
     readonly action: Schema.Literal<"left_mouse_up">;
@@ -554,15 +960,36 @@ export declare const ComputerUseLeftMouseUpAction: Schema.Struct<{
     readonly coordinate: Schema.optional<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>;
 }>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * Computer-use action payload for releasing the left mouse button, optionally at a specific coordinate.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type ComputerUseLeftMouseUpAction = typeof ComputerUseLeftMouseUpAction.Type;
 /**
- * Perform a middle click.
+ * Schema for a computer-use action that performs a middle click.
  *
- * @since 1.0.0
- * @category Computer Use
+ * **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
  */
 export declare const ComputerUseMiddleClickAction: Schema.Struct<{
     readonly action: Schema.Literal<"middle_click">;
@@ -573,15 +1000,32 @@ export declare const ComputerUseMiddleClickAction: Schema.Struct<{
     readonly coordinate: Schema.optional<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>;
 }>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * Computer-use action payload for performing a middle click, optionally at a specific coordinate.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type ComputerUseMiddleClickAction = typeof ComputerUseMiddleClickAction.Type;
 /**
- * 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.
  *
- * @since 1.0.0
- * @category Computer Use
+ * @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
  */
 export declare const ComputerUseRightClickAction: Schema.Struct<{
     readonly action: Schema.Literal<"right_click">;
@@ -592,15 +1036,34 @@ export declare const ComputerUseRightClickAction: Schema.Struct<{
     readonly coordinate: Schema.optional<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>;
 }>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * Computer-use action payload for performing a right click, optionally at a specific coordinate.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type ComputerUseRightClickAction = typeof ComputerUseRightClickAction.Type;
 /**
- * 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`.
  *
- * @since 1.0.0
- * @category Computer Use
+ * **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
  */
 export declare const ComputerUseScrollAction: Schema.Struct<{
     readonly action: Schema.Literal<"scroll">;
@@ -619,15 +1082,36 @@ export declare const ComputerUseScrollAction: Schema.Struct<{
     readonly scroll_amount: Schema.Number;
 }>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * Computer-use action payload for scrolling by a specified amount in a specified direction, optionally from a coordinate.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type ComputerUseScrollAction = typeof ComputerUseScrollAction.Type;
 /**
- * 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.
  *
- * @since 1.0.0
- * @category Computer Use
+ * **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
  */
 export declare const ComputerUseTripleClickAction: Schema.Struct<{
     readonly action: Schema.Literal<"triple_click">;
@@ -638,15 +1122,35 @@ export declare const ComputerUseTripleClickAction: Schema.Struct<{
     readonly coordinate: Schema.optional<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>;
 }>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * Computer-use action payload for performing a triple click, optionally at a specific coordinate.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type ComputerUseTripleClickAction = typeof ComputerUseTripleClickAction.Type;
 /**
- * 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.
  *
- * @since 1.0.0
- * @category Computer Use
+ * @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
  */
 export declare const ComputerUseWaitAction: Schema.Struct<{
     readonly action: Schema.Literal<"wait">;
@@ -656,17 +1160,34 @@ export declare const ComputerUseWaitAction: Schema.Struct<{
     readonly duration: Schema.Number;
 }>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * Computer-use action payload for pausing for a specified duration.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type ComputerUseWaitAction = typeof ComputerUseWaitAction.Type;
 /**
- * Zoom into a specific region of the screen at full resolution.
+ * Zooms into a specific region of the screen at full resolution.
+ *
+ * **When to use**
+ *
+ * Use when building or validating the 2025-11-24 computer-use action for a
+ * zoom-enabled tool definition.
+ *
+ * **Details**
+ *
+ * The encoded payload uses `action: "zoom"` and a `region` tuple.
+ *
+ * **Gotchas**
  *
- * Requires `enableZoom: true` in the tool definition.
+ * Requires `enableZoom: true` in the tool definition. `region` is only a
+ * four-number tuple and does not validate corner ordering or display bounds.
  *
- * @since 1.0.0
- * @category Computer Use
+ * @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
  */
 export declare const ComputerUseZoomAction: Schema.Struct<{
     readonly action: Schema.Literal<"zoom">;
@@ -677,19 +1198,28 @@ export declare const ComputerUseZoomAction: Schema.Struct<{
     readonly region: Schema.Tuple<readonly [Schema.Number, Schema.Number, Schema.Number, Schema.Number]>;
 }>;
 /**
- * @since 1.0.0
- * @category Computer Use
+ * Computer-use action payload for zooming into a specific screen region.
+ *
+ * **Gotchas**
+ *
+ * The enclosing computer-use tool must be configured with `enableZoom: true`.
+ * `region` is only a four-number tuple and does not validate corner ordering or
+ * display bounds.
+ *
+ * @category computer use
+ * @since 4.0.0
  */
 export type ComputerUseZoomAction = typeof ComputerUseZoomAction.Type;
 /**
- * Computer use tool for Claude 3.5 Sonnet v2 (deprecated).
+ * Defines the deprecated computer-use tool for Claude 3.5 Sonnet v2.
  *
- * Requires the "computer-use-2024-10-22" beta header.
+ * **Details**
  *
+ * Requires the "computer-use-2024-10-22" beta header.
  * Basic actions only: screenshot, left_click, type, key, mouse_move.
  *
- * @since 1.0.0
- * @category Computer Use
+ * @category computer use
+ * @since 4.0.0
  */
 export declare const ComputerUse_20241022: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly displayWidthPx: number;
@@ -746,16 +1276,25 @@ export declare const ComputerUse_20241022: <Mode extends Tool.FailureMode | unde
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, true>;
 /**
- * Computer use tool for Claude 4 models and Claude Sonnet 3.7.
+ * Defines the computer-use tool for Claude 4 models and Claude Sonnet 3.7.
  *
- * Requires the "computer-use-2025-01-24" beta header.
+ * **When to use**
+ *
+ * Use when you need 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.
  * Includes basic actions plus enhanced actions: scroll, left_click_drag,
  * right_click, middle_click, double_click, triple_click, left_mouse_down,
  * left_mouse_up, hold_key, wait.
  *
- * @since 1.0.0
- * @category Computer Use
+ * @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
  */
 export declare const ComputerUse_20250124: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly displayWidthPx: number;
@@ -895,15 +1434,28 @@ export declare const ComputerUse_20250124: <Mode extends Tool.FailureMode | unde
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, true>;
 /**
- * Computer use tool for Claude Opus 4.5 only.
+ * Defines the computer-use tool for Claude Opus 4.5 only.
  *
- * Requires the "computer-use-2025-11-24" beta header.
+ * **When to use**
  *
+ * Use when you need 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
  *
- * @since 1.0.0
- * @category Computer Use
+ * @category computer use
+ * @since 4.0.0
  */
 export declare const ComputerUse_20251124: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly displayWidthPx: number;
@@ -1052,27 +1604,46 @@ export declare const ComputerUse_20251124: <Mode extends Tool.FailureMode | unde
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, true>;
 /**
- * A `[start, end]` line range for viewing file contents.
+ * Defines a `[start, end]` line range for viewing file contents.
  *
- * Lines are 1-indexed. Use -1 for end to read to end of file.
+ * **When to use**
  *
- * @example [1, 50]    // View lines 1-50
- * @example [100, -1]  // View from line 100 to end of file
+ * Use when constructing or validating `view_range` for memory or text editor
+ * view commands.
  *
- * @since 1.0.0
- * @category Memory
+ * **Details**
+ *
+ * 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
  */
 export declare const ViewRange: Schema.Tuple<readonly [Schema.Number, Schema.Number]>;
 /**
- * @since 1.0.0
- * @category Memory
+ * 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.
+ *
+ * **When to use**
+ *
+ * Use when typing `view_range` for memory or text editor view commands.
+ *
+ * @category memory
+ * @since 4.0.0
  */
 export type ViewRange = typeof ViewRange.Type;
 /**
- * Creates a new file.
+ * Schema for the memory tool command that creates a new file at a path.
+ *
+ * **Details**
  *
- * @since 1.0.0
- * @category Memory
+ * The payload contains `command: "create"` and a `path` string.
+ *
+ * @category memory
+ * @since 4.0.0
  */
 export declare const MemoryCreateCommand: Schema.Struct<{
     readonly command: Schema.Literal<"create">;
@@ -1082,33 +1653,49 @@ export declare const MemoryCreateCommand: Schema.Struct<{
     readonly path: Schema.String;
 }>;
 /**
- * @since 1.0.0
- * @category Memory
+ * Memory tool command payload for creating a new file at a path.
+ *
+ * @category memory
+ * @since 4.0.0
  */
 export type MemoryCreateCommand = typeof MemoryCreateCommand.Type;
 /**
- * Delete a file or directory.
+ * Schema for a memory command that deletes a file or directory.
  *
- * @since 1.0.0
- * @category Memory
+ * @category memory
+ * @since 4.0.0
  */
 export declare const MemoryDeleteCommand: Schema.Struct<{
     readonly command: Schema.Literal<"delete">;
     /**
-     * The path to the file to delete.
+     * The path to the file or directory to delete.
      */
     readonly path: Schema.String;
 }>;
 /**
- * @since 1.0.0
- * @category Memory
+ * Memory tool command payload for deleting a file or directory at a path.
+ *
+ * @category memory
+ * @since 4.0.0
  */
 export type MemoryDeleteCommand = typeof MemoryDeleteCommand.Type;
 /**
- * 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**
  *
- * @since 1.0.0
- * @category Memory
+ * 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
  */
 export declare const MemoryInsertCommand: Schema.Struct<{
     readonly command: Schema.Literal<"insert">;
@@ -1126,15 +1713,22 @@ export declare const MemoryInsertCommand: Schema.Struct<{
     readonly insert_text: Schema.String;
 }>;
 /**
- * @since 1.0.0
- * @category Memory
+ * Memory tool command payload for inserting text at a specific line in a file.
+ *
+ * @category memory
+ * @since 4.0.0
  */
 export type MemoryInsertCommand = typeof MemoryInsertCommand.Type;
 /**
- * Rename or move a file or directory.
+ * Schema for the memory command that renames or moves a file or directory.
  *
- * @since 1.0.0
- * @category Memory
+ * **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
  */
 export declare const MemoryRenameCommand: Schema.Struct<{
     readonly command: Schema.Literal<"rename">;
@@ -1148,15 +1742,29 @@ export declare const MemoryRenameCommand: Schema.Struct<{
     readonly new_path: Schema.String;
 }>;
 /**
- * @since 1.0.0
- * @category Memory
+ * Memory tool command payload for renaming or moving a file or directory.
+ *
+ * @category memory
+ * @since 4.0.0
  */
 export type MemoryRenameCommand = typeof MemoryRenameCommand.Type;
 /**
- * Replace text in a file.
+ * Schema for the memory `str_replace` command.
  *
- * @since 1.0.0
- * @category Memory
+ * **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
  */
 export declare const MemoryStrReplaceCommand: Schema.Struct<{
     readonly command: Schema.Literal<"str_replace">;
@@ -1174,20 +1782,27 @@ export declare const MemoryStrReplaceCommand: Schema.Struct<{
     readonly new_str: Schema.String;
 }>;
 /**
- * @since 1.0.0
- * @category Memory
+ * Memory tool command payload for replacing text in a file.
+ *
+ * @category memory
+ * @since 4.0.0
  */
 export type MemoryStrReplaceCommand = typeof MemoryStrReplaceCommand.Type;
 /**
  * Shows directory contents or file contents with optional line ranges.
  *
- * @since 1.0.0
- * @category Memory
+ * **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 declare const MemoryViewCommand: Schema.Struct<{
     readonly command: Schema.Literal<"view">;
     /**
-     * The path to the file to view.
+     * The path to the file or directory to view.
      */
     readonly path: Schema.String;
     /**
@@ -1196,18 +1811,22 @@ export declare const MemoryViewCommand: Schema.Struct<{
     readonly view_range: Schema.optional<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>;
 }>;
 /**
- * @since 1.0.0
- * @category Memory
+ * Memory tool command payload for viewing a file or directory, optionally with a file line range.
+ *
+ * @category memory
+ * @since 4.0.0
  */
 export type MemoryViewCommand = typeof MemoryViewCommand.Type;
 /**
- * Memory tool for persistent file operations across conversations.
+ * Defines the memory tool for persistent file operations across conversations.
+ *
+ * **Details**
  *
  * Provides commands for creating, viewing, editing, renaming, and deleting
  * files within the model's memory space.
  *
- * @since 1.0.0
- * @category Memory
+ * @category memory
+ * @since 4.0.0
  */
 export declare const Memory_20250818: <Mode extends Tool.FailureMode | undefined = undefined>(args: void) => Tool.ProviderDefined<"anthropic.memory_20250818", "AnthropicMemory", {
     readonly args: Schema.Void;
@@ -1220,7 +1839,7 @@ export declare const Memory_20250818: <Mode extends Tool.FailureMode | undefined
     }>, Schema.Struct<{
         readonly command: Schema.Literal<"delete">;
         /**
-         * The path to the file to delete.
+         * The path to the file or directory to delete.
          */
         readonly path: Schema.String;
     }>, Schema.Struct<{
@@ -1264,7 +1883,7 @@ export declare const Memory_20250818: <Mode extends Tool.FailureMode | undefined
     }>, Schema.Struct<{
         readonly command: Schema.Literal<"view">;
         /**
-         * The path to the file to view.
+         * The path to the file or directory to view.
          */
         readonly path: Schema.String;
         /**
@@ -1277,13 +1896,24 @@ export declare const Memory_20250818: <Mode extends Tool.FailureMode | undefined
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * View the contents of a file or list directory contents.
+ * Reads the contents of a file or lists 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.
+ * 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.
  *
- * @since 1.0.0
- * @category Text Editor
+ * @see {@link CodeExecutionTextEditorView} for the code-execution variant without `view_range`
+ *
+ * @category text editor
+ * @since 4.0.0
  */
 export declare const TextEditorViewCommand: Schema.Struct<{
     readonly command: Schema.Literal<"view">;
@@ -1298,17 +1928,36 @@ export declare const TextEditorViewCommand: Schema.Struct<{
     readonly view_range: Schema.optional<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>;
 }>;
 /**
- * @since 1.0.0
- * @category Text Editor
+ * Text editor command payload for viewing file contents or listing directory contents.
+ *
+ * **Details**
+ *
+ * `view_range` is a 1-indexed `[start, end]` tuple where `-1` means through
+ * the end of the file.
+ *
+ * @category text editor
+ * @since 4.0.0
  */
 export type TextEditorViewCommand = typeof TextEditorViewCommand.Type;
 /**
  * Create a new file with specified content.
  *
- * Will fail if the file already exists. Parent directories must exist.
+ * **When to use**
+ *
+ * Use when validating or constructing an Anthropic text editor `create`
+ * command.
+ *
+ * **Details**
  *
- * @since 1.0.0
- * @category Text Editor
+ * 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.
+ *
+ * @category text editor
+ * @since 4.0.0
  */
 export declare const TextEditorCreateCommand: Schema.Struct<{
     readonly command: Schema.Literal<"create">;
@@ -1322,18 +1971,44 @@ export declare const TextEditorCreateCommand: Schema.Struct<{
     readonly file_text: Schema.String;
 }>;
 /**
- * @since 1.0.0
- * @category Text Editor
+ * Text editor command payload for creating a new file with the specified content.
+ *
+ * **When to use**
+ *
+ * Use when typing parsed text-editor create command payloads after schema
+ * validation and before dispatching to Anthropic tool handlers.
+ *
+ * **Gotchas**
+ *
+ * The command fails if the file already exists or if parent directories are missing.
+ *
+ * @category text editor
+ * @since 4.0.0
  */
 export type TextEditorCreateCommand = typeof TextEditorCreateCommand.Type;
 /**
- * Replace a specific string in a file with a new string.
+ * Replaces 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.
  *
- * @since 1.0.0
- * @category Text Editor
+ * @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
  */
 export declare const TextEditorStrReplaceCommand: Schema.Struct<{
     readonly command: Schema.Literal<"str_replace">;
@@ -1351,17 +2026,32 @@ export declare const TextEditorStrReplaceCommand: Schema.Struct<{
     readonly new_str: Schema.String;
 }>;
 /**
- * @since 1.0.0
- * @category Text Editor
+ * Text editor command payload for replacing one exact, unique string in a file.
+ *
+ * **When to use**
+ *
+ * Use when typing parsed text-editor replace command payloads that must carry
+ * one exact `old_str` match.
+ *
+ * **Gotchas**
+ *
+ * The `old_str` must match exactly, including whitespace and indentation, and
+ * must be unique in the file.
+ *
+ * @category text editor
+ * @since 4.0.0
  */
 export type TextEditorStrReplaceCommand = typeof TextEditorStrReplaceCommand.Type;
 /**
- * Insert text at a specific line number in a file.
+ * Inserts text at a specific line number in a file.
  *
- * Inserts the new text AFTER the specified line number.
+ * **Details**
  *
- * @since 1.0.0
- * @category Text Editor
+ * 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
  */
 export declare const TextEditorInsertCommand: Schema.Struct<{
     readonly command: Schema.Literal<"insert">;
@@ -1379,20 +2069,28 @@ export declare const TextEditorInsertCommand: Schema.Struct<{
     readonly new_str: Schema.String;
 }>;
 /**
- * @since 1.0.0
- * @category Text Editor
+ * Text editor command payload for inserting text after a specific line number in a file.
+ *
+ * @category text editor
+ * @since 4.0.0
  */
 export type TextEditorInsertCommand = typeof TextEditorInsertCommand.Type;
 /**
- * Undo the last edit made to a file.
+ * Undoes the last edit made to a file.
+ *
+ * **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.
  *
- * NOTE: This command is available in text_editor_20241022 and text_editor_20250124,
- * but NOT in text_editor_20250728 (Claude 4 models).
+ * **Gotchas**
  *
- * @since 1.0.0
- * @category Text Editor
+ * 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
  */
 export declare const TextEditorUndoEditCommand: Schema.Struct<{
     readonly command: Schema.Literal<"undo_edit">;
@@ -1402,17 +2100,35 @@ export declare const TextEditorUndoEditCommand: Schema.Struct<{
     readonly path: Schema.String;
 }>;
 /**
- * @since 1.0.0
- * @category Text Editor
+ * Text editor command payload for undoing the most recent edit to a file.
+ *
+ * **Gotchas**
+ *
+ * Available for `text_editor_20241022` and `text_editor_20250124`, but not for
+ * `text_editor_20250429` or `text_editor_20250728`.
+ *
+ * @category text editor
+ * @since 4.0.0
  */
 export type TextEditorUndoEditCommand = typeof TextEditorUndoEditCommand.Type;
 /**
- * Text editor tool for Claude 3.5 Sonnet (deprecated).
+ * Defines the deprecated text editor tool for Claude 3.5 Sonnet.
  *
- * Requires the "computer-use-2024-10-22" beta header.
+ * **When to use**
+ *
+ * Use when you need the 2024-10-22 `str_replace_editor` compatibility path for
+ * Claude 3.5 Sonnet.
+ *
+ * **Details**
+ *
+ * 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
  *
- * @since 1.0.0
- * @category Text Editor
+ * @category text editor
+ * @since 4.0.0
  */
 export declare const TextEditor_20241022: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly failureMode?: Mode | undefined;
@@ -1479,10 +2195,23 @@ export declare const TextEditor_20241022: <Mode extends Tool.FailureMode | undef
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, true>;
 /**
- * Text editor tool for Claude Sonnet 3.7 (deprecated model).
+ * Defines the text editor tool for deprecated Claude Sonnet 3.7.
  *
- * @since 1.0.0
- * @category Text Editor
+ * **When to use**
+ *
+ * Use when you need 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 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
  */
 export declare const TextEditor_20250124: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly failureMode?: Mode | undefined;
@@ -1549,12 +2278,26 @@ export declare const TextEditor_20250124: <Mode extends Tool.FailureMode | undef
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, true>;
 /**
- * Text editor tool for Claude 4 models.
+ * Defines the text editor tool for Claude 4 models using Anthropic's `str_replace_based_edit_tool`.
+ *
+ * **When to use**
  *
- * NOTE: This version does NOT support the `undo_edit` command.
+ * Use when you need the 2025-04-29 Claude 4 `str_replace_based_edit_tool`
+ * version.
  *
- * @since 1.0.0
- * @category Text Editor
+ * **Details**
+ *
+ * Requires the "computer-use-2025-01-24" beta header.
+ *
+ * **Gotchas**
+ *
+ * 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
  */
 export declare const TextEditor_20250429: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly max_characters?: number | undefined;
@@ -1622,12 +2365,19 @@ export declare const TextEditor_20250429: <Mode extends Tool.FailureMode | undef
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, true>;
 /**
- * Text editor tool for Claude 4 models.
+ * Defines the text editor tool for Claude 4 models.
+ *
+ * **Details**
  *
- * NOTE: This version does NOT support the `undo_edit` command.
+ * Uses Anthropic's `str_replace_based_edit_tool`. `max_characters` can limit
+ * file-view output for this version.
  *
- * @since 1.0.0
- * @category Text Editor
+ * **Gotchas**
+ *
+ * This version does not support the `undo_edit` command.
+ *
+ * @category text editor
+ * @since 4.0.0
  */
 export declare const TextEditor_20250728: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly max_characters?: number | undefined;
@@ -1695,13 +2445,23 @@ export declare const TextEditor_20250728: <Mode extends Tool.FailureMode | undef
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, true>;
 /**
- * User location for localizing search results.
+ * Describes user location for localizing search results.
+ *
+ * **When to use**
+ *
+ * Use when you need to localize search 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.
  *
- * Providing location helps return more relevant results for location-dependent
- * queries like weather, local businesses, events, etc.
+ * @see {@link WebSearch_20250305_Args} for the argument schema that consumes this location
  *
- * @since 1.0.0
  * @category Web Search
+ * @since 4.0.0
  */
 export declare const WebSearchUserLocation: Schema.Struct<{
     /**
@@ -1726,10 +2486,27 @@ export declare const WebSearchUserLocation: Schema.Struct<{
     readonly timezone: Schema.optional<Schema.String>;
 }>;
 /**
- * Configuration arguments for the web search tool.
+ * Defines configuration arguments for the web search tool.
+ *
+ * **When to use**
+ *
+ * Use when you need to configure `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
  *
- * @since 1.0.0
  * @category Web Search
+ * @since 4.0.0
  */
 export declare const WebSearch_20250305_Args: Schema.Struct<{
     /**
@@ -1775,15 +2552,28 @@ export declare const WebSearch_20250305_Args: Schema.Struct<{
     }>>;
 }>;
 /**
- * @since 1.0.0
+ * Configuration arguments for the Anthropic web search tool, including usage limits, domain filters, and optional user location.
+ *
+ * **Gotchas**
+ *
+ * `allowedDomains` and `blockedDomains` are mutually exclusive.
+ *
  * @category Web Search
+ * @since 4.0.0
  */
 export type WebSearch_20250305_Args = typeof WebSearch_20250305_Args.Type;
 /**
- * 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
  *
- * @since 1.0.0
  * @category Web Search
+ * @since 4.0.0
  */
 export declare const WebSearchParameters: Schema.Struct<{
     /**
@@ -1792,20 +2582,35 @@ export declare const WebSearchParameters: Schema.Struct<{
     readonly query: Schema.String;
 }>;
 /**
- * @since 1.0.0
+ * Type of the parameters Claude supplies when invoking the Anthropic web search tool.
+ *
+ * **Details**
+ *
+ * Contains the generated search query used by `WebSearch_20250305`.
+ *
+ * @see {@link WebSearch_20250305} for the provider-defined tool that consumes this payload
+ *
  * @category Web Search
+ * @since 4.0.0
  */
 export type WebSearchParameters = typeof WebSearchParameters.Type;
 /**
- * Web search tool for Claude models.
+ * Defines the web search tool for Claude models.
+ *
+ * **When to use**
+ *
+ * Use when you want Claude to 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).
  *
- * @since 1.0.0
+ * @see {@link WebFetch_20250910} for retrieving known URLs after discovery
+ *
  * @category Web Search
+ * @since 4.0.0
  */
 export declare const WebSearch_20250305: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly maxUses?: number | undefined;
@@ -1882,10 +2687,21 @@ export declare const WebSearch_20250305: <Mode extends Tool.FailureMode | undefi
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * Citation configuration for web fetch.
+ * Defines citation configuration for web fetch.
+ *
+ * **When to use**
+ *
+ * Use when you need to enable or disable citations on web fetch results.
+ *
+ * **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
  *
- * @since 1.0.0
  * @category Web Fetch
+ * @since 4.0.0
  */
 export declare const WebFetchCitationsConfig: Schema.Struct<{
     /**
@@ -1894,15 +2710,48 @@ export declare const WebFetchCitationsConfig: Schema.Struct<{
     readonly enabled: Schema.Boolean;
 }>;
 /**
- * @since 1.0.0
+ * Configuration payload for enabling or disabling citations on web fetch results.
+ *
+ * **When to use**
+ *
+ * Use when typing parsed web-fetch citation configuration shared between
+ * request arguments and handler code.
+ *
+ * **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
  */
 export type WebFetchCitationsConfig = typeof WebFetchCitationsConfig.Type;
 /**
- * Configuration arguments for the web fetch tool.
+ * Defines configuration arguments for the web fetch tool.
+ *
+ * **When to use**
+ *
+ * Use when you need to configure `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
  *
- * @since 1.0.0
  * @category Web Fetch
+ * @since 4.0.0
  */
 export declare const WebFetch_20250910_Args: Schema.Struct<{
     /**
@@ -1936,15 +2785,44 @@ export declare const WebFetch_20250910_Args: Schema.Struct<{
     readonly maxContentTokens: Schema.optional<Schema.Number>;
 }>;
 /**
- * @since 1.0.0
+ * Configuration arguments for the Anthropic web fetch tool, including usage limits, domain filters, citation settings, and token limits.
+ *
+ * **When to use**
+ *
+ * Use when typing parsed web-fetch tool configuration shared by the
+ * provider-defined tool and request-building code.
+ *
+ * **Gotchas**
+ *
+ * `allowedDomains` and `blockedDomains` are mutually exclusive.
+ * `maxContentTokens` is approximate and does not apply to binary content such
+ * as PDFs.
+ *
  * @category Web Fetch
+ * @since 4.0.0
  */
 export type WebFetch_20250910_Args = typeof WebFetch_20250910_Args.Type;
 /**
- * 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
  *
- * @since 1.0.0
  * @category Web Fetch
+ * @since 4.0.0
  */
 export declare const WebFetchParameters: Schema.Struct<{
     /**
@@ -1954,25 +2832,52 @@ export declare const WebFetchParameters: Schema.Struct<{
     readonly url: Schema.String;
 }>;
 /**
- * @since 1.0.0
+ * Type of the parameters Claude supplies when invoking the Anthropic web fetch tool.
+ *
+ * **When to use**
+ *
+ * Use when typing Claude-supplied web-fetch tool parameters after schema
+ * validation, before enforcing URL provenance or length constraints.
+ *
+ * **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.
+ *
  * @category Web Fetch
+ * @since 4.0.0
  */
 export type WebFetchParameters = typeof WebFetchParameters.Type;
 /**
- * Web fetch tool for Claude models.
+ * Defines the web fetch tool for Claude models.
+ *
+ * **When to use**
+ *
+ * Use when you want Claude to 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.
+ * This is a server-side tool executed by Anthropic's infrastructure. Selecting
+ * this tool adds the "web-fetch-2025-09-10" beta header.
  *
- * Requires the "web-fetch-2025-09-10" beta header.
+ * @see {@link WebSearch_20250305} for discovering URLs before fetching specific content
  *
- * @since 1.0.0
  * @category Web Fetch
+ * @since 4.0.0
  */
 export declare const WebFetch_20250910: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
-    readonly citations?: {
-        readonly enabled: boolean;
-    } | undefined;
+    readonly citations?: Schema.Struct.ReadonlySide<{
+        /**
+         * Enable citations for fetched content.
+         */
+        readonly enabled: Schema.Boolean;
+    }, "Encoded"> | undefined;
     readonly maxUses?: number | undefined;
     readonly allowedDomains?: readonly string[] | undefined;
     readonly blockedDomains?: readonly string[] | undefined;
@@ -2044,13 +2949,15 @@ export declare const WebFetch_20250910: <Mode extends Tool.FailureMode | undefin
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * Input parameters for regex-based tool search.
+ * Schema for regex-based tool search input parameters.
+ *
+ * **Details**
  *
  * Claude constructs regex patterns using Python's `re.search()` syntax.
  * Maximum query length: 200 characters.
  *
- * @since 1.0.0
- * @category Tool Search
+ * @category tool search
+ * @since 4.0.0
  */
 export declare const ToolSearchRegexParameters: Schema.Struct<{
     /**
@@ -2059,15 +2966,34 @@ export declare const ToolSearchRegexParameters: Schema.Struct<{
     readonly query: Schema.String;
 }>;
 /**
- * @since 1.0.0
- * @category Tool Search
+ * Type of the parameters Claude supplies when invoking regex-based Anthropic tool search.
+ *
+ * **Details**
+ *
+ * Claude constructs regex patterns using Python's `re.search()` syntax.
+ * Maximum query length: 200 characters.
+ *
+ * @category tool search
+ * @since 4.0.0
  */
 export type ToolSearchRegexParameters = typeof ToolSearchRegexParameters.Type;
 /**
- * Input parameters for BM25/natural language tool search.
+ * Defines input parameters for BM25/natural language tool search.
+ *
+ * **When to use**
  *
- * @since 1.0.0
- * @category Tool Search
+ * 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
  */
 export declare const ToolSearchBM25Parameters: Schema.Struct<{
     /**
@@ -2076,21 +3002,24 @@ export declare const ToolSearchBM25Parameters: Schema.Struct<{
     readonly query: Schema.String;
 }>;
 /**
- * @since 1.0.0
- * @category Tool Search
+ * Type of the parameters Claude supplies when invoking BM25 natural-language Anthropic tool search.
+ *
+ * @category tool search
+ * @since 4.0.0
  */
 export type ToolSearchBM25Parameters = typeof ToolSearchBM25Parameters.Type;
 /**
- * Regex-based tool search for Claude models.
+ * Defines regex-based tool search for Claude models.
+ *
+ * **Details**
  *
  * Claude constructs regex patterns using Python's `re.search()` syntax to
  * find tools. The regex is matched against tool names, descriptions,
  * argument names, and argument descriptions.
- *
  * Requires the "advanced-tool-use-2025-11-20" beta header.
  *
- * @since 1.0.0
- * @category Tool Search
+ * @category tool search
+ * @since 4.0.0
  */
 export declare const ToolSearchRegex_20251119: <Mode extends Tool.FailureMode | undefined = undefined>(args: void) => Tool.ProviderDefined<"anthropic.tool_search_tool_regex_20251119", "AnthropicToolSearchRegex", {
     readonly args: Schema.Void;
@@ -2116,16 +3045,24 @@ export declare const ToolSearchRegex_20251119: <Mode extends Tool.FailureMode |
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * BM25/natural language tool search for Claude models.
+ * Defines 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
  * BM25 algorithm. The search is performed against tool names, descriptions,
  * argument names, and argument descriptions.
- *
  * Requires the "advanced-tool-use-2025-11-20" beta header.
  *
- * @since 1.0.0
- * @category Tool Search
+ * @see {@link ToolSearchRegex_20251119} for the regex-pattern alternative
+ *
+ * @category tool search
+ * @since 4.0.0
  */
 export declare const ToolSearchBM25_20251119: <Mode extends Tool.FailureMode | undefined = undefined>(args: void) => Tool.ProviderDefined<"anthropic.tool_search_tool_bm25_20251119", "AnthropicToolSearchBM25", {
     readonly args: Schema.Void;