> ## Documentation Index
> Fetch the complete documentation index at: https://www.plungeai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# plungeai-discovery

> Find the right thing on PlungeAI's live registry before building anything: agents, structured tools, models, skills, personas, connectors, and workflow templates, via hybrid semantic + keyword search (`plungeai_list_agents` MCP / `GET /v1/discovery/search` REST / `ocean-cli discovery search`)…


Find the right thing on PlungeAI's live registry before building anything: agents, structured tools, models, skills, personas, connectors, and workflow templates, via hybrid semantic + keyword search (`plungeai_list_agents` MCP / `GET /v1/discovery/search` REST / `ocean-cli discovery search`), full capability cards, a recommendation (`POST /v1/discovery/recommend`) and a one-answer resolver (`POST /v1/discovery/resolve`), tool-invocation contracts (`plungeai_get_tool_contract` / `GET /v1/tools/{id}`), and the template gallery (`plungeai_templates` / `GET /v1/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, 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 `plungeai-tools-connectors`; for the model catalog `plungeai-models`; for CNL authoring `plungeai-workflows`.

[Download zip](https://skills.plungeai.com/plungeai-discovery.zip) · [View raw SKILL.md](https://skills.plungeai.com/plungeai-discovery/SKILL.md)

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`](/skills/plungeai-discovery/references/list-and-contract).

## 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`](/skills/plungeai-discovery/references/search-and-recommend).

## 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`](/skills/plungeai-discovery/references/list-and-contract).

## Over the One API — every discovery route

Same `ozk_` key (`plungeai-api-setup`). Nothing here runs or spends anything; the two `POST` routes `recommend` and
`resolve` are rate-limited (`429 rate_limited`, `Retry-After`), the catalog `GET`s are not.

| Job | REST | MCP | CLI `ocean-cli …` |
|---|---|---|---|
| search | `GET /v1/discovery/search?q=&kind=&category=&limit=&offset=&mode=&fields=` → `{cards, count, total, searchMethod}` | `plungeai_list_agents {search, kind, category}` | `discovery search Q --kind` |
| one card | `GET /v1/discovery/cards/{type}/{id}` → markdown | `plungeai_list_agents {agent_id}` | `discovery card TYPE ID` |
| best card | `POST /v1/discovery/recommend {type, task}` → `{recommended, card, score}` | — | `discovery recommend TASK` |
| one answer | `POST /v1/discovery/resolve {task, kinds?, category?}` → `{outcome, tool, operation, call: {required_params, example_cnl}, confidence, alternatives}` | — | `discovery search` / `recommend` |
| contract | `GET /v1/tools/{id}` | `plungeai_get_tool_contract` | `tools get ID` |
| templates | `GET /v1/templates?kind=&category=&limit=` → `{templates, count}`; `GET /v1/templates/{id}` → `{template, yaml}`; `POST /v1/templates/{id}/use {name?}` → `201 {workflow}` | `plungeai_templates` `list` / `get` / `use` | `templates list` / `get` / `use` |

What builders get wrong:

- **Page with `total`, not `count`.** `count` is this page's length; search also returns `total` (every card the
  filters match). `GET /v1/agents` and `GET /v1/tools` have only `count`: page until a short page.
- **REST knows more kinds than MCP.** REST `kind`: `agents`, `skills`, `digital-twins`, `personas`, `experts`,
  `backgrounds`, `workflows`, `models`, `providers`, `connectors`, `plugins`, `mcp-servers`; the MCP tool's `kind`
  stops at `agents`, `personas`, `experts`, `skills`, `models`, `workflows`, `connectors`. A card URL takes the
  singular type (`agent`, `digital_twin`, `mcp_server`, …); the plural kinds are accepted as aliases.
- **`recommended` can be `null` (score `0`).** On `resolve`, act only on `outcome: "match"` with a real
  `confidence` (`null` is the keyword fallback); `uncertain` and `none` mean read the cards yourself.
- **Agent cards carry `credential`** (`{tier: "platform"}` or `{tier: "connection", provider, method}`): read it
  before you call, so a connection-tier agent does not surprise you with a `424` (`plungeai-tools-connectors`).
- **A template `use` is a copy that is yours.** It creates a saved workflow of the template's kind and runs the
  same save-time lint (`422 invalid_workflow`, nothing created); `404 template_not_found` for an inactive id.
- Model cards read `provider:model`; the model routes take the `provider/model` slug from `GET /v1/models`
  (`plungeai-models`).
- **MCP `format: "json"` is not typed rows.** On `plungeai_list_agents` it wraps the rendered markdown as
  `{content: "<markdown>"}`; for machine-readable cards use `GET /v1/discovery/search` (or `ocean-cli discovery
  search --json`).

## 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 (search also answers `total`); 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.

## Reference pages

<CardGroup cols={2}>
<Card title="Discovery over MCP — list_agents, get_tool_contract, templates (listing)" icon="file-text" href="/skills/plungeai-discovery/references/list-and-contract">
The registry is LIVE: agents come from the registry service at request time, no static manifest.
</Card>
<Card title="Discovery — /v1/discovery" icon="file-text" href="/skills/plungeai-discovery/references/search-and-recommend">
Discovery is the live catalog of everything the platform can do — agents, workflows, MCP servers, connectors, models — with hybrid semantic + keyword search…
</Card>
</CardGroup>