tools

Owner-defined tools the agent can call: api_endpoint (HTTP), code (sandboxed JS/Python), and derived (a preset wrapper over a built-in). Tools can return…

tools — Custom tools

Owner-defined tools the agent can call: api_endpoint (HTTP), code (sandboxed JS/Python), and derived (a preset wrapper over a built-in). Tools can return rich generative-UI via a _render payload.

Section key tools · Shape array · Tier Pro and up (free trial includes it)
Edit in the dashboard: Tools page
Related: Built-in tools · Tool parameters · Code-tool ctx & bridge

List of custom tool definitions.

Fields (per item)

Field	Required	Type	Allowed values / constraints	Default	Description
name	yes	string	—	—	Tool identifier the agent will invoke.
description	yes	string	—	—	What the tool does, shown to the agent.
type	yes	enum	one of api_endpoint, code, derived	—	api_endpoint = HTTP call; code = sandboxed JS/Python; derived = wraps a platform built-in tool (base_tool + param_overrides) with preset params.
url	no	string	—	—	For api_endpoint: target URL (legacy field, prefer endpoint_url).
endpoint_url	no	string	—	—	For api_endpoint: target URL.
method	no	enum	one of GET, POST, PUT, DELETE	—	For api_endpoint: HTTP method.
headers	no	array of object	—	—	For api_endpoint: extra HTTP headers as [{key, value}] pairs.
code	no	string	—	—	For code: source. Must export an async handle(input, ctx) function. The ctx argument lets the snippet call any enabled platform built-in via ctx.tools.<builtin_name>(input) and write audit lines via ctx.audit(event, data).
language	no	enum	one of javascript, python	—	For code: runtime language. Auto-detected if omitted.
input_schema	no	array of object	—	—	Tool input parameters, as an ordered LIST (not a JSON-schema object). Each item describes one argument the agent supplies. The platform builds the tool’s input schema from this list; a non-array is treated as zero parameters. Ignored for type=‘derived’ (the wrapped base_tool defines the schema) — pass []. Item fields below.
enabled	no	boolean	—	—	When false, the tool is registered but not callable at chat time.
collapsed	no	boolean	—	—	UI hint — start this entry collapsed in the dashboard.
visible_to_user	no	boolean	—	—	When true, tool calls and results are shown to the power-user in the chat.
base_tool	no	string	—	—	For type=‘derived’ tools: the built-in tool name this entry wraps (must be a wrappable:true entry from STATIC_INTERNAL_TOOLS — web_search, web_fetch, calculate, execute_code, email_send, email_status, email_read, present_public_file, show_file_excerpt, show_image, surface_file).
param_overrides	no	array of object	—	—	For type=‘derived’ tools: per-parameter presets applied to the base_tool. Each item: {param: string, mode: ‘lock’|‘default’|‘append’, value: string}. lock=fixed (hidden from the agent); default=preset the agent may override; append=preset concatenated onto the agent’s value.
result_note	no	string	—	—	Optional note appended to the tool result before the agent sees it.
engine	no	enum	one of internal, anthropic	—	For type=‘derived’ tools wrapping web_search or web_fetch: which engine the wrapped tool uses. ‘anthropic’ uses Anthropic’s server-side bundle; ‘internal’ uses the platform tool stack. Mirrors builtin_tools.web_search_engine but scoped to this derived tool.
anthropic_search_config	no	object	—	—	For type=‘derived’ tools wrapping web_search with engine=‘anthropic’: config merged into the Anthropic web_search wire object. Same shape as builtin_tools.web_search_anthropic_config. Item fields below.
anthropic_fetch_config	no	object	—	—	For type=‘derived’ tools wrapping web_fetch with engine=‘anthropic’: config merged into the Anthropic web_fetch wire object. Item fields below.

input_schema items

Tool input parameters, as an ordered LIST (not a JSON-schema object). Each item describes one argument the agent supplies. The platform builds the tool’s input schema from this list; a non-array is treated as zero parameters. Ignored for type=‘derived’ (the wrapped base_tool defines the schema) — pass [].

