OpenAI tool namespaces: hosted vs local execution

The OpenAI Agents SDK defines exactly five tool categories to govern how agents execute actions like fetching data or running code. This architecture relies on the tool namespace to separate hosted server-side execution from local runtime environments, forcing developers to choose between OpenAI-managed convenience and user-controlled security. These namespaces dictate orchestration patterns, drive token efficiency through deferred loading, and determine the ROI of hosted container execution versus local shell skills.

The framework distinguishes clearly between Hosted OpenAI tools that run on proprietary servers and Local/runtime execution tools like ComputerTool that operate within your own environment. While Hosted tools handle web search and image generation, the ShellTool offers a hybrid approach by running locally or inside a hosted container depending on configuration. This separation allows the system to wrap any Python function as a tool or expose an entire agent as a callable utility without requiring a full handoff.

Efficiency gains come from deferring large tool surfaces until runtime, a technique the documentation calls hosted tool search. Instead of flooding the context window with every available function, the model loads only the specific namespace required for the current turn. This approach mirrors the cost-conscious mindset seen elsewhere in the AI coding sector, where competitors like Cursor price individual access at a monthly rate. Understanding these mechanical distinctions is no longer optional for building viable agent systems in 2026.

The Role of Tool Namespaces in Modern Agent Architecture

Defining Hosted Tools and Tool Namespaces in OpenAI Agents

Hosted tools are OpenAI-managed capabilities executing server-side alongside the OpenAIResponsesModel, offloading runtime complexity from the developer's environment. This category includes the WebSearchTool for real-time data retrieval, the FileSearchTool for querying Vector Stores, and the CodeInterpreterTool for sandboxed code execution. These components run entirely within OpenAI's infrastructure rather than requiring custom process management on the user side. Performance remains consistent without local dependency conflicts.

Tool namespaces function as logical catalogs grouping related functions under a shared identifier. Agents defer loading large tool surfaces until specific capabilities are required at runtime. By using the ToolSearchTool, a model dynamically loads a tool_namespace containing CRM or billing functions only when conversation context demands it. Initial token overhead drops notably. This deferred loading mechanism prevents context window saturation when managing extensive function libraries.

Network latency and service availability become strict dependencies when relying on hosted execution. The application cannot intercept or modify the tool's internal logic before execution. Architectural decisions must balance managed service convenience against the need for low-latency, customizable local control. Subscription models for advanced coding agents correlate capability with costs like $20/month. The structural choice between hosted and local tools fundamentally dictates the agent's operational boundary. Grouping related deferred tools into namespaces optimizes search efficiency.

Applying Local Runtime Tools and Function Wrappers

Local runtime tools execute outside the model response because the application performs the work. Developers deploy LocalShellTool and ComputerTool when sandboxed environments lack necessary system access or persistent state. These interfaces require the operator to manage underlying process security and execution context directly unlike hosted options.

Wrapping custom logic involves the Function tools category where the SDK uses Python's `inspect` module and `griffe` for parsing docstrings. This mechanism converts standard Python functions into strict schemas using Pydantic. Data types get enforced before invocation. Such validation prevents incorrect function execution by defining required inputs and rules deterministically.

Specialized planning agents often require this local execution depth to interact with terminal-based workflows or IDE-first environments effectively. Hosted tools reduce infrastructure overhead. Local wrappers enable deep integration with existing developer tooling like Cursor or native terminal interfaces.

Shifting execution to the local environment transfers the burden of sandboxing from the provider to the builder. A failure in input sanitization within a local wrapper exposes the host system to arbitrary code execution risks. Builders must implement their own containment strategies rather than relying on OpenAI's managed isolation.

Selecting between deferred namespaces and individual local tools depends on whether the bottleneck is token context or system capability.

Hosted MCP versus Local Shell: Selecting the Right Execution Mode

Select HostedMCPTool to expose remote servers or LocalShellTool for legacy integration based on runtime control.

Infrastructure ownership balances against execution latency in this decision. HostedMCPTool delegates tool surface management to OpenAI. The model loads deferred capabilities only when the conversation requires them. This approach minimizes token overhead by avoiding upfront transmission of large schema definitions. LocalShellTool executes commands within the operator's own process. Direct access to local filesystems and legacy binaries becomes possible even when cloud containers cannot reach them. Local execution demands rigorous input validation to prevent arbitrary code execution risks on production hosts.

Architectural fit matters for operators too. Modern frameworks increasingly treat agents as microservices, favoring hosted modes for stateless scalability. Tasks requiring persistent local state or specific environment variables necessitate local shells.

Developers should catalog available tools to match runtime needs effectively. Deferring large tool surfaces until runtime with tool search requires the hosted option for standard Responses models.

Inside Deferred Loading and Function Calling Mechanics

How Hosted Tool Search Defers Large Tool Surfaces

