get_costs

Instructions

Implementation Reference

• mcp-server/src/tools.ts:118-131 (handler)

  The 'get_costs' tool definition with its handler. The handler calls client.getCosts() and returns the JSON-serialized result.

  {
    name: "get_costs",
    description:
      "Get cost breakdown for the current month: total spend, cost by model, " +
      "and estimated savings from guard interventions.",
    inputSchema: {
      type: "object",
      properties: {},
    },
    handler: async (client) => {
      const result = await client.getCosts();
      return JSON.stringify(result, null, 2);
    },
  },

• mcp-server/src/client.ts:71-77 (helper)

  The getCosts() method on AgentGuardClient that calls the REST API endpoint /api/v1/costs and returns typed cost data including monthly totals, per-model costs, and guard savings.

  async getCosts() {
    return this.fetch<{
      monthly: { total_cost: number; trace_count: number };
      by_model: Array<{ model: string; total_cost: number; call_count: number }>;
      savings: { guard_events: number; estimated_savings: number };
    }>("/api/v1/costs");
  }

• mcp-server/src/tools.ts:15-177 (registration)

  The 'get_costs' tool is registered as part of the 'tools' array exported from tools.ts, alongside other tools like query_traces, get_trace, etc.

  export const tools: ToolDefinition[] = [
    {
      name: "query_traces",
      description:
        "Search recent traces from your AgentGuard-instrumented agents. " +
        "Filter by service name, time range, or paginate through results.",
      inputSchema: {
        type: "object",
        properties: {
          limit: { type: "number", description: "Max traces to return (default 20, max 500)" },
          offset: { type: "number", description: "Offset for pagination" },
          service: { type: "string", description: "Filter by service name" },
          since: { type: "string", description: "ISO timestamp — only traces after this time" },
          until: { type: "string", description: "ISO timestamp — only traces before this time" },
        },
      },
      handler: async (client, args) => {
        const result = await client.getTraces({
          limit: args.limit ? String(args.limit) : "20",
          offset: args.offset ? String(args.offset) : undefined,
          service: args.service as string | undefined,
          since: args.since as string | undefined,
          until: args.until as string | undefined,
        });
        return JSON.stringify(result, null, 2);
      },
    },
    {
      name: "get_trace",
      description:
        "Get the full event tree for a specific trace by its trace ID. " +
        "Shows all spans, tool calls, LLM calls, guard triggers, and errors.",
      inputSchema: {
        type: "object",
        properties: {
          trace_id: { type: "string", description: "The trace ID to look up" },
        },
        required: ["trace_id"],
      },
      handler: async (client, args) => {
        const result = await client.getTrace(args.trace_id as string);
        return JSON.stringify(result, null, 2);
      },
    },
    {
      name: "get_trace_decisions",
      description:
        "Extract normalized decision.* events from one trace. " +
        "Use this when a workflow includes proposal, override, approval, or binding steps.",
      inputSchema: {
        type: "object",
        properties: {
          trace_id: { type: "string", description: "The trace ID to inspect for decision events" },
        },
        required: ["trace_id"],
      },
      handler: async (client, args) => {
        const traceId = args.trace_id as string;
        const result = await client.getTrace(traceId);
        const events = Array.isArray(result.events) ? result.events : [];
        const decisions = extractDecisionEvents(events as Array<Record<string, unknown>>, {
          traceId,
        });
        return JSON.stringify({ trace_id: traceId, decisions }, null, 2);
      },
    },
    {
      name: "get_alerts",
      description:
        "Get recent guard alerts (loop detection, budget exceeded) and errors. " +
        "Useful for checking if your agents are hitting safety limits.",
      inputSchema: {
        type: "object",
        properties: {
          limit: { type: "number", description: "Max alerts to return (default 50)" },
          since: { type: "string", description: "ISO timestamp — only alerts after this time" },
        },
      },
      handler: async (client, args) => {
        const result = await client.getAlerts({
          limit: args.limit ? String(args.limit) : undefined,
          since: args.since as string | undefined,
        });
        return JSON.stringify(result, null, 2);
      },
    },
    {
      name: "get_usage",
      description:
        "Check your current event quota usage and plan limits. " +
        "Shows event count vs limit, retention period, and plan details.",
      inputSchema: {
        type: "object",
        properties: {},
      },
      handler: async (client) => {
        const result = await client.getUsage();
        const pct = result.event_limit > 0
          ? ((result.event_count / result.event_limit) * 100).toFixed(1)
          : "0";
        return JSON.stringify({ ...result, usage_percent: `${pct}%` }, null, 2);
      },
    },
    {
      name: "get_costs",
      description:
        "Get cost breakdown for the current month: total spend, cost by model, " +
        "and estimated savings from guard interventions.",
      inputSchema: {
        type: "object",
        properties: {},
      },
      handler: async (client) => {
        const result = await client.getCosts();
        return JSON.stringify(result, null, 2);
      },
    },
    {
      name: "check_budget",
      description:
        "Quick pass/fail budget health check. Combines usage quota and cost data " +
        "to give a summary of whether you're within safe operating limits.",
      inputSchema: {
        type: "object",
        properties: {},
      },
      handler: async (client) => {
        const [usage, costs] = await Promise.all([
          client.getUsage(),
          client.getCosts(),
        ]);
  
        const usagePct = usage.event_limit > 0
          ? (usage.event_count / usage.event_limit) * 100
          : 0;
  
        const status = usagePct >= 90
          ? "critical"
          : usagePct >= 75
            ? "warning"
            : "healthy";
  
        return JSON.stringify(
          {
            status,
            plan: usage.plan,
            events: {
              used: usage.event_count,
              limit: usage.event_limit,
              percent: `${usagePct.toFixed(1)}%`,
            },
            costs: {
              monthly_total: costs.monthly.total_cost,
              trace_count: costs.monthly.trace_count,
            },
            savings: costs.savings,
          },
          null,
          2,
        );
      },
    },
  ];

• mcp-server/src/tools.ts:4-13 (schema)

  The ToolDefinition interface that defines the schema shape including name, description, inputSchema (with properties and required fields), and the handler function signature.

  export interface ToolDefinition {
    name: string;
    description: string;
    inputSchema: {
      type: "object";
      properties: Record<string, unknown>;
      required?: string[];
    };
    handler: (client: AgentGuardClient, args: Record<string, unknown>) => Promise<string>;
  }