The three tools

Every Omniio MCP client sees exactly three tools. Discovery is deliberately a sequence: find a capability, read one schema, then execute it.

search_tools#

Searches the cached catalogues of every server you have enabled. It does not contact an upstream server and does not change data, so it is declared read-only and idempotent.

querystring · required

A natural-language description of the capability, such as `search GitHub issues` or `up-to-date library documentation`.

limitinteger · 1–25

The maximum matches to return. The default is 8. Broader searches usually work better than guessing a vendor's exact tool name.

{"query":"read a pull request and its review comments","limit":5}

The result is compact text rather than a block of schemas:

Found 2 tool(s). Call describe_tool with a name to see its arguments, then run_tool to execute:
- github__get_pull_request  [GitHub]  Get details for one pull request
- github__get_pull_request_comments  [GitHub]  Read review comments on a pull request

No matches is not an error. The response suggests broader terms and checking that the relevant server is enabled.

describe_tool#

Returns one matching tool's description and JSON input schema. Its only input is the fully qualified name returned by search_tools.

{"name":"github__get_pull_request"}

The definition is returned as compact JSON. Omniio intentionally does not pretty-print a large schema: indentation would become context tokens with no information in them.

Like search, describing is read-only and idempotent. An unknown or disabled name is an error and points the caller back to search_tools rather than letting it guess.

run_tool#

Calls the upstream server. The name is required; arguments is an object that must match the schema from describe_tool and may be omitted for a tool with no parameters.

{
  "name": "github__get_pull_request",
  "arguments": {
    "owner": "example",
    "repo": "service",
    "pullNumber": 214
  }
}

run_tool is conservatively annotated as potentially destructive, non-idempotent and open-world. Omniio cannot truthfully call a proxy read-only: the upstream tool might create, send or delete something. Policy and scopes is where you narrow individual tools.

Before the call leaves Omniio, the gateway checks the account's burst ceiling, monthly quota, tool policy and any held approval. After the upstream replies, the result is scanned and the call is written to the audit trail.

The name belongs to the server#

Qualified names use a double underscore: server__tool. The prefix is the server slug, not its display label, so two servers may both publish search without colliding.

Never construct a qualified name from memory. Server slugs and upstream tool names can change; the supported path is always search_tools → describe_tool → run_tool.

What counts as a call#

All three tools are metered. Search and description still perform work on your behalf even though they do not reach an upstream. A request refused by the per-minute burst ceiling reaches no upstream and is not billed; the usage page covers monthly accounting and plan limits.

Next: Approvals.