Hosted tool search cuts token overhead by loading only the FunctionTool instances needed for the current turn. This mechanism stops the model from parsing schema definitions for hundreds of unused functions, a sharp optimization when managing large tool surfaces. Systems rely on @function_tool(defer_loading=True) decorators to flag specific functions for runtime retrieval instead of initial context injection. When an agent needs a deferred capability, it emits a search call that triggers loading of the specific tool_namespace or individual tool.

Configuration demands exactly one ToolSearchTool entry inside the agent definition to enable this retrieval path. Developers group related deferred functions using tool_namespace, which offers a descriptive surface for the model to query.

The standard Runner raises an exception if the model tries to execute a client-side search call without proper orchestration logic. Applications needing flexible, non-hosted discovery must implement manual execution loops rather than depending on automatic handling. HostedMCPTool instances and deferred functions strictly require the hosted search pathway to function correctly within the openai>=2.25.0 SDK. This approach shrinks the initial prompt size notably. The model must correctly identify and request the missing tool before proceeding, creating a specific dependency chain.

Configuring Python Functions and Agents as Tools

The Agents SDK builds tool schemas by parsing function names, arguments, and docstrings automatically. Developers define logic using standard Python syntax while the framework extracts metadata to populate the model's available actions without manual JSON specification. The system uses the griffe library to interpret documentation strings in google, sphinx, or numpy formats, converting comments into detailed descriptions for the LLM. Automation ensures input validation rules and data types align strictly with set function signatures.

Operational scale requires managing how these tools appear to the model during execution. Loading every definition simultaneously consumes excessive context tokens when an agent faces a large surface of potential actions. Marking specific functions with `defer_loading=True` and grouping them within a tool_namespace solves this problem. A single ToolSearchTool instance enables the model to query and load these grouped capabilities dynamically at runtime rather than during initialization. This approach separates tool definition from immediate availability, allowing systems to maintain hundreds of potential functions while exposing only the subsets per turn.

Tool visibility and context efficiency create tension; deferring too many necessary tools can increase latency as the model performs extra search steps before acting. Hosted tool search remains specific to OpenAI Responses models, limiting portability across different inference backends even though some IDE-first environments integrate tightly with local codebases. Builders must balance token savings from deferred loading against the extra round-trip required to resolve tool names during execution.

Runtime Constraints of Hosted Tool Search and SDK Versions

Hosted tool search operates exclusively within OpenAI Responses models, creating a hard boundary for cross-platform agent deployment. Developers cannot port deferred loading logic to other LLM providers without rewriting the underlying orchestration layer. The mechanism relies on the model's ability to interpret search calls and retrieve specific tool_namespace definitions only when available on OpenAI's infrastructure.

Implementation requires the Python environment to run openai>=2.25.0, as earlier SDK versions lack parsing logic for deferred schemas. Attempts to execute these configurations on older runtimes fail during the agent initialization phase due to missing decorators. This setup enables efficient token usage but introduces a rigid dependency on a single vendor's model family and update cadence.

The standard Runner presents a second operational risk by not auto-executing client-side tool search calls. If an agent emits a `tool_search_call` with `execution="client"`, the runner raises an exception rather than performing the fetch. Teams must distinguish between hosted retrieval, which the model handles, and manual orchestration, which demands custom error handling code.

Token efficiency and architectural flexibility stand in opposition here. Builders gain significant context savings but lose the ability to switch base models without refactoring the entire tool surface definition.

Measurable ROI from Hosted Container Execution and Shell Skills

Configuring ShellTool with container_auto and container_reference Modes

Defining the environment type as container_auto or container_reference shifts ShellTool execution from local runtime to managed infrastructure. Selecting container_auto provisions a fresh container for the specific request, while container_reference reuses an existing environment identified by a specific container_id, such as `cntr_...`, to maintain state across multiple interaction turns. This distinction allows developers to balance resource overhead against the need for persistent file system context.

Certain local parameters become invalid when configuring these hosted environments to prevent runtime conflicts. Users must not set executor, needs_approval, or on_approval on the ShellTool definition because the hosted platform manages these lifecycle events internally. This architectural constraint forces a clear separation between local development sandboxes and production-grade environments where security boundaries are enforced by the provider rather than the client script.

Explicit file_ids or volume mounts are required for data persistence in this managed approach. Builders must architect agents to treat the container as disposable unless explicitly referencing a persistent ID.

Application: Wrapping Python Functions as Tools Using Docstring Parsing and Pydantic Constraints

Automatic schema generation from docstrings converts standard Python functions into callable tools. The OpenAI Agents SDK inspects function signatures and parses documentation to construct strict input schemas without manual JSON definitions. This mechanism supports google, sphinx, and numpy docstring formats, allowing engineers to maintain clean code while providing the model with structured metadata. Input validation relies on Pydantic constraints, where Pydantic's Field can be used to add constraints (e.g. Ge=0, le=100) and descriptions to enforce numerical boundaries and prevent invalid execution paths.

