Finding and calling a tool

Omniio puts one endpoint in front of every MCP server the user has connected. It does not preload their tools. You see three: search_tools, describe_tool and run_tool. Everything else is behind them.

That is the whole trade. You do not pay context for hundreds of tool definitions, and in exchange you have to look before you call.

The loop

search_tools(query)  →  describe_tool(name)  →  run_tool(name, arguments)

search_tools and describe_tool are read-only and idempotent. They change nothing, they cost nothing to be wrong about, and they are annotated as such so you can call them without stopping to ask permission. Only run_tool acts.

Search first, and search unprompted

The failure that matters is not a bad call. It is answering from memory a question one of these servers could have answered properly — a stale figure, a made-up issue number, a library API that changed two versions ago. That reads as confidence and is wrong.

So: if a request needs current data, a lookup in a product the user has connected, or an action taken in one, call search_tools before concluding anything. You do not need to be asked to.

If search_tools returns nothing relevant, say so plainly and answer normally. Do not guess at a tool name that was not returned.

Read the schema. Do not infer the arguments.

This is the single largest cause of failed run_tool calls, and it is entirely avoidable: describe_tool returns the exact JSON input schema, and the argument names in it are frequently not the ones you would guess.

Real examples from this gateway:

Tool	Guessed	Actually
pixelgust__get_current_weather	latitude, longitude	lat, lon
wolfram__WolframAlpha	input	query
context7__resolve-library-id	libraryName alone	both libraryName and query

Each of those failed on the first attempt, from a caller that had the correct schema in its context and used a plausible name instead of the given one.

The rule is mechanical: after describe_tool returns, build the arguments by reading its properties and required. If you find yourself typing an argument name you have not just read, stop.

Names are qualified

search_tools returns names like github__search_issues — the server, two underscores, the tool. Pass that whole string to describe_tool and run_tool. An unqualified name will not resolve, and there may be several tools with the same short name on different servers.

When a call comes back unhappy

• "needs approval before it can run" — not an error. See the handling-held-and-refused-calls skill.
• "denied by your Omniio tool policy" — the account has switched this tool off. Do not retry; tell the user where to change it.
• A validation error naming a field — you got the arguments wrong. Re-read the schema from describe_tool; do not retry the same arguments.
• The tool's own error text — the upstream ran and refused. Relay what it said rather than reinterpreting it.

Cost

Every run_tool counts against the account's monthly allowance and its per-minute burst limit. search_tools and describe_tool are metered too but are far cheaper than a wrong call followed by a right one. Searching twice to call once is the correct trade.