plungeai-discovery

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.

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.

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.

Reference pages