Provider catalog

The catalog is the set of provider tools you can call from a tool column, an enrichment waterfall, a workflow step, or directly via oxygen tools run.

Two surfaces

Prefer the native equivalent when both exist.

Which providers exist today, their auth mode, and how many operations each one exposes: provider reference.

Tool descriptor shape

Searching

oxygen tools search <query> --json
oxygen tools search --provider blitzapi --all --no-access-check --json
oxygen tools search people --capability mobile_phone --only-runnable --json
oxygen tools search --no-access-check --terse --limit 100 --json   # fast bounded catalog discovery
oxygen tools get <tool-id> --json
oxygen tools enums list --json
oxygen tools enums get blitzapi industry --query software --json

tools search accepts free-text plus capability filters. tools get returns the full descriptor, including input and output schemas.

Inspecting one selection

CLI and HTTP descriptor reads retain full detail by default. MCP oxygen_tools_get starts with a compact summary view. Its projection.omitted_paths lists the metadata not returned; the schema completeness flags state whether an exact input or output schema is included. Request pricing, access, guidance, examples, input_schema, output_schema, or full for the details needed next.

For native provider fields, first use field_names, optionally with field_query, then native_fields with exact field_keys. These are native metadata views, including authored aliases and enum references. They are not executable schemas and do not establish that an alias or example is accepted. Fetch accepted enum values with oxygen_tools_enums_get.

oxygen tools get blitzapi.people_search --view field_names --field-query title --json
oxygen tools get blitzapi.people_search --view native_fields --field-keys people.job_title.include,company.industry.include --max-chars 4000 --json
oxygen tools get blitzapi.people_search --view input_schema --json

A requested context window returns the entire selected view or a typed size refusal. Schemas are never shortened. Use smaller metadata views or target native field keys after a refusal; no descriptor cursor or pagination is implied. CLI full reads without --max-chars retain the full native artifact.

Provider operations and native Table columns differ from executable MCP tool definitions. Discover MCP capabilities with oxygen_capabilities_search, retrieve the selected complete definition with oxygen_capabilities_schema, then use its recommended read or write gateway. Reading catalog metadata does not authorize a provider call, a paid action, or a workspace change.

Use a broad brand-name query to discover a provider id, then --provider <id> --all for an exact inventory. This avoids treating fuzzy matches from other vendors as part of that provider's surface. For example, the provider id for Blitz is blitzapi; its current catalog contains 22 operation ids backed by 19 distinct routes (three ids are compatibility aliases).

The response's total_tools counts every match for your query and filters (not just the rows returned under --limit), so the empty-query --all --no-access-check form is the fast way to inventory the whole catalog: it skips per-tool availability checks and returns compact descriptors without availability info. Every response carries counts_complete. When it is true, total_tools is exact. When it is false, partial_sources names the catalog source that did not answer (for example the Composio directory) and the totals are understated — retry, and the CLI prints a warning to stderr when this happens. A separate access_check_failures list names tools whose availability could not be determined; those tools are still in the catalog and the totals remain exact.

Every row also carries per-row pricing: estimated_credits_per_row, pricing_kind (fixed for a list price every row pays, estimated for an expected value or a ceiling), estimate_basis (list_price, expected, ceiling, floor, or default_request), a ready-to-read price_label ("0.05 credits/call", "~1.925 credits/row", "up to 222.75 credits/row", "free", or "priced at run time"), and provider_count. A BYOK call on your own provider key pays OXYGEN's 0.05-credit platform fee per call; its price_label includes that fee. estimated_credits_per_row: 0 means no OXYGEN charge for the row. null means the price is only known at run time — preview or dry-run the column instead of quoting it.

