{"record":{"id":"9ea1356ff37be5eb","repo":"vercel/ai","slug":"allowedtools-with-only-tools-that-cannot-be-allow","errorCode":null,"errorMessage":"allowedTools with only tools that cannot be allow-listed (${droppedToolNames.join(', ')})","messagePattern":"allowedTools with only tools that cannot be allow-listed \\((.+?)\\)","errorType":"exception","errorClass":"UnsupportedFunctionalityError","httpStatus":null,"severity":"error","filePath":"packages/openai/src/responses/openai-responses-prepare-tools.ts","lineNumber":486,"sourceCode":"        });\n        continue;\n      }\n\n      if (!resolution.supported) {\n        toolWarnings.push({\n          type: 'unsupported',\n          feature: `allowedTools entry \"${name}\"`,\n          details: `${resolution.reason}; the tool is removed from the allowed tools`,\n        });\n        droppedToolNames.push(name);\n        continue;\n      }\n\n      allowedToolEntries.push(resolution.entry);\n    }\n\n    if (allowedToolEntries.length === 0) {\n      throw new UnsupportedFunctionalityError({\n        functionality: `allowedTools with only tools that cannot be allow-listed (${droppedToolNames.join(\n          ', ',\n        )})`,\n      });\n    }\n\n    return {\n      tools: openaiTools,\n      toolChoice: {\n        type: 'allowed_tools',\n        mode: allowedTools.mode ?? 'auto',\n        tools: allowedToolEntries,\n      },\n      toolWarnings,\n    };\n  }\n\n  if (toolChoice == null) {","sourceCodeStart":468,"sourceCodeEnd":504,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/openai/src/responses/openai-responses-prepare-tools.ts#L468-L504","documentation":"When allowedTools is set, prepareResponsesTools filters the tool list down to entries that can actually be allow-listed on the Responses API (e.g. function-type tools). If every entry in allowedTools was dropped because its corresponding tool type cannot be allow-listed, the SDK throws UnsupportedFunctionalityError instead of silently sending an empty allow-list.","triggerScenarios":"Calling an openai.responses(...) model with allowedTools containing only names that resolve to tool types OpenAI cannot allow-list (e.g. web_search, code_interpreter or other built-in/hosted tools) and no allow-listable function tools.","commonSituations":"Restricting tools in an agent config where the only configured tools are built-in OpenAI tools; renaming a function tool so allowedTools no longer matches an allow-listable entry; copying an allowedTools list from a chat.completions setup to responses.","solutions":["Add at least one allow-listable (function) tool to the tools array and reference it in allowedTools","Remove non-allow-listable tool names from allowedTools and gate them via toolChoice or application logic instead","Convert the restricted capability into a custom function tool so it can be allow-listed"],"exampleFix":"// before\ntools: { web_search: openai.tools.webSearch() },\nallowedTools: ['web_search']\n// after\ntools: { web_search: openai.tools.webSearch(), search_wrapper: tool({...}) },\nallowedTools: ['search_wrapper']","handlingStrategy":"validation","validationCode":"if (allowedTools.length > 0 && !allowedTools.some(name => name in functionTools)) {\n  throw new Error('allowedTools must include at least one allow-listable function tool');\n}","typeGuard":"function hasAllowListableTool(tools: Record<string, unknown>, allowedTools: string[]): boolean {\n  return allowedTools.some(name => tools[name] != null);\n}","tryCatchPattern":"try {\n  await generateText({ model: openai.responses('gpt-4.1'), tools, allowedTools, ... });\n} catch (e) {\n  if (UnsupportedFunctionalityError.isInstance(e) && e.message.includes('cannot be allow-listed')) {\n    // fall back to calling without allowedTools and enforce restrictions app-side\n  } else throw e;\n}","preventionTips":["Only put function-tool names in allowedTools","Keep allowedTools derived from the actual tools object keys","Remember built-in tools (web_search, etc.) cannot be allow-listed"],"tags":["openai","tools","allowed-tools","responses-api","unsupported-functionality"],"backgroundTag":"empty-tool-allowlist","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}