metrx_list_agents

List all AI agents in your organization with status, category, and cost information. Filter results by status or category to identify available agents for operational tasks.

Instructions

List all AI agents in your organization with their status, category, and cost. Optionally filter by status or category. Returns agent IDs needed for other tools. Do NOT use for detailed per-agent analysis — use get_agent_detail for that.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`status`	No	Filter by agent status
`category`	No	Filter by agent category (e.g., "sales", "support", "engineering")

Implementation Reference

src/tools/dashboard.ts:64-124 (handler)

Main implementation of the list_agents tool. Registers the tool with name 'list_agents' (auto-prefixed to 'metrx_list_agents' by the server middleware), defines the input schema with optional status and category filters, and implements the handler logic that calls the /agents API endpoint and formats the results as a readable list of agents with their IDs, names, status, category, monthly costs, and ROI multipliers.

server.registerTool(
  'list_agents',
  {
    title: 'List Agents',
    description:
      'List all AI agents in your organization with their status, category, and cost. ' +
      'Optionally filter by status or category. Returns agent IDs needed for other tools. ' +
      'Do NOT use for detailed per-agent analysis — use get_agent_detail for that.',
    inputSchema: {
      status: z
        .enum(['active', 'idle', 'error', 'archived'])
        .optional()
        .describe('Filter by agent status'),
      category: z
        .string()
        .optional()
        .describe('Filter by agent category (e.g., "sales", "support", "engineering")'),
    },
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: false,
    },
  },
  async ({ status, category }) => {
    const params: Record<string, string> = {};
    if (status) params.status = status;
    if (category) params.category = category;

    const result = await client.get<{ agents: AgentDetail[] }>('/agents', params);

    if (result.error) {
      return {
        content: [{ type: 'text', text: `Error listing agents: ${result.error}` }],
        isError: true,
      };
    }

    const agents = result.data?.agents || [];
    if (agents.length === 0) {
      return {
        content: [{ type: 'text', text: 'No agents found matching the specified filters.' }],
      };
    }

    const lines: string[] = [`## Agents (${agents.length})`, ''];
    for (const agent of agents) {
      const cost = agent.monthly_cost_cents ? formatCents(agent.monthly_cost_cents) : 'N/A';
      const roi = agent.roi_multiplier ? ` | ${agent.roi_multiplier.toFixed(1)}x ROI` : '';
      lines.push(
        `- **${agent.name}** [${agent.agent_key}] — ${agent.status} | ${agent.category} | ${cost}/mo${roi}`
      );
      lines.push(`  ID: ${agent.id}`);
    }

    return {
      content: [{ type: 'text', text: lines.join('\n') }],
    };
  }
);

src/tools/dashboard.ts:72-81 (schema)

Input schema definition for list_agents tool using zod validation. Defines optional 'status' parameter (enum: active, idle, error, archived) and 'category' parameter (string) for filtering the agent list.

inputSchema: {
  status: z
    .enum(['active', 'idle', 'error', 'archived'])
    .optional()
    .describe('Filter by agent status'),
  category: z
    .string()
    .optional()
    .describe('Filter by agent category (e.g., "sales", "support", "engineering")'),
},

src/types.ts:30-40 (schema)

AgentDetail interface type definition used for the list_agents tool response. Extends AgentSummary with additional fields like description, framework_source, outcome_rung, primary_model, failure_risk_score, secondary_categories, and created_at.

export interface AgentDetail extends AgentSummary {
  description?: string;
  parent_agent_id?: string;
  framework_source?: string;
  outcome_value_cents?: number;
  outcome_rung?: string;
  primary_model?: string;
  failure_risk_score?: number;
  secondary_categories?: string[];
  created_at: string;
}

src/tools/dashboard.ts:14-14 (registration)
The registerDashboardTools function exports the registration logic that is called from src/index.ts line 106. This function registers all dashboard-related tools including list_agents with the MCP server.
```
export function registerDashboardTools(server: McpServer, client: MetrxApiClient): void {
```
src/services/formatters.ts:21-23 (helper)
The formatCents helper function used by list_agents handler to convert monthly_cost_cents values to dollar string format for display in the agent list output.
```
export function formatCents(cents: number): string {
  return `$${(cents / 100).toFixed(2)}`;
}
```

Metrx MCP Server