Tools¶

The Nodexa Responses API supports several tool types that allow assistants to extend their capabilities beyond text generation. This page describes every supported tool, when to use each, and which LLM providers support them.

How Tools Work¶

Tools are declared in the tools array of your request. The assistant decides which tools to invoke based on the conversation context.

{
  "model": "YOUR_ASSISTANT_ID",
  "input": "What is the weather in Tokyo right now?",
  "tools": [
    {
      "type": "web_search_preview"
    }
  ]
}

Explicit tools override configured tools

If you include a tools array in your request (even an empty array []), it replaces the tools configured on the assistant for that request. To use the assistant's default tools, omit the tools field entirely.

See [Tool Precedence](../concepts/tool-precedence.md) for details.

Tool Types¶

Function Tools (client-executed)¶

Function tools allow you to define custom operations that run in your application. The assistant decides when to call them, generates the arguments, and then waits for you to execute the function and return the result.

{
  "type": "function",
  "name": "get_weather",
  "description": "Get the current weather for a given location.",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name or coordinates, e.g. 'San Francisco' or '37.7749,-122.4194'"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Temperature unit"
      }
    },
    "required": ["location"]
  }
}

Field	Required	Type	Description
`type`	Yes	`"function"`	Identifies this as a client-executed function tool
`name`	Yes	`string`	Function name — alphanumeric, underscores, hyphens only; max 64 chars
`description`	No	`string`	Describes what the function does; helps the model decide when to call it
`parameters`	No	`object`	JSON Schema for the function's arguments

Constraints:

Maximum 128 function tools per request
Tool names must be unique within the request
Names must match /^[a-zA-Z0-9_-]{1,64}$/

See Function Calling for the complete execution flow.

Web Search — OpenAI (`web_search_preview`)¶

Uses OpenAI's built-in web search capability. Available for models in the gpt-4o family with search support.

{
  "type": "web_search_preview",
  "search_context_size": "medium"
}

Field	Required	Type	Description
`type`	Yes	`"web_search_preview"`	OpenAI web search tool identifier
`search_context_size`	No	`"low" \\| "medium" \\| "high"`	Controls how much search context is retrieved. Default: `"medium"`

search_context_size values:

Value	Description	Use Case
`"low"`	Fewer search results, faster	Simple factual lookups
`"medium"`	Balanced results	General purpose (default)
`"high"`	More results, slower	Complex research tasks needing comprehensive coverage

Web Search — Claude (`web_search`)¶

Uses Anthropic Claude's built-in web search capability. Available for Claude models that support tool use.

{
  "type": "web_search",
  "allowed_domains": ["reuters.com", "bbc.co.uk", "apnews.com"],
  "blocked_domains": ["reddit.com", "twitter.com"]
}

Field	Required	Type	Description
`type`	Yes	`"web_search"`	Claude web search tool identifier
`allowed_domains`	No	`string[]`	Whitelist of domains to include in results
`blocked_domains`	No	`string[]`	Blacklist of domains to exclude from results

Domain filtering

Use allowed_domains when you want the assistant to cite only trusted, authoritative sources (e.g., official documentation sites, major news outlets). Use blocked_domains for a lighter touch when only a few sources should be excluded.

Google Search (`google_search`)¶

Uses Google's Grounding with Google Search feature via the Gemini API. Available for Google Gemini models.

{
  "type": "google_search",
  "dynamic_retrieval_threshold": 0.3
}

Field	Required	Type	Description
`type`	Yes	`"google_search"`	Google search / grounding tool identifier
`dynamic_retrieval_threshold`	No	`number` (0.0–1.0)	Threshold for dynamic retrieval. Lower values = more retrieval. Default: model-dependent

dynamic_retrieval_threshold:

The threshold controls how frequently Google grounding is triggered based on the model's confidence that fresh web data is needed.

Value	Behavior
`0.0`	Always retrieve from Google Search
`0.3`	Retrieve when the model is moderately uncertain (good default)
`1.0`	Only retrieve when the model is very confident it needs live data

Provider Compatibility Matrix¶

Tool Type	OpenAI (GPT-4o, etc.)	Anthropic (Claude)	Google (Gemini)
`function`	Yes	Yes	Yes
`web_search_preview`	Yes	No	No
`web_search`	No	Yes	No
`google_search`	No	No	Yes

Mismatched tool and model

If you specify a tool not supported by the model backing the assistant's active specialist agent, the platform will return a 400 error with tool_not_supported_for_model. Always match your web search tool type to the model in use, or omit the web search tool and let the assistant's configuration determine which search tool to use.

Combining Tool Types¶

You can include multiple tool types in a single request. For example, a function tool alongside a web search tool:

{
  "model": "YOUR_ASSISTANT_ID",
  "input": "Look up today's USD/EUR exchange rate and calculate how much 250 USD is in EUR.",
  "tools": [
    {
      "type": "web_search_preview"
    },
    {
      "type": "function",
      "name": "calculate",
      "description": "Perform arithmetic calculations",
      "parameters": {
        "type": "object",
        "properties": {
          "expression": {
            "type": "string",
            "description": "A math expression to evaluate, e.g. '250 * 0.92'"
          }
        },
        "required": ["expression"]
      }
    }
  ]
}

The assistant may call the web search tool first to get the exchange rate, then call calculate with the retrieved value.

Tools Configured on the Assistant¶

Your platform administrator configures tools on each assistant in the Nodexa admin panel. These can include:

REST API integrations
MCP (Model Context Protocol) server connections
Knowledge base retrieval
Web search

When you omit the tools field, these configured tools are automatically available to the assistant. See Tool Precedence for how request-level and assistant-level tools interact.

Tool Limits¶

Limit	Value
Maximum tools per request	128
Maximum tool name length	64 characters
Tool name characters	Alphanumeric, `_`, `-` only
Tool names must be unique	Yes (within a single request)

See Limits for the full limits reference.

Tools¶

How Tools Work¶

Tool Types¶

Function Tools (client-executed)¶

Web Search — OpenAI (web_search_preview)¶

Web Search — Claude (web_search)¶

Google Search (google_search)¶

Provider Compatibility Matrix¶

Combining Tool Types¶

Tools Configured on the Assistant¶

Tool Limits¶

Web Search — OpenAI (`web_search_preview`)¶

Web Search — Claude (`web_search`)¶

Google Search (`google_search`)¶