Discovery

Source: orchestration/mcp-gateway/server.ts (TOOL_DEFS, SERVER_INSTRUCTIONS), orchestration/mcp-gateway/tools.ts (ListAgentsSchema, listAgents), orchestration/mcp-gateway/tool-exec.ts (getToolContract), orchestration/mcp-gateway/credential-preflight.ts, orchestration/mcp-gateway/registry-cards.ts, orchestration/mcp-gateway/extras.ts (TemplatesSchema, plungeaiTemplates), core/core-base/tool-contract.ts, orchestration/registry/registry.ts (search markdown, KIND_GROUPS); registry reads live-verified 2026-09-24.

Before you run anything, find it. Discovery is three steps. Each one is a read-only tool call that costs no credits:

Find      ──►  plungeai_list_agents         search the live registry (active agents only)
Inspect   ──►  plungeai_get_tool_contract   typed params, operations, approval gates, YOUR credential status
Execute   ──►  plungeai_execute_tool · plungeai_execute_agent · an agent: task in a workflow

plungeai_templates (list / get) is the fourth discovery tool. It lists ready-made workflows. All examples use https://mcp.plungeai.com/v1. https://api.plungeai.com/v1/mcp is the same server behind the One API (Overview). Every tool accepts user_request, the user's words verbatim. Always send it (Protocol & transport). Full parameter tables are in the Tool reference.

5.1 Registry agents vs your workflows

Two different things are both called "agents". The server's initialize instructions teach every client the difference (SERVER_INSTRUCTIONS in server.ts):

An unqualified "show me my agents" means your workflows. plungeai_list_agents is only for the registry: when the user says registry, discovery or platform agents, or when the client itself is choosing building blocks for a workflow.

plungeai_list_agents with kind: "workflows" searches the registry's public workflow cards. Those are not your workflows.

5.2 Search the registry — plungeai_list_agents

One tool, five modes. The mode is picked from the arguments you send:

Other arguments:

• kind: which card set to search. agents is the default. See the table below.
• limit: 1 to 100. It overrides the defaults above.
• format: "json" returns {"content": "<the same markdown>"} as text and as structuredContent. The source is rendered registry markdown; there are no typed rows yet (tool description, server.ts).

search is semantic, so describe the capability, not a name: "web search", "convert pdf to markdown", "post to slack". The registry ranks the results. Trust the ranking.

The catalog is active-only. For kind: "agents" the gateway always adds status=active to the registry query (listAgents in tools.ts). Every agent it lists is deployed and callable. The execution tools refuse any id that is not status:active (Tools, Agents & missions). So take agent ids from a live search, never from memory, another platform, or a guess.

Try asking

• "What agents do you have for financial analysis and SEC filings?"
• "Which agent should I use to turn a PDF into markdown?" The search is semantic. For this one you get pdf-worker, markitdown and ms-office-worker, and each card says what it is not for (pdf-worker → "Extracting text from existing PDFs → use doc-converter"). Live-verified 2026-09-24.
• "What connectors are available?" Also try personas, experts, skills and models.
• "What agents are in the registry for web search?"

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_list_agents","arguments":{"user_request":"Which agent should I use to turn a PDF into markdown?","search":"convert pdf to markdown","limit":3}}}'

The result text is the registry's own markdown, passed through unchanged. An abridged excerpt (live registry, 2026-09-24):

# Registry search — q="convert pdf to markdown"

*3 results*

## PDF Worker (`pdf-worker`)
*agent · tools · status:active*

Generates PDF documents from Markdown content. …

**Good at:**
- Converting meeting notes in Markdown to a shareable PDF document (exportToPdf)
…

**Not for:**
- Extracting text from existing PDFs → use `doc-converter` (pdf-worker generates PDFs; it does not parse or extract content from existing PDF files)
…

## markitdown (`markitdown`)
*agent · tools · status:active*
…

Each result has a heading with the name and id, a line with type, category and status, the description, Good at: and Not for:. The *N results* line counts the results on this page, not the catalog total.

Not-for redirects come from the card as written. A redirect target is not checked against the active catalog. On 2026-09-24, sec-agent's card said "Real-time stock quotes → use alpha-vantage", and alpha-vantage is status:testing, so execution refuses it. Before you use a redirect target, check it with search or agent_id.

Kinds

kind picks the card set (KIND_GROUPS in orchestration/registry/registry.ts):