Functions may optionally accept context as the first argument to access runtime state, though this signature change requires no additional configuration. Disabling use_docstring_info stops the parser from extracting descriptions, forcing reliance on explicit overrides for name and description fields. Automatic parsing accelerates development, yet complex flexible behaviors often require defining custom on_invoke_tool handlers to manage asynchronous logic or external API interactions directly. Grouping these wrapped functions into tool namespaces improves token efficiency compared to exposing every utility immediately for larger deployments. Docstring reliance demands rigorous documentation standards; vague descriptions degrade the model's ability to select the correct tool during orchestration. Builders must ensure docstrings remain synchronized with code logic to avoid schema mismatches.

Security Risks in Hosted Execution: Network Policies and Domain Secret Injection

Strict network_policy configuration prevents unauthorized egress from the container_auto environment during hosted ShellTool execution. Operators choose between disabled and allowlist modes, where the latter restricts outbound traffic to verified domains only. The system injects domain-scoped secrets via network_policy.domain_secrets in allowlist mode, ensuring credentials match the specific execution context rather than global permissions. This approach mitigates lateral movement if an agent attempts to access internal resources unexpectedly.

Isolating agents in secure environments introduces complexity when tools require broad internet access for dependency resolution or external API calls. Developers configuring memory_limit parameters should verify that network constraints do not interrupt legitimate data fetching required by the skill bundle. Running agents within isolated environments on a VM or cloud instance provides a necessary security boundary against malicious code execution for strong isolation. Validating these policies before deploying agents with write access to production systems is necessary for maintaining system integrity.

Migrating to Flexible Tool Loading in Five Steps

Defining the ToolSearchTool Mechanism for Deferred Loading

The ToolSearchTool enables OpenAI Responses models to defer large tool surfaces until runtime, loading only the subset needed for the current turn. This mechanism reduces token overhead by preventing the model from processing unused schema definitions during initialization. Developers must configure exactly one instance of ToolSearchTool within the agent definition to activate this deferred loading behavior. The process requires pairing this searcher with specific defer_loading flags on function tools or namespaces.

1. Decorate target functions with `@function_tool(defer_loading=True)` to mark them for runtime retrieval.
2. Group related tools using `tool_namespace` to create a searchable surface for the model.
3. Include a single ToolSearchTool in the agent's tool list to enable flexible discovery.
4. Ensure the Runner executes the query, allowing the model to invoke the searcher when necessary.

Hosted tool search operates exclusively with OpenAI Responses models and requires `openai>=2.25.0` for full Python SDK compatibility. A hard constraint involves orchestration logic: if the model emits a client-executed search call, the standard Runner raises an exception rather than auto-executing the load. This behavior forces developers to explicitly manage manual orchestration modes when using `execution="client"`. Namespaces improve search efficiency, yet keeping groups under ten functions remains the recommended practice to maintain precision. The limitation for this token efficiency is increased configuration complexity, as named tool_choice cannot target bare namespace names or deferred-only tools directly.

Configuring WebSearchTool and FileSearchTool with Filters

Configure WebSearchTool and FileSearchTool by applying specific filters and context parameters to narrow result scopes. The FileSearchTool accepts `filters`, `ranking_options`, and `include_search_results` alongside standard vector store identifiers. These parameters allow engineers to restrict retrieval to specific metadata fields or adjust relevance scoring algorithms before the model processes the content. Conversely, the WebSearchTool uses `user_location` and `search_context_size` to ground queries geographically and control the depth of retrieved snippets. Setting `search_context_size` prevents the agent from ingesting excessive peripheral text that dilutes reasoning quality.

Retrieval precision often conflicts with token consumption; broader contexts increase accuracy but raise latency.

Implementing these controls requires the underlying OpenAI Responses models to parse the refined search schema correctly. Aggressive filtering carries a risk of zero-shot failures if the filter criteria exclude all viable candidates. Operators must balance strictness with the variability of external data sources. Precise configuration reduces the need for downstream correction loops.

Implementation: Pre-Implementation Checklist for Hosted Tool Search Constraints

Verify the runtime environment supports OpenAI Responses models before attempting deferred tool loading, as this capability is unavailable elsewhere. Developers must confirm the installation of Python SDK version `openai>=2.25.0` to access the necessary ToolSearchTool primitives. This constraint exists because the standard Runner orchestration logic relies on specific response types that older SDK versions cannot parse or execute correctly.

1. Audit the agent's tool surface to identify candidates for defer_loading flags, ensuring they are not required for immediate initialization.
2. Validate that exactly one ToolSearchTool is added to the agent configuration to prevent schema conflicts during execution.
3. Confirm that function tools targeting CRM or billing data are grouped into namespaces containing fewer than ten functions each.

Skipping namespace grouping increases token consumption and reduces model accuracy during the initial search phase. Some teams might consider flexible client-side orchestration, yet the standard Runner raises an exception if it encounters a client-executed tool search call without manual handling logic. Properly configured namespaces provide a structured search surface that raw function lists cannot match.

References

• Cursor Individual developers and teams wanting IDE-first AI Code
• AI Lab both Freemium, Subscription, Usage Based ✓ ✗
• GitHub - boy1dr/AgentDex: A dead-simple way to chain AI