If your agent has access to an MCP server but still searches local files, first find out whether the server connected and its tools loaded. Only after those checks should you treat the missing call as a model-selection problem. A direct, task-specific instruction can help, but it cannot make an unavailable tool callable.
1. Check whether the MCP server initialized
A missing tool call does not by itself show that the model ignored a server it could use. The connection may have failed before the model received any tools. OpenAI’s MCP connections guide says to inspect agent.session.turn.failed when a required server cannot initialize, and to check process logs for stdio servers. It describes the MCP server’s role this way: “An MCP server publishes tool definitions and runs tool calls.”
As an Amazon Associate I earn from qualifying purchases.
For an HTTP server
- Confirm the configured server URL is reachable from the place where the connection runs.
- Check whether the connection is made from the service origin or an execution environment. If it runs in an environment, verify that the environment is attached and connected and can reach the server over the network.
- Verify any required credentials.
For a stdio server
- Check the configured command and confirm its executable and dependencies are available in the runtime.
- Confirm the working directory exists and is an absolute path.
- Inspect the process logs for startup errors.
Also check whether the server is configured as required or optional. A required server that fails to initialize can cause the turn to fail; with an optional server, an absent call does not establish that its tools reached the model.
Recommended Free Tools
2. Confirm the expected tool loaded before the turn
A connected server is not enough: the particular tool must be discovered and available to the turn. In OpenAI Realtime MCP, inspect the listing lifecycle events: mcp_list_tools.in_progress, mcp_list_tools.completed, and mcp_list_tools.failed. The completed event includes the imported tool names. If listing is still in progress, tools that have not loaded are not eligible for that turn.
Compare the expected tool name with the names in the completed listing, and check that listing finished before the turn began. If the tool is absent, investigate discovery or loading rather than changing the prompt to demand a call.
Consider how the tool catalog is loaded
OpenAI’s tool-search guidance distinguishes eager loading, which suits a small set of functions used often, from deferred loading, which can suit a larger catalog where only some functions are relevant. Deferred discovery adds a step, so confirm that the intended tool is actually found. For MCP, automatic discovery applies when the model and provider support tool search; configuring an MCP server does not mean you should add a separate tool_search function by default.
3. Diagnose model selection only after the tool is available
Once the expected tool appears in the imported list, examine the request, the tool’s name and description, access restrictions, and tool-choice settings. OpenAI’s tool guidance says the model decides from the prompt whether to use a configured tool; tool_choice can guide or control that decision.
Make the task and the intended tool’s purpose explicit. A community discussion has suggested that names and descriptions can affect MCP tool selection, but that is anecdotal—not an official rule or a controlled finding. Treat clearer naming and descriptions as a hypothesis to test, not a guaranteed fix.
If an application requires a tool call, use the API’s supported tool-choice controls and handle turns where no eligible tool exists. For example, Realtime cannot call a tool that has not finished loading, even when the turn uses tool_choice: "required"; wait for listing to complete or choose a policy suited to that turn.
Give the agent a scoped instruction
When the server and tool are available, tell the agent which server to use and for what kind of task. OpenAI’s Docs MCP setup guide gives an AGENTS.md instruction pattern for directing relevant OpenAI questions to its documentation MCP. That is a useful example, not a guarantee that every framework reads or follows AGENTS.md.
For a repository documentation server, an instruction could say:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsFor questions about this repository’s indexed documentation, use the project_docs MCP search tool before local grep. If it returns no relevant result, then search the files locally.Adapt the server name, task scope, and fallback to your application. Avoid telling the agent to use MCP for unrelated tasks, and preserve a fallback for cases where the server has no relevant result.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Verify which stage failed
After changing one factor, run a representative request and inspect observable runtime output. OpenAI’s MCP server documentation describes an mcp_list_tools item when discovery succeeds and an mcp_call item when a tool is selected. Failed calls can include protocol, execution, or connectivity errors.
| Evidence | What it tells you | Next check |
|---|---|---|
| Turn initialization failure or stdio process error | The server may not have become available. | Connection origin, reachability, credentials, command, dependencies, and working directory. |
| Listing failed, is still in progress, or omits the expected tool | The tool was not confirmed as available for the turn. | Listing completion, discovery configuration, and imported tool names. |
| Tool is listed, but no call is emitted | The model did not select the available tool. | Request wording, tool name and description, access restrictions, and tool-choice settings. |
| A call is emitted, but it returns an error | Selection happened; execution or connectivity may have failed. | Call arguments, result, and reported protocol, execution, or connectivity error. |
Record whether initialization succeeded, whether the expected tool appeared, whether listing finished before the turn, whether a call was emitted, and whether it returned a result. This separates a connection or loading problem from a selection or execution problem, so you can change the part that actually failed.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