The status filter applies only to agents on purpose. Almost no card in the other sets carries status:active (personas, experts and workflows none, skills 1 of 1,053 when the rule was written), so filtering would empty the list (comment in listAgents).

Categories

On 2026-09-24 the live catalog held 92 active agents in 14 categories: ai, blockchain, coding-agents, communication, ecommerce-agents, entertainment, financials, google-workspace, media, microsoft-365, payment, search, shopping, tools. Category values must match exactly. The finance category is financials: category: "finance" returns *0 results* (live-verified 2026-09-24). If you are unsure, use search ("agents for financial analysis") and let the ranking work. For counts per category, read the plungeai://agents/categories resource (Prompts & resources).

Don't ask for "all agents". An unfiltered listing is large. On 2026-09-24 the full active catalog in markdown was about 150 KB, all of it going into your client's context in one call. Always filter by search, category or kind.

When the registry does not answer

These are plain text errors, not outcome envelopes. plungeai_list_agents has no outputSchema. Retry after a few seconds.

5.3 Read one full card — agent_id

agent_id returns the agent's complete card as markdown (GET /api/cards/agent/<id>?fields=full on the registry). It includes the description, Best for, the Not for table, the prompt format, operations, parameters, examples, output, credentials, demonstrations and tags. Fetch it before the first use of an unfamiliar agent. Cards are several KB each (weather-agent: about 12.7 KB, live 2026-09-24).

agent_id takes precedence: search, category and kind are ignored when agent_id is set. It always reads an agent card.

Try asking: "Show me the full card for sec-agent — what operations does it support?"

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_list_agents","arguments":{"user_request":"Show me the full card for the weather agent","agent_id":"weather-agent"}}}'

A wrong or inactive id is not an error. The answer is guidance with live near-matches, and isError stays false:

The MCP server never shows a non-active card, not even when you ask for it by id.

5.4 The invocation contract — plungeai_get_tool_contract

Structured agents are forms, not chats. A card with a Parameters table (markitdown, weather-agent, the Gmail agent, …) takes typed fields, not a sentence. plungeai_get_tool_contract gives your client the exact form. It lists every typed field, the operations and which of them need approval, worked examples, and the live credential status for your account. Then the client fills the form and calls plungeai_execute_tool. The contract is the API documentation for that agent.

You can also just ask about an agent in plain language. The answer comes from its card (what it is good at, what to use instead) and its contract (the exact fields, and whether you are set up):

• "Before I use the Gmail agent — what exactly does it need from me, and am I connected?"
• "What is the x402 broker for?"
• "Can I search Amazon and pay with x402? What information do you need from me?"

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_get_tool_contract","arguments":{"user_request":"What does the weather agent need from me?","agent_id":"weather-agent"}}}'

What comes back

The text is Markdown in this order (renderContractMarkdown in tool-contract.ts, then getToolContract in tool-exec.ts):

1. # <Name> (`<id>`) and the description.
2. ## Operations: one line per operation, with its purpose, (requires: …) for fields that only that operation needs, and ⚠️ GATED: requires explicit user approval on gated operations.
3. ## Parameters: one line per field, with its type, required, one of: … (enums read from the card), default: … and the description.
4. ## Examples: up to three worked CNL snippets from the card's demonstrations.
5. **Returns:**: the card's output description.
6. ## Credentials: your live status (table below).
7. A closing line: Run it: plungeai_execute_tool {agent_id: "<id>", operation: "<one of the operations above>", params: {<the parameters above>}}. Gated operations pause for user approval — relay the ⏸ block and continue with plungeai_continue. The hint is the server's own text. A gated floor operation run through plungeai_execute_tool comes back as a trust-fence refusal that plungeai_continue cannot resume; it runs only from Ocean Studio (6.6).

An excerpt for weather-agent (rendered from the live card, 2026-09-24):

# Weather Agent (`weather-agent`)

Complete OpenWeatherMap client: current conditions, 5-day/3-hour forecast, … EVERY location-based operation accepts either lat/lon coordinates OR a `location` city name …

## Operations

- `current` — Real-time weather conditions
- `forecast` — 5-day forecast with 3-hour intervals
- `air-quality` — Current AQI (OWM 1-5 scale) + pollutant components
- `air-quality-history` — Historical AQI between start and end (requires: start, end)
- `one-call-timemachine` — Weather at a past/future moment (requires: dt)
…

## Parameters

