overslash_search

Discover the service instances and actions a caller can reach, by free-text query. Useful when an agent doesn't yet know which service can do what it needs. Each result is one (instance, action) pair, ranked by relevance; an empty query lists every callable instance with no actions (browse mode).

Pre-release

Parameters

Field	Type	Default	Notes
query	string	—	Free-text query. Pass an empty string to list every callable instance with no actions (browse mode).
include_catalog	boolean	false	When true, also surface un-connected templates as setup_required: true rows. The default returns only configured instances the caller can call right now.
exclude	string	—	Comma-separated services to omit. Each entry matches against both the instance name (gmail_work) and the template key (gmail), so one entry can drop a single instance or every instance of a template. Applied before scoring and the result limit.

Result shape

{
  "query": "send an email",
  "results": [
    {
      "service": "gmail_work",
      "template": "gmail",
      "service_display_name": "Google Gmail",
      "account_email": "alice@example.com",
      "action": "send_email",
      "description": "Send an email message",
      "risk": "write",
      "tier": "user",
      "auth": { "type": "oauth", "provider": "google", "connected": true },
      "score": 0.94
    }
  ]
}

Each result carries:

Field	Notes
service	The instance name — pass this verbatim as the service argument to overslash_read / overslash_call. Never pass the template key. Omitted on setup_required rows (no instance is configured yet).
template	Template key. Always present, so two rows from the same template (gmail_work, gmail_personal) are recognizable as siblings.
service_display_name	Human-readable service name.
account_email	OAuth account identifier (e.g. alice@example.com). Present only for OAuth instances whose userinfo lookup returned an email.
secret_name	Variable name of the secret backing an API-key instance — the label only, never the value. Present only for API-key instances.
action	Action name. Absent in browse mode (empty query).
description	Action description. Absent in browse mode.
risk	read, write, or delete. Absent in browse mode.
tier	global, org, team, or user.
auth	{ "type": "oauth" | "api_key", "provider": <string>, "connected": <bool> }. provider is present only for OAuth; connected is false for setup_required rows.
score	Relevance score. Absent in browse mode.
setup_required	true for catalog rows whose template has no configured instance. Present only when include_catalog=true. Set the row up via the dashboard before it becomes callable.

Ranking notes

For a non-empty query, results blend three signals:

1. Keyword + Jaro-Winkler fuzzy scoring over every visible (service, action) pair (weight 0.4) — carries exact matches like stripe or list_repos.
2. Embedding cosine similarity via pgvector top-K (weight 0.6), when embeddings are available for the deployment. Gracefully skipped otherwise.
3. Post-rank bonuses — a connected-instance bonus floats up actions the caller can run right now, plus a small bonus toward read-safer actions.

Browse mode (empty query) skips scoring entirely: instances are sorted connected-first, then alphabetically by display name. The default result limit is 20 and the hard cap is 100; browse mode is not truncated.

Examples

Search for an action:

{ "query": "send an email" }

List every callable instance (browse mode):

{ "query": "" }

Include un-connected templates, dropping one already-tried service:

{ "query": "payments", "include_catalog": true, "exclude": "stripe_test" }