> ## Documentation Index > Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](/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](/sidebar-menu/tools)\ **Related:** [Built-in tools](/builtin-tools/index) · [Tool parameters](/tool-parameters) · [Code-tool ctx & bridge](/custom-tools-ctx) > 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.\(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. |