- `lat` (number): Latitude - optional when `location` is given (auto-geocoded)
- `location` (string): City name auto-geocoded to coordinates, e.g. "Hamburg,DE" or "Sun Valley,ID,US" …
- `units` (string): `standard` (Kelvin) | `metric` (Celsius, default) | `imperial` (Fahrenheit)
- `start` (number): Unix start time — (operation: air-quality-history, required there)
…

## Credentials
- 🔐 Platform-managed — nothing for the user to connect.

structuredContent is the outcome envelope (6.4) with the contract attached:

{
  "status": "ok",
  "agent_id": "weather-agent",
  "summary": "Contract for weather-agent",
  "contract": {
    "agent_id": "weather-agent",
    "name": "Weather Agent",
    "description": "…",
    "operations": [{ "name": "air-quality-history", "purpose": "…", "gated": false, "required_params": ["start", "end"] }],
    "inputSchema": { "type": "object", "properties": { "location": { "type": "string", "description": "…" } }, "required": [], "additionalProperties": true },
    "examples": [{ "title": "Current weather by city name (no coordinates)", "cnl": "agent: weather-agent\noperation: current\n…" }],
    "output_type": "…",
    "credentials": []
  }
}

With format: "json" the text becomes this same object as a JSON document. The Markdown ## Credentials lines are then not in the text, but contract.credentials carries the same data.

Contract fields

How the contract is built

The card's parameter types are free text written by people. The generator never throws: an unknown type becomes string, and the raw type is kept in the description (buildToolContract in tool-contract.ts). These rules shape what your client sees:

• Envelope names are skipped. agent, type, id, operation, depth, user_id, executor_user_id, workflow, execution_id belong to the task envelope. They never appear as params. The operation goes in plungeai_execute_tool's own operation argument.
• Credential fields are never required. access_token, api_key, apikey, bearer_token, oauth_token, refresh_token are shown with "(platform-injected from your connected account at runtime — do NOT supply)".
• Operation-specific requireds live on operations[].required_params and are enforced only when you run that operation.
• prompt as an alias. When a card marks prompt and another text field required together (for example query + prompt), prompt is made optional.
• Old multi-operation cards. On a card with two or more operations and no per-operation attribution, the fields it marks required are moved into the description as "(required by some operations — see the examples)". Otherwise every call would be refused for fields that belong to other operations.
• Gated operations are the platform floor list (buy, purchase, fetch_paid, send, transfer, pay, send_payment, withdraw, shop) plus any gated:<op> tag on the card. See The trust fence.

Credentials section

The ## Credentials lines come from the agent's credential requirements (6.7) and a live status lookup for the calling user:

Outcomes

The tool is read-only (readOnlyHint: true). Card lookups are cached for 60 seconds per gateway isolate (registry-cards.ts), so an agent that was just deactivated can still look active for up to a minute.

5.5 Workflow templates — plungeai_templates list and get

Templates are a platform-wide library of ready-made workflows. They are the same rows Studio's gallery shows (templates / template_versions in D1, content in KV). Three actions:

Try asking: "What workflow templates are available? Start one from the due-diligence template." The client lists the templates, finds the due-diligence one, then calls use (Workflows).

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_templates","arguments":{"user_request":"What workflow templates are available?","action":"list","limit":10}}}'

To read one template's YAML, pass its id from the list:

# get needs a real template id from the list above
curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"plungeai_templates","arguments":{"user_request":"Show me the due-diligence template","action":"get","template_id":"<template id>"}}}'

plungeai_templates is not marked read-only, because use writes a workflow. list and get change nothing. The tool has no format argument; its output is always Markdown.

5.6 Other discovery surfaces

• Resources. plungeai://agents/list, plungeai://agents/categories, plungeai://personas/list and the plungeai://agents/{category} template read the same live registry (agents active-only). plungeai://docs/workflow-authoring is the full CNL authoring guide. See Prompts & resources.
• The /plungeai prompt gives the client the whole discover → inspect → execute routine in one message (Prompts & resources).
• Over HTTP. The One API has the same catalog as REST routes: GET /v1/discovery/search and GET /v1/tools/{id} (https://api.plungeai.com/docs#8-discovery (opens in a new tab), https://api.plungeai.com/docs#6-tools-plane (opens in a new tab)).
• Skills for your client. https://skills.plungeai.com (opens in a new tab) has installable skills that teach Claude Code, Cursor and other clients these same patterns (Connecting clients).