MCP tool is connected but not called: check the description and permissions first

Key points of this article

A successful connection only means that the handshake between the assistant and the server is completed. The tool must first appear in the list before the assistant can call it.
The assistant decides whether to call it based on the tool description and task content. When the description is general or the prompt word is vague, it often responds directly with text.
Each call stops at the confirmation step. Usually the permissions are set to require confirmation or not released, and need to be checked in the client.
The assistant can only read allowed directories, put the file in an accessible location, or give the full path in the request and test again.

Many people follow the tutorial to connect OmniDoc's MCP server to the AI assistant. After saving the configuration, the assistant also shows that it is connected. But when asked to translate a PDF, it either answered directly in text, or said "I can't process the file" without calling OmniDoc's tools.

In this case, it is usually not that the server is broken, but that "the connection is successful" and "can be called" are two different things. The connection only indicates that the assistant and the server have completed the handshake; whether the assistant needs to call a tool depends on whether it can see the tool, whether the tool description matches the current task, and whether the client's permissions are allowed. As long as one of the three links is disconnected, it will appear to be "connected but not called".

This article is written for readers who have completed the connection but encountered "no call". After reading, you can check the tool list, tool description, permission settings and file path in order, and know how to write a request so that the assistant can actively use the tool when appropriate. The method in this article is based on the general MCP working method and does not involve specific interface button names. You can find the corresponding setting location according to the assistant you use.

Why is the mcp tool not being called when connected? One sentence conclusion

First confirm that there is indeed an OmniDoc tool in the tool list, and then check the description and permissions; if all three are normal, most problems arise from the prompt word not clearly explaining the task.

your situation	Recommended practices	reason
Assistant shows connected but tool list is empty	Check the configuration file format and try again after completely restarting the assistant.	The server did not successfully register the tool and the assistant could not be called.
It's in the tool list, but the assistant always bypasses it	Specify the tools and files to be used in the request, and then test	The assistant matches the description and task, making it easy to choose a direct answer when the request is vague.
Every call pops up to confirm or be rejected	Allow the corresponding tools of the server in the client's permission settings	If the permission is not released, the call will be blocked and it will look like there is no call.
Called but the file cannot be found	Place the file in a directory accessible to the assistant, or give an absolute path	Assistant can't read anywhere on your computer
Connected to multiple document servers at the same time	Keep only the servers you need, or specify which one to use in the request	When the tools have similar functions, the assistant may have selected another server.

First determine what kind of problem it is

Don't rush to change the configuration yet. Compare the symptoms below to quickly narrow down the scope.

symptoms	Common causes	How to confirm this
Assistant says, "No relevant tools"	The tool was not registered successfully, or the configuration was not activated	In the assistant's MCP settings, check if tools are listed under OmniDoc
Tools are listed, but never used	The tool description is unclear, or the request does not trigger it	Put it another way to clarify the requirement and see if it is called; If it still doesn't appear, check the description again
Each time, it stops at the confirmation step	Permission is set to each inquiry or not granted	Check if the client has any pending confirmation prompts and check the server's permissions
Error after calling, prompting 'File Not Found'	The file path is not within the accessibility range of the assistant	Retry with the full path to confirm that the directory containing the file can be read
Changed the configuration, but the effect didn't change	The assistant did not reload the configuration	After completely exiting the assistant, open it again and check the tool list
New sessions are normal, old sessions are not used	The context of old conversations affects judgment	Start a new session and retest with the same request

Inspect and fix each item one by one

Confirm that the server has actually registered the tool. Open the assistant's MCP settings, find the OmniDoc server, and check if tools are listed below. If not, go back to the configuration file to check the JSON format: commas, quotes, and parentheses are paired, and whether the backslashes in the path are escaped correctly. If the format is incorrect, the server may not start at all.
Confirm that the configuration is active. After saving the configuration, exit the assistant completely before opening it; do not just close the window. Many assistants only read the MCP configuration at startup and don't restart, so what you see may still be the old state.
Check whether the tool description is complete. Description is the main basis for the assistant to determine "when to use this tool." Please use the original description returned by the server; don't delete keywords just to save effort. For example, if words like "translation," "PDF," or "Word" are missing, the assistant will have a hard time matching your task with the tool. If you are connecting to an older version server, there may also be mismatched descriptions. Try updating again.
Check permission settings. Check in the client whether the server's tools are allowed and set to "Each Query". If you need to confirm every time, pay attention to the pop-up prompt on the first call, and test only after confirming. Tools that were previously rejected need to be re-released in the settings, otherwise they will remain blocked outside.
Testing with explicit requests. Don't just say "Help me handle this file"; the assistant will likely respond directly in text. You can write: "Please use the OmniDoc tool to translate /Users/yourusername/Documents/paper.pdf into a bilingual Chinese version." This approach simultaneously explains the tool's purpose, file location, and output requirements, making it easier for the assistant to determine which tool to call.
Handle file paths. Assistants usually can only read directories they are allowed to access. Place the pending files into these directories, or specify the complete absolute path in the request. After the call is complete, also confirm where the output file is written. If you can't find the result, first check if the assistant's reply indicates the save location.

How to Prevent It from Happening Next Time

After connecting, perform a small test: have the assistant list available tools, then process a very small file, confirm the connection is open, and then proceed with the official task.
After each configuration change, note what was changed. When problems arise, it's easy to revert and compare without guessing from the beginning.
For long-term requests, always specify the tool's purpose and file path to reduce the hassle of redecapitating each time.
Only retain servers that are actually needed. The fewer tools you have, the less likely you are to choose the wrong assistant.
If the requested document involves important content such as contracts or papers, before submitting the translation or editing results, you must check the proper terms, numbers, and formulas one by one, which can lead to errors in machine translation.

❓ Frequently Asked Questions (FAQ)

1. How do you call the OmniDoc tool in mcp? Do you need to write code yourself?

Usually, no code is needed. After connecting, simply explain the task in natural language, and the assistant will decide whether to call the tool based on the request. If it doesn't call, first follow the steps above to check the tool list and permissions.

2. Why does the assistant say it has no access when connecting files with MCP?

The assistant can only read directories allowed by the client and the files you explicitly provided in the request. Move the file to an allowed directory, or provide the full path in the request and test again.

3. Every time you call, you have to check—can the assistant automatically call it?

Permission settings determine whether confirmation is required each call. Switching to automatic release is easier, but only if you trust the server and know which files the assistant will handle. For tasks involving sensitive data, it is recommended to keep the confirmation step.

4. Can scanned PDFs be translated using the assistant?

OmniDoc's translation feature supports scanned PDFs. However, whether it can be called depends on whether the MCP connection and tool permissions are normal. First, check the previous text. Before submitting the translation, important content must still be verified.

📝 Summary

MCP tools connect but are not called, mostly because the tool is not registered, descriptions do not match the task, permissions are not granted, or the file path is inaccessible. Sorting in the order of "first check the tool list, then check permissions, and finally use explicit request testing" usually helps quickly identify the problem.

Open OmniDoc and connect the document tool to your AI assistant