modus_get_employee_insights

Instructions

Implementation Reference

• modus-mcp-server.js:330-344 (schema)

  Schema definition for modus_get_employee_insights tool. Requires an employeeId parameter (number).

  {
    name: "modus_get_employee_insights",
    description:
      "Get individual employee performance insights with AI analysis. Returns detailed performance summary including ramp progress, quota attainment, revenue, pipeline coverage, and AI-generated insights about performance trends and concerns.",
    inputSchema: {
      type: "object",
      properties: {
        employeeId: {
          type: "number",
          description: "Employee ID to analyze",
        },
      },
      required: ["employeeId"],
    },
  },

• modus-mcp-server.js:973-1000 (handler)

  Handler for modus_get_employee_insights. Calls /api/sales-insights/employee/{employeeId} and returns performance summary with AI analysis.

  case "modus_get_employee_insights": {
    const { employeeId } = args || {};
  
    if (!employeeId) {
      throw new Error("employeeId is required");
    }
  
    response = await modusApi.get(`/api/sales-insights/employee/${employeeId}`);
    const data = response.data;
  
    // Add summary statistics
    const performanceSummary = data.performanceSummary || {};
    const summary = {
      overallPerformanceScore: calculatePerformanceScore(performanceSummary),
      keyStrengths: identifyStrengths(performanceSummary),
      keyConcerns: identifyConcerns(performanceSummary, data.insights),
      recommendationPriority: determineRecommendationPriority(performanceSummary, data.insights),
    };
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({ summary, data }, null, 2),
        },
      ],
    };
  }

