> ## Documentation Index > Fetch the complete documentation index at: https://docs.plungeai.com/llms.txt > Use this file to discover all available pages before exploring further. # Discovery over MCP — list_agents, get_tool_contract, templates (listing) > The registry is LIVE: agents come from the registry service at request time, no static manifest. The registry is LIVE: agents come from the registry service at request time, no static manifest. Only `status:active` agents are listed and callable over MCP; the same fence sits on the execution path, so an id you did not just get from a live search is likely to be refused. Take ids from search results, verbatim, every session. --- ## plungeai_list_agents **Purpose:** discover platform building-block agents from the live registry. NOT the user's saved workflows (that is `plungeai_list_workflows`). Read-only. **Parameters** | Param | Type | Notes | |---|---|---| | `search` | string ≤2000 | Hybrid semantic + keyword query over live agent cards. Describe the capability in natural language ("web search", "convert pdf to markdown", "post a message to a channel") and trust the ranking. | | `category` | string | Registry category filter. | | `agent_id` | string | Fetch ONE full card (markdown: operations, parameters, good-at examples, "Not for → use X instead" redirects). | | `kind` | enum | `agents` (default) \| `personas` \| `experts` \| `skills` \| `models` \| `workflows` \| `connectors`. Only `agents` is filtered active-only (the other kinds do not carry the tag). | | `limit` | int 1–100 | Default 25. | | `format` | `markdown` \| `json` | Response serialization; default markdown. | Every call also takes `user_request` (the user's ask, verbatim — every `plungeai_*` tool does; the platform uses it for routing and diagnostics). **Example** ```json {"user_request": "which agents can read SEC filings?", "search": "financial analysis and SEC filings", "limit": 5} ``` **Returns:** the registry's own markdown — ranked cards for a search, a full card for `agent_id`, the whole catalog (large) when unfiltered. Prefer `search`/`category` over an unfiltered listing. **Failures & fixes** - Unknown `agent_id` → "No registry card with id ... exists" plus a *Closest live matches* section. Not an error state — pick a listed live id or refine `search`. - Non-active `agent_id` → the card is withheld ("only `status:active` agents are listed and callable here") plus live alternatives. Same fix. - "Registry unavailable — try again shortly." → transient; retry once after a pause. **Rules:** never quote the catalog size as fixed; before using an unfamiliar agent, fetch its full card — cards carry parameters and redirects that prevent wrong-agent calls. --- ## plungeai_get_tool_contract **Purpose:** the exact invocation contract for one registry agent, generated live from its card: JSON Schema for parameters, the operation list (with approval-gated operations flagged), worked YAML examples, output shape, and LIVE per-provider credential status for the acting user. Fetch it before the first `plungeai_execute_tool` call to an unfamiliar agent — the contract IS the API docs. Read-only. **Parameters:** `agent_id` (required, string), `format` (`markdown` \| `json`, optional). **Example** ```json {"user_request": "what's the weather in Lisbon this weekend?", "agent_id": "weather-agent"} ``` (`weather-agent` here came from a live search in the same conversation — always derive the id from step 1's results, never from this page.) **Returns:** contract markdown + the same contract machine-readable at `structuredContent.contract` (one field of the ok envelope). The Credentials section is decisive: - `🔐 platform-managed` — nothing for the user to connect; just call. - `✅ connected as ` — the user's account is linked; call away. - `⚠️ NOT connected` / `expired — reconnect` — a required connection is missing: execution will stop with connect instructions until the user connects it (in a PlungeAI app → Connectors). Relay that BEFORE executing. The footer spells the run call: `plungeai_execute_tool {agent_id, operation: "", params: {...}}`. Full typed-execution detail (params, outcome envelope, fences) lives in the `plungeai-tools-connectors` skill. **Failures & fixes:** unknown/inactive id → `unavailable` + alternatives (same fence as execution); "The registry did not answer" → `error`, retry in a few seconds. --- ## plungeai_templates — listing saved workflow templates **Purpose:** browse the platform's gallery of ready-made workflow/agent/bot templates (Studio's own template gallery — same `templates`/`template_versions` D1 rows and KV content, so usage counts stay consistent). This is discovery of **pre-built starting points**, distinct from `plungeai_list_agents` (registry building blocks) and `plungeai_list_workflows` (the user's own saved workflows). **Parameters** (listing actions only — `action: "use"` instantiates a template into a saved workflow and belongs to workflow authoring, see `plungeai-workflows`): | Param | Type | Notes | |---|---|---| | `action` | `"list"` \| `"get"` | `list` — the gallery; `get` — one template's full YAML | | `template_id` | string | Required for `get` (and for `use`) | | `category` | string | Filter for `list` | | `limit` | int 1–100 | `list` only | ```json {"user_request": "what workflow templates are available for research?", "action": "list", "category": "research", "limit": 10} ``` `list` returns a markdown table: Name, Kind, Category, Difficulty, Used (usage count), ID, Description — only `status:active` templates. `get` returns the template's name/description/category/difficulty plus its full YAML in a fenced block — read this before deciding whether to instantiate it with `action: "use"` (`plungeai-workflows`). **Failures & fixes:** `get`/`use` without `template_id` → "template_id is required for this action." — supply the id from a `list` call. Unknown `template_id` → "Template not found: " — re-list. --- ## Putting it together — discover before you build ``` 1. plungeai_list_agents {search: "convert pdf to markdown"} → markitdown 2. plungeai_get_tool_contract {agent_id: "markitdown"} → schema; credentials 🔐 platform-managed 3. plungeai_templates {action: "list", category: "documents"} → any ready-made pipeline to start from instead? ``` Skip step 2 only for agents whose contract you fetched earlier in the same conversation. Execution (`plungeai_execute_agent`, `plungeai_execute_tool`, `plungeai_get_result`) is covered in `plungeai-agents` and `plungeai-tools-connectors`.