A scalable provider quote uses estimate_basis: default_request: the resolver prices an empty estimator input (quote_input: {}) using its defaults. cost.managed_credit_estimate.default_request_credits names that quote; the retained min and billing.managed_credit_band.floor fields are compatibility aliases when quote_basis: default_request, not lower bounds. AI Ark people search defaults to 10 requested person slots (25 Oxygen credits); requesting one previews at 2.5, while its size-25 example previews at 62.5. A Table row invokes the tool once, so the row quote depends on that invocation's requested page size. Preview exact inputs before quoting a run.

cost_hint uses provider-native units and sets customer_charge: false; the Oxygen customer price comes from cost.managed_credit_estimate and the native preview. For example, AI Ark's seed consumption is 0.5 provider credits per requested person slot, converted to 2.5 Oxygen credits by its current seed pricing. Blitz uses a fixed monthly managed subscription with zero marginal provider cost; its customer people-search quote remains 1 Oxygen credit per call for either 1 or 10 requested results. Customer prices are resolved from the current control-plane configuration, so provider-native hints do not authorize spend or fix a future customer rate.

MCP catalog searches return a native context window of whole cards. include_native=false omits native column metadata (favorite searches retain their native entries); workflow_eligible=true selects hosted-workflow tools and carries their canonical workflow_effect. CLI uses --no-include-native and its existing --workflow-eligible flag. returned_tools is the number of tool cards present; projection.arrays reports selected, retained and omitted entries for every array. counts_complete describes catalog-source coverage, while projection.returned_complete says whether the response exposes every selected entry and known tool match. Provider summary counts describe the selected tools before the context window, so they are labelled separately from the retained cards. In the workflow-eligible view, legacy total_tools excludes synthetic oxygen_* capabilities and may count provider-source rows before workflow eligibility filtering. The exact array counts include the synthetic capabilities; projection.returned_complete remains false because this native view supplies no combined eligible total.

Search has no cursor. Narrow oversized results with provider, category, capability or text, prefer verbosity=minimal, then inspect one selection with oxygen_tools_get. Executable MCP definitions use oxygen_capabilities_schema; provider operations run through oxygen_tools_run_dry / oxygen_tools_run_live. Native Table columns belong to oxygen_columns_catalog and oxygen_enrichment_catalog, and are configured with oxygen_columns_add. Workflow-eligible oxygen_* rows are named MCP capabilities: inspect their definitions and executable gateway with oxygen_capabilities_schema, rather than sending them through a provider run gateway. These references convey a path; live tools still enforce their own approval, credit and access requirements.

The native HTTP and CLI defaults retain their full responses. CLI callers can opt into the same contract with oxygen tools search people --max-chars 4000 --json. A complete schema or card that exceeds its window returns catalog_window_exceeded; schemas are never shortened to make them fit. The connector retains its existing external catalog widget; built-in agents receive plain JSON; unattended Agents also budget their complete duplicate result envelope.

Per-plan BYOK daily call thresholds and every other default ceiling: pricing reference.

Running a tool

oxygen tools run <tool-id> --input-json '{"first_name":"Ada","domain":"acme.com"}' --mode dry-run --json
oxygen tools run <tool-id> --input-json '{...}' --mode live --approved --max-credits 5 --json

Use dry-run first. Live calls can consume credits or write externally depending on the tool, so keep one-off live runs small and prefer table runs for batches.

Bulk runs go through a run:

oxygen table-ingestions create-tool-page <table-id> --tool <tool-id> --request-json '{...}' --max-credits <cap> --json

This writes each result as a row. --max-credits is required for paid tools; take the cap from the dry run's credit estimate times the pages you fetch.

Checking access

oxygen tools search <query> --only-runnable --json
oxygen integrations list --json

--only-runnable filters to tools the active org can currently call. If a tool is missing, check whether it requires a connected integration. MCP also exposes oxygen_tools_check_access for agents that need a structured access check.

Related

• Columns — wrapping a tool as a per-row column.
• Waterfalls — running providers in fallback order.
• Integrations — connecting BYOK accounts.
• LinkedIn data access — choosing between the managed scraper.* operations and a connected account.