• modus-mcp-server.js:53-392 (registration)

  Tool registration via the TOOLS array served by ListToolsRequestSchema handler.

  const TOOLS = [
  {
    name: "modus_get_current_headcount",
    description:
      "Get current headcount by team, role, or department with filtering. Returns employee data including roles, departments, and employment status.",
    inputSchema: {
      type: "object",
      properties: {
        department: {
          type: "string",
          description: "Filter by department name (e.g., 'Sales', 'Engineering')",
        },
        role: {
          type: "string",
          description: "Filter by job role (e.g., 'Account Executive', 'SDR')",
        },
        status: {
          type: "string",
          enum: ["ACTIVE", "INACTIVE"],
          default: "ACTIVE",
          description: "Filter by employment status",
        },
      },
    },
  },
  {
    name: "modus_get_attrition_risks",
    description:
      "Get ML-powered attrition risk predictions with confidence scores (0-1). Returns employees at risk of leaving with risk factors and confidence levels. Uses cached insights by default for speed, set fresh=true for real-time analysis.",
    inputSchema: {
      type: "object",
      properties: {
        threshold: {
          type: "number",
          description: "Minimum risk threshold (0-1). Default: 0.7 (70% risk)",
          default: 0.7,
          minimum: 0,
          maximum: 1,
        },
        department: {
          type: "string",
          description: "Filter by role/department name (e.g., 'Account Executive', 'SDR')",
        },
        fresh: {
          type: "boolean",
          default: false,
          description: "Generate fresh insights (slower but current). Default: false (uses cached data for speed)",
        },
      },
    },
  },
  {
    name: "modus_get_open_positions",
    description:
      "Get open job requisitions and hiring forecast by quarter. Returns open positions with status, department, and planned start dates.",
    inputSchema: {
      type: "object",
      properties: {
        status: {
          type: "string",
          enum: ["OPEN", "DRAFT", "CLOSED", "ALL"],
          description: "Filter by requisition status. Default: OPEN",
        },
        department: {
          type: "string",
          description: "Filter by department name",
        },
      },
    },
  },
  {
    name: "modus_get_ramp_profiles",
    description:
      "Get ramp time profiles showing how long new hires take to reach full productivity. Returns month-by-month productivity percentages by role.",
    inputSchema: {
      type: "object",
      properties: {
        role: {
          type: "string",
          description: "Job role to get ramp data for (e.g., 'Account Executive')",
        },
      },
    },
  },
  {
    name: "modus_get_historical_attrition",
    description:
      "Get historical attrition metrics for trend analysis. Returns attrition rates and counts over specified time periods.",
    inputSchema: {
      type: "object",
      properties: {
        days: {
          type: "number",
          enum: [90, 180, 365],
          default: 180,
          description: "Time period for historical data (90, 180, or 365 days)",
        },
        department: {
          type: "string",
          description: "Filter by department name",
        },
      },
    },
  },
  {
    name: "modus_get_sales_breakdown",
    description:
      "Get comprehensive sales breakdown with hiring/capacity analysis including targets, capacity, attrition impact, and quarterly waterfall metrics. Returns month-by-month capacity projections with revenue gaps and hiring needs. The period type is auto-detected: use quarter for quarterly analysis, year for annual, or startDate/endDate for custom ranges.",
    inputSchema: {
      type: "object",
      properties: {
        period: {
          type: "string",
          description: "Period type (optional - auto-detected): YTD, QUARTER, YEAR, CUSTOM_RANGE, LAST_12_MONTHS, NEXT_12_MONTHS",
          enum: ["YTD", "QUARTER", "YEAR", "CUSTOM_RANGE", "LAST_12_MONTHS", "NEXT_12_MONTHS"],
        },
        year: {
          type: "number",
          description: "Year to analyze (e.g., 2025). Required for QUARTER, YEAR, or YTD periods.",
        },
        quarter: {
          type: "number",
          description: "Quarter number (1-4). When specified, automatically uses QUARTER period.",
        },
        startDate: {
          type: "string",
          description: "Start date (YYYY-MM-DD). When specified with endDate, automatically uses CUSTOM_RANGE period.",
        },
        endDate: {
          type: "string",
          description: "End date (YYYY-MM-DD). When specified with startDate, automatically uses CUSTOM_RANGE period.",
        },
        scenarioId: {
          type: "number",
          description: "Optional scenario ID to analyze",
        },
      },
    },
  },
  {
    name: "modus_get_sales_insights",
    description:
      "Get AI-powered sales insights across 30+ categories including revenue gaps, attrition risk, territory performance, pipeline coverage, and competitive analysis. Returns detailed insights with recommendations and confidence scores.",
    inputSchema: {
      type: "object",
      properties: {
        categories: {
          type: "string",
          description: "Comma-separated list of categories (e.g., 'REVENUE_GAP,ATTRITION_RISK,TERRITORY_PERFORMANCE'). Available: REVENUE_GAP, HEADCOUNT_PLANNING, CAPACITY_UTILIZATION, ATTRITION_RISK, ATTRITION_BACKFILLS, PIPELINE_COVERAGE, WIN_RATE_SHIFTS, SALES_CYCLE_BOTTLENECK, TERRITORY_PERFORMANCE, TERRITORY_DESIGN, TERRITORY_LOAD_MGMT, MARKET_EXPANSION, COMPETITIVE_ANALYSIS, SKILLS_GAP, and 20+ more.",
        },
        timeframe: {
          type: "string",
          description: "JSON timeframe (e.g., '{\"months\": 12}')",
        },
        includeRecommendations: {
          type: "boolean",
          default: true,
          description: "Include AI recommendations in results",
        },
        limit: {
          type: "number",
          default: 50,
          description: "Maximum number of insights to return (max: 100)",
        },
        skipCache: {
          type: "boolean",
          default: false,
          description: "Force fresh generation (slower but current). Default: false (uses cached data)",
        },
      },
    },
  },
  {
    name: "modus_get_benchmark_insights",
    description:
      "Get benchmark-driven sales insights with company data and industry comparisons. Optimized for fast retrieval (< 500ms) with multi-layer caching. Returns insights with company metrics (OTE, quotas, attrition rates), industry benchmarks with sources, variance analysis, and actionable recommendations. Use this for comparing your company's metrics to industry standards.",
    inputSchema: {
      type: "object",
      properties: {
        category: {
          type: "string",
          description: "Filter by insight category: 'territory', 'performance', or 'recommendations'. Omit for all categories.",
        },
        force: {
          type: "boolean",
          default: false,
          description: "Force fresh generation bypassing cache (slower). Default: false (uses cached data for speed).",
        },
      },
    },
  },
  {
    name: "modus_get_hiring_timeline",
    description:
      "Get planned hiring timeline with ramp details and quota assignments. Returns hiring schedule with time to hire, start/end dates, territory assignments, monthly ramp percentages, and quarterly quotas.",
    inputSchema: {
      type: "object",
      properties: {
        year: {
          type: "number",
          default: 2025,
          description: "Year to get hiring timeline for",
        },
        scenarioId: {
          type: "number",
          description: "Optional scenario ID to analyze",
        },
      },
    },
  },
  {
    name: "modus_get_performance_leaderboard",
    description:
      "Get top sales performers across key metrics including opportunities created/won, pipeline created, bookings, ASP, and close rate. Returns ranked list of top performers for each metric.",
    inputSchema: {
      type: "object",
      properties: {
        year: {
          type: "number",
          description: "Year for performance data",
        },
        quarter: {
          type: "number",
          description: "Quarter number (1-4)",
        },
        month: {
          type: "number",
          description: "Month number (1-12)",
        },
        limit: {
          type: "number",
          default: 6,
          description: "Number of top performers to show per metric",
        },
      },
    },
  },
  {
    name: "modus_get_team_performance",
    description:
      "Get team performance overview with performance labels (Top performer, High potential, At risk, etc.). Returns employee performance metrics including revenue, bookings, opportunities, pipeline, ASP, and close rate.",
    inputSchema: {
      type: "object",
      properties: {
        year: {
          type: "number",
          description: "Year for performance data",
        },
        quarter: {
          type: "number",
          description: "Quarter number (1-4)",
        },
        month: {
          type: "number",
          description: "Month number (1-12)",
        },
        limit: {
          type: "number",
          default: 50,
          description: "Maximum number of employees to return",
        },
        offset: {
          type: "number",
          description: "Pagination offset",
        },
        sortBy: {
          type: "string",
          description: "Sort by: revenue, bookings, opportunities, pipeline, ASP, closeRate",
        },
        sortOrder: {
          type: "string",
          enum: ["asc", "desc"],
          description: "Sort order: asc or desc",
        },
      },
    },
  },
  {
    name: "modus_get_employee_insights",
    description:
      "Get individual employee performance insights with AI analysis. Returns detailed performance summary including ramp progress, quota attainment, revenue, pipeline coverage, and AI-generated insights about performance trends and concerns.",
    inputSchema: {
      type: "object",
      properties: {
        employeeId: {
          type: "number",
          description: "Employee ID to analyze",
        },
      },
      required: ["employeeId"],
    },
  },
  {
    name: "modus_get_quota_assignments",
    description:
      "Get quota assignments by employee and territory. Returns employee quota assignments with quarterly and annual quotas, territory details, and regional breakdowns.",
    inputSchema: {
      type: "object",
      properties: {
        year: {
          type: "number",
          description: "Year for quota assignments",
        },
        search: {
          type: "string",
          description: "Search employee names",
        },
        region: {
          type: "string",
          description: "Filter by region",
        },
        role: {
          type: "string",
          description: "Filter by job role",
        },
      },
    },
  },
    {
      name: "modus_get_quarterly_capacity",
      description:
        "Get quarterly capacity breakdown showing beginning/end capacity, revenue targets, gaps, attrition impact, backfills, and capacity at risk. Returns 5 quarters (3 previous + current + 1 future) with detailed waterfall metrics. This is the PREFERRED tool for revenue gap analysis.",
      inputSchema: {
        type: "object",
        properties: {
          scenarioId: {
            type: "number",
            description: "Optional scenario ID to analyze",
          },
        },
      },
    },
  ];
  
  // List tools handler
  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: TOOLS,
    };
  });

