record_value_metric

Instructions

Implementation Reference

• src/mcp/tools/value-metrics.ts:66-126 (handler)

  The `registerRecordValueMetricTool` function registers the 'record_value_metric' MCP tool. It defines the Zod schema for inputs (workflow_id, workflow_type, agent_id, autonomy_level, measurement_source, time_saved_minutes, risk_blocked_count, success, task_complexity), constructs a ValueMetricEntry, pushes it to an in-memory store, calculates running economic totals (time saved, cost saved, model costs, risks blocked, success rate), emits telemetry via engine.telemetryService.emitToolCall, and returns the recorded metric with running totals.

  export function registerRecordValueMetricTool(server: McpServer, engine: GovernanceEngine): void {
    server.tool(
      'record_value_metric',
      'Record a workflow value metric — tracks time saved, risk blocked, success rate, autonomy level, and task complexity for ROI reporting.',
      {
        workflow_id: z.string().max(100).describe('Unique workflow identifier'),
        workflow_type: z.string().max(100).describe('Type of workflow (e.g., claim-analysis, evidence-review, compliance-check)'),
        agent_id: z.string().max(100).describe('Agent that performed the workflow'),
        autonomy_level: z.enum(['assist', 'delegate', 'automate']).describe('Level of agent autonomy'),
        measurement_source: z.enum(['measured', 'estimated', 'derived']).default('estimated').describe('How values were obtained'),
        time_saved_minutes: z.number().min(0).describe('Minutes of human time saved'),
        risk_blocked_count: z.number().min(0).default(0).describe('Number of risks/violations blocked'),
        success: z.boolean().describe('Whether the workflow completed successfully'),
        task_complexity: z.enum(['low', 'medium', 'high']).default('medium').describe('Task complexity level'),
      },
      { title: 'Record Value Metric', readOnlyHint: false, idempotentHint: false, destructiveHint: false, openWorldHint: false },
      async (input) => {
        try {
          const entry: ValueMetricEntry = {
            workflowId: input.workflow_id,
            workflowType: input.workflow_type,
            agentId: input.agent_id,
            autonomyLevel: input.autonomy_level,
            measurementSource: input.measurement_source,
            timeSavedMinutes: input.time_saved_minutes,
            riskBlockedCount: input.risk_blocked_count,
            success: input.success,
            taskComplexity: input.task_complexity,
            timestamp: new Date().toISOString(),
          };
  
          metricsStore.push(entry);
  
          // Calculate running economic value
          const totalTimeSaved = metricsStore.reduce((sum, m) => sum + m.timeSavedMinutes, 0);
          const totalCostSaved = (totalTimeSaved / 60) * baselines.humanHourlyRate;
          const totalModelCost = metricsStore.length * baselines.modelCostPerRun;
  
          // Tool accountability tracking
          engine.telemetryService.emitToolCall('record_value_metric', `metric-${Date.now().toString(36)}`, 'ADVISORY', true);
  
          return { content: [{ type: 'text' as const, text: JSON.stringify({
            recorded: true,
            workflowId: input.workflow_id,
            metricIndex: metricsStore.length,
            runningTotals: {
              totalMetrics: metricsStore.length,
              totalTimeSavedMinutes: Math.round(totalTimeSaved),
              totalCostSavedUSD: Math.round((totalCostSaved - totalModelCost) * 100) / 100,
              totalRisksBlocked: metricsStore.reduce((sum, m) => sum + m.riskBlockedCount, 0),
              successRate: Math.round((metricsStore.filter(m => m.success).length / metricsStore.length) * 100),
            },
          }, null, 2) }] };
        } catch (error) {
          // Tool accountability tracking
          engine.telemetryService.emitToolCall('record_value_metric', `metric-${Date.now().toString(36)}`, 'ADVISORY', false);
          return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'RECORD_FAILED', message: String(error) }) }], isError: true };
        }
      }
    );
  }

• src/mcp/tools/value-metrics.ts:70-80 (schema)

  Zod schema for the 'record_value_metric' tool inputs: workflow_id (string max 100), workflow_type (string max 100), agent_id (string max 100), autonomy_level (enum: assist/delegate/automate), measurement_source (enum: measured/estimated/derived, default estimated), time_saved_minutes (number min 0), risk_blocked_count (number min 0, default 0), success (boolean), task_complexity (enum: low/medium/high, default medium).

  {
    workflow_id: z.string().max(100).describe('Unique workflow identifier'),
    workflow_type: z.string().max(100).describe('Type of workflow (e.g., claim-analysis, evidence-review, compliance-check)'),
    agent_id: z.string().max(100).describe('Agent that performed the workflow'),
    autonomy_level: z.enum(['assist', 'delegate', 'automate']).describe('Level of agent autonomy'),
    measurement_source: z.enum(['measured', 'estimated', 'derived']).default('estimated').describe('How values were obtained'),
    time_saved_minutes: z.number().min(0).describe('Minutes of human time saved'),
    risk_blocked_count: z.number().min(0).default(0).describe('Number of risks/violations blocked'),
    success: z.boolean().describe('Whether the workflow completed successfully'),
    task_complexity: z.enum(['low', 'medium', 'high']).default('medium').describe('Task complexity level'),
  },

• src/mcp/server.ts:105-105 (registration)

  Registration entry in the MCP server's tool table. The `registerValueMetricsTools` function (which includes `registerRecordValueMetricTool`) is listed with tier 'tenant' and description 'value_metrics (record_value_metric, record_governance_event, generate_impact_report)'.

  { tier: 'tenant', register: registerValueMetricsTools, description: 'value_metrics (record_value_metric, record_governance_event, generate_impact_report)' },

• src/mcp/server.ts:42-42 (registration)

  Import of `registerValueMetricsTools` from './tools/value-metrics.js' in the MCP server, which leads to the registration of the 'record_value_metric' tool.

  import { registerValueMetricsTools } from './tools/value-metrics.js';

• src/core/audit/telemetry.ts:188-189 (helper)

  Telemetry configuration entry for 'record_value_metric': toolClass 'write', riskTier 'low', maiDefault 'INFORMATIONAL', requiresHumanApproval false, category 'metrics'. This defines the tool's governance classification for audit purposes.

  { toolName: 'record_value_metric',    toolClass: 'write',    riskTier: 'low',      maiDefault: 'INFORMATIONAL',  requiresHumanApproval: false, category: 'metrics' },
  { toolName: 'record_governance_event', toolClass: 'write',   riskTier: 'low',      maiDefault: 'INFORMATIONAL',  requiresHumanApproval: false, category: 'metrics' },