Tool Precedence

Nodexa assistants have tools configured in the admin panel. You can also pass tools in your API request. This page explains how these two sources interact and what the effective tool set is for any given request.

---

Two Sources of Tools

1. Assistant-configured tools (set by your Nodexa administrator)

These are persistent tools attached to the assistant in the admin panel. They may include:

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

2. Request-level tools (provided in the tools field of your API call)

These are tools you declare per-request in the tools array:

{
  "model": "YOUR_ASSISTANT_ID",
  "input": "...",
  "tools": [
    { "type": "function", "name": "my_custom_tool", ... }
  ]
}

---

Precedence Rules

Rule 1: Omit tools → use assistant's configured tools

If you do not include a tools field in your request at all, the assistant uses its configured tools unchanged.

{
  "model": "YOUR_ASSISTANT_ID",
  "input": "Search for recent news about AI."
}

In this case, if the assistant has a web search tool configured, it will be available.

Rule 2: Include tools → override assistant's configured tools

If you include a tools array — even an empty array — it replaces the assistant's configured tools for that request. The assistant-configured tools are not available.

{
  "model": "YOUR_ASSISTANT_ID",
  "input": "Search for recent news about AI.",
  "tools": []
}

In this case, the assistant has no tools available — even if web search is configured in the admin panel. The assistant will respond from its training knowledge only.

{
  "model": "YOUR_ASSISTANT_ID",
  "input": "Check the weather and search my calendar.",
  "tools": [
    { "type": "function", "name": "get_weather", ... }
  ]
}

In this case, only get_weather is available. Calendar tools configured in the admin panel are not.

---

Summary Table

tools field in request	Effective tool set
Omitted	Assistant's configured tools
[] (empty array)	No tools available
[tool1, tool2]	Only tool1 and tool2

---

Common Patterns

Extend assistant tools with request-level tools

There is currently no built-in "merge" behavior. If you want the assistant to have its configured tools plus additional request-level tools, you need to fetch the assistant's tool configuration and include all tools explicitly:

// Not currently supported as a single field — declare all tools you need:
const response = await client.responses.create({
  model: assistantId,
  input: userMessage,
  tools: [
    // Admin-configured tools that you want to include
    { type: 'web_search_preview' },
    // Plus your custom function tool
    {
      type: 'function',
      name: 'lookup_order',
      description: 'Look up a customer order by order ID',
      parameters: {
        type: 'object',
        properties: {
          orderId: { type: 'string' },
        },
        required: ['orderId'],
      },
    },
  ],
});

Prefer omitting tools when possible

If your integration doesn't need to add function tools, omit tools entirely and let the assistant use its configured tools. This reduces your integration's complexity and keeps tool management centralized in the admin panel.

Disable all tools for a specific request

To get a plain LLM response with no tool invocations — useful for purely conversational requests where tool calls would be unwanted — pass an empty tools array:

const response = await client.responses.create({
  model: assistantId,
  input: 'Write me a haiku about autumn.',
  tools: [], // No tools — creative writing needs no tool calls
});

Use only client-side function tools

If you want the assistant to use only your function tools (no web search, no knowledge base), pass only your function tools:

const response = await client.responses.create({
  model: assistantId,
  input: userMessage,
  tools: [
    { type: 'function', name: 'get_account_balance', ... },
    { type: 'function', name: 'get_recent_transactions', ... },
  ],
});

---

Why This Design?

The override behavior gives you explicit control over the tool surface for each request:

• Predictability — you know exactly which tools are available for a given request
• Security — you can prevent the assistant from calling external services for sensitive requests
• Flexibility — different parts of your application can use the same assistant with different tool configurations

The tradeoff is that if you want to add function tools while preserving assistant-configured tools, you must declare all tools explicitly. This is by design: it avoids subtle interactions between admin-configured and request-level tools.