• modus-mcp-server.js:1313-1321 (helper)

  Helper function to calculate an overall performance score from the performance summary.

  function calculatePerformanceScore(performanceSummary) {
    if (!performanceSummary) return 0;
    const quotaAttainment = performanceSummary.quotaAttainmentPercentage || 0;
    const pipelineCoverage = performanceSummary.pipelineCoverageRatio || 0;
  
    // Weighted score: 70% quota attainment, 30% pipeline coverage (normalized to 0-100)
    const score = quotaAttainment * 0.7 + Math.min(pipelineCoverage * 20, 100) * 0.3;
    return Math.round(score);
  }

• modus-mcp-server.js:1338-1356 (helper)

  Helper function to identify key concerns from performance data and insights.

  function identifyConcerns(performanceSummary, insights) {
    const concerns = [];
    if (!performanceSummary) return concerns;
  
    if (performanceSummary.quotaAttainmentPercentage < 70) {
      concerns.push("Low quota attainment");
    }
    if (performanceSummary.pipelineCoverageRatio < 2) {
      concerns.push("Insufficient pipeline coverage");
    }
    if (insights && Array.isArray(insights)) {
      const hasRiskInsight = insights.some((i) => i.type === "PIPELINE_RISK" || i.severity === "HIGH");
      if (hasRiskInsight) {
        concerns.push("Pipeline risk identified");
      }
    }
  
    return concerns.slice(0, 2);
  }