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. 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

Every call also takes user_request (the user's ask, verbatim — every plungeai_* tool does; the platform uses it for routing and diagnostics).

Example

{"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

{"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 <email> — 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: "<one of the operations>", 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):

{"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: <id>" — 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.