---
name: plungeai-discovery
description: "Find the right thing on PlungeAI's live registry before building anything: agents, structured tools, models, skills, personas, connectors, and saved workflow templates, via hybrid semantic + keyword search (`plungeai_list_agents` MCP / `GET /v1/discovery/search` REST), full capability cards, a platform recommendation endpoint, tool-invocation contracts (`plungeai_get_tool_contract` / `GET /v1/tools/{id}`), and the template gallery (`plungeai_templates`). Use when picking an agent/tool/model/skill for a job, before the first call to an unfamiliar agent, deciding what to build from instead of from scratch, or debugging a refused/unknown id. Ids are live and active-only — never assert one from memory. For running a prompt-driven agent use `plungeai-agents`; for typed tool execution use `plungeai-tools-connectors`; for the model catalog use `plungeai-models`; for CNL workflow authoring use `plungeai-workflows`."
---

# PlungeAI Discovery

The platform's capability catalog — agents, tools, models, skills, personas,
connectors, workflows — is **live and changes without notice**. Discovery is
not an optional first step, it is the mechanism that makes every other
capability usable: an id you did not just get from a live lookup is likely
to be refused at execution.

## Prerequisites

- Self-service `ozk_` key from **Dashboard → One API → Keys**
  (`https://dashboard.plungeai.com`).
- MCP: `https://mcp.plungeai.com/v1`. REST: `https://api.plungeai.com`.

## Discovery first (this IS the discovery-first step)

Never name an agent, tool, connector, or model in generated code, a workflow,
or a reply unless that exact id came from one of the calls below in this
session. "90-something agents" is flavor; the live catalog is the fact.

## 1. Search by capability — MCP

```json
plungeai_list_agents {search: "convert pdf to markdown"}
plungeai_list_agents {kind: "skills", search: "…"}
plungeai_list_agents {agent_id: "exa-agent"}   // full card
```

`kind` filters the catalog segment: `agents` (default, active-only) \|
`personas` \| `experts` \| `skills` \| `models` \| `workflows` \|
`connectors`. Full parameter table and failure modes —
`references/list-and-contract.md`.

## 2. Search by capability — REST

```bash
curl -s "https://api.plungeai.com/v1/discovery/search?q=web%20search&kind=agents&limit=2" \
  -H "Authorization: Bearer ozk_YOUR_KEY"
```

Or let the platform pick for you:

```bash
curl -s -X POST https://api.plungeai.com/v1/discovery/recommend \
  -H "Authorization: Bearer ozk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"type": "agent", "task": "summarize a long PDF into bullet points"}'
```

Full query params (`mode`, `fields`, `include=quality`, …), response shapes,
and the full-card markdown route (`GET /v1/discovery/cards/{type}/{id}`) —
`references/search-and-recommend.md`.

## 3. Inspect before you call — the tool contract

Before the first call to an unfamiliar structured tool-agent (a card with a
Parameters table), fetch its invocation contract — it IS the API docs, and
(over MCP) carries the acting user's live credential status:

```json
plungeai_get_tool_contract {agent_id: "markitdown"}
```

```bash
curl -s https://api.plungeai.com/v1/tools/markitdown -H "Authorization: Bearer ozk_YOUR_KEY"
```

## 4. Starting points instead of from scratch — templates

```json
plungeai_templates {action: "list", category: "research"}
plungeai_templates {action: "get", template_id: "<id>"}
```

Browses Studio's own template gallery (ready-made workflows/agents/bots).
Full detail — `references/list-and-contract.md`.

## Gotchas

- **Substring near-misses are not the same id.** `brave-agent` may exist
  while `brave-search` does not — take ids character-for-character from a
  result, never guess a variant.
- **`count` is a page length, not a catalog total.** Page until a short
  page comes back; don't stop at `offset >= count`.
- **Errors on `/v1/discovery/recommend` and `/v1/discovery/cards/{type}/{id}`
  are always the One API envelope.** The router normalizes the registry's own
  flat `{"error": "<string>"}` rejections into `{"error":{"code","message"}}`
  before they reach you (`code` is `not_found` on a 404, `invalid_request`
  otherwise; the original text lands in `message`) — `err.error.code` is
  always safe to read on these two routes.
- **"My agents" is not the registry.** Users mean their saved workflows
  (`plungeai_list_workflows`) — the registry (`plungeai_list_agents`) is the
  platform's own capability catalog, for when YOU are composing.
- **Discovery finds the contract; it doesn't execute anything.** Fetching a
  card or a contract never runs a workflow or spends a token — it's always
  safe to over-discover.

## Related skills

- `plungeai-agents` — execute a prompt-driven agent once you've found it.
- `plungeai-tools-connectors` — typed execution against a fetched contract, connected-account status.
- `plungeai-models` — the model catalog (`GET /v1/models`) and money plane.
- `plungeai-workflows` — instantiate a template into a saved workflow (`plungeai_templates {action: "use"}`), CNL authoring.
- `plungeai-results-traces` — execution trace lookups (`GET /v1/traces/{id}`), a separate observability surface.
- `plungeai-platform` — how discovery fits into the platform's five layers.