Field	Required	Type	Allowed values / constraints	Default	Description
name	yes	string	—	—	Parameter name — the key the agent fills in.
type	no	enum	one of string, number, integer, boolean, array, object	—	Parameter type. Defaults to ‘string’ when omitted.
description	no	string	—	—	What this parameter is for, shown to the agent.
required	no	boolean	—	—	Whether the agent must supply this parameter.

anthropic_search_config fields

For type=‘derived’ tools wrapping web_search with engine=‘anthropic’: config merged into the Anthropic web_search wire object. Same shape as builtin_tools.web_search_anthropic_config.

Field	Required	Type	Allowed values / constraints	Default	Description
max_uses	no	number	—	—	Maximum number of web_search invocations the agent may perform per API request. When unset, Anthropic applies its default; when set on a wrapped tool, this value is passed to the Anthropic web_search_20260209 tool definition.
max_results	no	number	—	—	Hint for the number of search results to return per query. Passed to Anthropic’s web_search tool; when unset Anthropic applies its default.
topic	no	string	—	—	Search topic hint (e.g. ‘news’, ‘finance’) to help Anthropic filter results for relevance. Optional; when unset Anthropic uses its default topic classification.
user_location	no	object	—	—	Geographic context object used by Anthropic to return location-aware search results. When present, applies all non-empty fields (city, country, region, timezone) to localize results; when absent or fully empty, Anthropic applies its default. Item fields below.
allowed_domains	no	array of string	—	—	List of domain names to restrict search results to only these sources (e.g. [‘nytimes.com’, ‘reuters.com’]). Mutually exclusive with blocked_domains; when both are empty or unset, Anthropic searches all domains.
blocked_domains	no	array of string	—	—	List of domain names to exclude from search results. Mutually exclusive with allowed_domains; when both are empty or unset, Anthropic searches all domains.
max_content_tokens	no	number	—	—	Token budget limit for the content returned per search result. When set, Anthropic truncates fetched content to stay under this token count; when unset, Anthropic applies its default content limit.

anthropic_fetch_config fields

For type=‘derived’ tools wrapping web_fetch with engine=‘anthropic’: config merged into the Anthropic web_fetch wire object.

Field	Required	Type	Allowed values / constraints	Default	Description
max_uses	no	number	—	—	Maximum number of web_fetch invocations the agent may perform per API request. When unset, Anthropic applies its default; when set on a wrapped tool, this value is passed to the Anthropic web_fetch_20260209 tool definition.
allowed_domains	no	array of string	—	—	List of domain names to restrict web fetches to only these sources. Mutually exclusive with blocked_domains; when both are empty or unset, the agent may fetch from any domain.
blocked_domains	no	array of string	—	—	List of domain names to prevent the agent from fetching. Mutually exclusive with allowed_domains; when both are empty or unset, the agent may fetch from any domain.
max_content_tokens	no	number	—	—	Token budget limit for the page content returned by web_fetch. When set, Anthropic truncates fetched content to stay under this token count; when unset, Anthropic applies its default content limit.
citations	no	boolean	—	—	When true, enables inline citations on fetched documents via Anthropic’s web_fetch_20260209 tool, allowing the LLM to cite exact sources. When false or unset, content is returned without explicit citation markers.

anthropic_search_config.user_location fields

Geographic context object used by Anthropic to return location-aware search results. When present, applies all non-empty fields (city, country, region, timezone) to localize results; when absent or fully empty, Anthropic applies its default.

Field	Required	Type	Allowed values / constraints	Default	Description
type	no	enum	one of approximate	—	Classification of the location precision. Currently only ‘approximate’ is supported, indicating a best-effort geographic hint rather than exact coordinates.
city	no	string	—	—	City name to help localize search results (e.g. ‘San Francisco’). Optional within the location object.
country	no	string	—	—	Country name or ISO code to help localize search results (e.g. ‘US’ or ‘United States’). Optional within the location object.
region	no	string	—	—	State/province/region name to help localize search results (e.g. ‘California’). Optional within the location object.
timezone	no	string	—	—	IANA timezone identifier (e.g. ‘America/Los_Angeles’) to help Anthropic understand the user’s local time context for time-sensitive queries. Optional within the location object.