metrx_get_agent_detail

Retrieve detailed information about a specific agent, including its model, framework, category, outcome configuration, and failure risk score.

Instructions

Get detailed information about a specific agent including its model, framework, category, outcome configuration, and failure risk score. Do NOT use for fleet-wide overviews — use get_cost_summary instead.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`agent_id`	Yes	The agent UUID to look up

Implementation Reference

src/tools/dashboard.ts:126-161 (handler)

The main handler implementation for get_agent_detail tool. It validates the agent_id UUID parameter, makes a GET request to /agents/{agent_id}, handles errors, and formats the response using formatAgentDetail.

// ── get_agent_detail ──
server.registerTool(
  'get_agent_detail',
  {
    title: 'Get Agent Detail',
    description:
      'Get detailed information about a specific agent including its model, ' +
      'framework, category, outcome configuration, and failure risk score. ' +
      'Do NOT use for fleet-wide overviews — use get_cost_summary instead.',
    inputSchema: {
      agent_id: z.string().uuid().describe('The agent UUID to look up'),
    },
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: false,
    },
  },
  async ({ agent_id }) => {
    const result = await client.get<AgentDetail>(`/agents/${agent_id}`);

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

    const text = formatAgentDetail(result.data!);

    return {
      content: [{ type: 'text', text }],
    };
  }
);

src/tools/dashboard.ts:127-144 (schema)

Tool registration with input schema definition - validates agent_id as a required UUID string. Includes tool metadata like title, description, and annotations.

server.registerTool(
  'get_agent_detail',
  {
    title: 'Get Agent Detail',
    description:
      'Get detailed information about a specific agent including its model, ' +
      'framework, category, outcome configuration, and failure risk score. ' +
      'Do NOT use for fleet-wide overviews — use get_cost_summary instead.',
    inputSchema: {
      agent_id: z.string().uuid().describe('The agent UUID to look up'),
    },
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: false,
    },
  },

src/index.ts:78-103 (registration)

The registration wrapper that adds the 'metrx_' prefix to all tools. The tool registered as 'get_agent_detail' becomes 'metrx_get_agent_detail'. Also wraps handlers with rate limiting.

const METRX_PREFIX = 'metrx_';
const originalRegisterTool = server.registerTool.bind(server);
(server as any).registerTool = function (
  name: string,
  config: any,
  handler: (...handlerArgs: any[]) => Promise<any>
) {
  const wrappedHandler = async (...handlerArgs: any[]) => {
    if (!rateLimiter.isAllowed(name)) {
      return {
        content: [
          {
            type: 'text' as const,
            text: `Rate limit exceeded for tool '${name}'. Maximum 60 requests per minute allowed.`,
          },
        ],
        isError: true,
      };
    }
    return handler(...handlerArgs);
  };

  // Register with metrx_ prefix (only — no deprecated aliases)
  const prefixedName = name.startsWith(METRX_PREFIX) ? name : `${METRX_PREFIX}${name}`;
  originalRegisterTool(prefixedName, config, wrappedHandler);
};

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

Type definition for AgentDetail interface - extends AgentSummary with additional fields like description, framework_source, primary_model, failure_risk_score, etc.

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/services/formatters.ts:190-224 (helper)

formatAgentDetail helper function that formats the AgentDetail object into a human-readable markdown string with sections for key, category, status, model, framework, risk score, etc.

export function formatAgentDetail(agent: AgentDetail): string {
  const lines: string[] = [
    `## Agent: ${agent.name}`,
    '',
    `**Key**: ${agent.agent_key}`,
    `**Category**: ${agent.category}`,
    `**Status**: ${agent.status}`,
    `**Background**: ${agent.is_background ? 'Yes' : 'No'}`,
  ];

  if (agent.primary_model) {
    lines.push(`**Primary Model**: ${agent.primary_model}`);
  }
  if (agent.framework_source) {
    lines.push(`**Framework**: ${agent.framework_source}`);
  }
  if (agent.outcome_rung) {
    lines.push(`**Outcome Rung**: ${agent.outcome_rung}`);
  }
  if (agent.failure_risk_score !== undefined && agent.failure_risk_score > 0) {
    lines.push(
      `**Failure Risk**: ${formatPct(agent.failure_risk_score)} ${
        agent.failure_risk_score > 0.7 ? '🔴' : agent.failure_risk_score > 0.3 ? '🟡' : '🟢'
      }`
    );
  }
  if (agent.secondary_categories && agent.secondary_categories.length > 0) {
    lines.push(`**Secondary Categories**: ${agent.secondary_categories.join(', ')}`);
  }
  if (agent.last_call_at) {
    lines.push(`**Last Active**: ${agent.last_call_at}`);
  }

  return lines.join('\n');
}

Metrx MCP Server