Tool Discovery (List Agents)

Relevant source files

The following files were used as context for generating this wiki page:

• src/server.ts
• src/agentLoader.ts
• src/types.ts
• scripts/postinstall.js
• README.md
• agents/general-purpose.md

Tool Discovery is a core mechanism in the SuperAgent MCP server that allows clients to programmatically identify and retrieve descriptions of specialized agents available for task execution. This feature is primarily exposed through the list-agents tool, which serves as a registry for curated system prompts and behavioral mindsets stored within the project.

The discovery system ensures that users can see which specialized personas—such as backend-architect, python-expert, or technical-writer—are currently active and valid for use with the main execution tools: codex, gemini, and continue.
Sources: src/server.ts:51-76, README.md:12-25

Architecture and Component Flow

The Tool Discovery system relies on a multi-stage process involving file system synchronization, markdown parsing, and MCP tool registration.

1. Agent Synchronization

Upon installation, a post-install script seeds the user's home directory (~/.superagent/agents) with markdown files from the package. This ensures that the discovery tool has a local directory to query, which users can also extend with custom definitions.
Sources: scripts/postinstall.js:13-52, src/agentLoader.ts:10-53

2. Loading and Parsing Logic

The agentLoader.ts module is responsible for scanning the local agents directory. It parses Markdown files that contain specific frontmatter (YAML-like metadata) to extract the agent's identity.

3. MCP Tool Integration

The server registers the list-agents tool using the Model Context Protocol. When called, it invokes the loader to return a structured list of all valid agents.

Component	Responsibility	Source File
list-agents (Tool)	MCP-exposed interface for discovery	src/server.ts:69-73
loadAgents()	Scans filesystem and returns Agent[] objects	src/agentLoader.ts:101-125
parseAgentFile()	Extracts name, description, and systemPrompt from MD	src/agentLoader.ts:71-100
Agent (Interface)	Defines the data structure for discovered tools	src/agentLoader.ts:7-12

Agent Definition Structure

Agents are discovered based on a specific Markdown format. The discovery engine looks for a frontmatter block delimited by --- at the start of the file.

Data Model Fields

Field	Type	Description	Mandatory
name	string	The unique identifier used in the agent parameter of tools	Yes
description	string	A brief summary of the agent's purpose	Yes
category	string	Grouping for organizational purposes	No
systemPrompt	string	The body of the markdown file (after frontmatter)	Yes
Sources: src/agentLoader.ts:7-12, src/agentLoader.ts:71-100

Example Discovery Source

---
name: general-purpose
description: General-purpose agent for research and code search
category: general
---
# System Prompt Content...

Sources: agents/general-purpose.md:1-7

Discovery Execution Flow

When a client requests the list of tools, the server dynamically generates the descriptions to include the available agents, ensuring the help text is always up-to-date with the filesystem.

Usage in Invocation Tools

Discovered agents are intended to be passed into the agent parameter of the execution tools. The AgentPromptSchema validates these inputs during tool calls.

• Codex/Gemini/Continue: Accepts an optional agent string.
• Validation: The AgentIdentifierSchema ensures the name is between 1 and 64 characters.
  Sources: src/types.ts:5-13, src/server.ts:54-68

Conclusion

The Tool Discovery system provides a dynamic bridge between static configuration files and the MCP runtime. By centralizing agent definitions in Markdown files and exposing them via list-agents, the system allows for easy extensibility while maintaining a clear contract for clients to understand available capabilities.