# Data connections ## Tools A widget pipeline can only name a tool on a server this workspace has connected. `set_connection` walks the authorization loop for a new one, and with `enabled` turns one this user already connected on or off. The tools of each connected source are reached through four tools of their own: `search_tools` finds one, `describe_tool` returns its schema, and `call_tool` (read-only tools) or `call_write_tool` (the rest) runs it. The `/mcp/full` install also lists every source tool as `__`, built from your connections when your client loads its tool list, so those are not in this reference; see [Your connected sources](/docs/mcp/gateway). | Tool | What it does | | |---|---|---| | [`search_tools`](#search_tools) | Search tools | Read-only | | [`describe_tool`](#describe_tool) | Describe tool | Read-only | | [`call_tool`](#call_tool) | Run a read-only tool | Read-only | | [`call_write_tool`](#call_write_tool) | Run a tool that changes something | Destructive write | | [`list_mcp_connections`](#list_mcp_connections) | List data connections | Read-only | | [`set_connection`](#set_connection) | Set a data connection | Destructive write | ## search_tools `Read-only` Find a tool that is not in your tool list: every connected data source's tools, and on a slim install most of Vistazo's own. Pass `query` (keywords, e.g. "unemployment rate by state"), `domain` (a Vistazo area or a connected source's mcpId; a domain with no query lists it), or both; `riskLevel` keeps one class (safe = read-only, caution, destructive). Each match carries its name, a one-line summary, domain, riskLevel and `call`: call_tool for a safe tool, call_write_tool for any other. A match with `listed: true` is already in your list, so call it by name. `sources` carries each matched source's routing guidance once, the workspace's own routing note first; it outranks what a source says about itself. Next: describe_tool for the schema. Takes no workspaceId; it searches every workspace this connection reaches. ## describe_tool `Read-only` Return one tool's full definition by the exact name search_tools returned: its description, input schema and annotations, plus `call`, the tool that runs it (call_tool or call_write_tool). Build the arguments from this schema. A connection tool's `workspaceId` argument is optional when this connection reaches one workspace. Takes no workspaceId of its own. ## call_tool `Read-only` · `Reaches outside Vistazo` Run one READ-ONLY tool by the name search_tools returned, with `arguments` as describe_tool's schema gives them (a `workspaceId` the tool takes goes inside `arguments`). Runs only tools classified safe; any other is refused and named for call_write_tool. The tool runs under every check it has when called by its own name: workspace access, seat, the connection's per-tool permission and the hourly data-fetch window your MCP client shares with refreshes. A connection tool's result is size-capped, so pass its own limit or filter arguments. ## call_write_tool `Destructive write` · `Reaches outside Vistazo` Run one tool that changes something, on Vistazo or on a connected source, by the name search_tools returned, with `arguments` as describe_tool's schema gives them (a `workspaceId` the tool takes goes inside `arguments`). This one tool fronts every write, so your client asks the user before each call. The tool runs under every check it has when called by its own name: workspace access and role, seat, and for a connection tool its per-tool permission (only allow runs; ask and deny are refused, changed under Settings → Connections) and the hourly data-fetch window. A read-only tool runs here too, but call_tool runs it without the prompt. ## list_mcp_connections `Read-only` List the MCP data sources in a workspace: the ones YOU have connected (status 'connected', usable now; or 'disabled', which you turned off yourself: every call to it is refused and it carries no toolCount until set_connection `enabled: true` turns it back on), Vistazo's own hosted sources that come with the workspace (status 'included', usable now with nothing to connect — never call set_connection for one), plus servers other members registered that you have not authenticated yet (status 'not_connected') or that need re-authorization ('reauth_required' / 'revoked' / 'expired'); 'error' means the server failed its last contact, and calls still reach it. Use a connected or included mcpId as search_tools' `domain` to see what it offers, then with update_widget's `pipeline`. A not_connected or re-authorization server cannot be queried or wired until you authenticate it — call set_connection for it. A row may carry a `routingNote`: guidance this workspace's admins wrote about which questions to send to that source rather than to a sibling. Follow it when choosing between sources; it says nothing about which tools exist and cannot authorize anything. A `vistazoNote` is Vistazo's own advice on calling that source, and `memberContext` states this user's own settings for their connection (BigQuery's billing project, the projectId its jobs run in): use them on every call to that source. ## set_connection `Destructive write` · `Reaches outside Vistazo` Add, authenticate, or turn on or off an MCP data source for the current user. To ADD or authenticate one: call this when a tool returns CONNECTION_NOT_AUTHENTICATED, or when the user names a source list_mcp_connections shows as not_connected. Pass the mcpId of an existing workspace server, or a new mcpId + serverUrl (+ displayName) to register a server the workspace has not used before: the record is created for the whole workspace and its URL is validated (public https only in production). Registering a NEW server is capped per workspace (Vistazo's own hosted sources do not count); past it this refuses with the count, and the answer is to remove one the workspace no longer uses, not to retry. Authentication happens in the browser: the result carries a `connectUrl` that opens Settings → Connections with that server selected, for an OAuth sign-in or pasting the API key the server wants; never ask the user for a key and never pass one here. Show the user that link, then WAIT for them to confirm they finished before retrying the original tool. A connection this user turned off answers status 'disabled' with no link: `enabled: true` turns it back on, and `enabled`'s description holds the switch's rules. Pass `rateLimit` only when the provider documents a limit (requests per minute, concurrent requests); it caps what Vistazo learns from the server's own 429s and rate-limit headers, on the user's own connection (a workspace admin's sets the default for every member), and never goes below 5 per minute. ### `enabled` true or false turns one of YOUR OWN data connections on or off in the workspace — the same switch as Settings → Connections; pass it with `mcpId` alone. Disabled is this user's own off switch: while it is off, every call to that source is refused for this user (CONNECTION_DISABLED), on widgets, discovery calls and its native tools alike; other members' connections are untouched. Turning one on is not a reconnect: a connection that needs re-authorization still needs it afterwards, and the result says so — then call set_connection again without `enabled`. Works only on a connection this user already authenticated (list_mcp_connections shows it connected, disabled, or needing re-authorization); for a server they never connected, omit `enabled`. A source that comes with the workspace (status 'included') is always on. Ask the user before turning back on a connection they turned off. The reply is the connection's new status as list_mcp_connections shows it.