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), 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 (opens in a new tab) · View raw SKILL.md (opens in a new tab)

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

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

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:

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:

plungeai_get_tool_contract {agent_id: "markitdown"}

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

4. Starting points instead of from scratch — templates

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.

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 GETs are not.

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