Skip to main content
Glama
mod-us

Modus MCP Server

Official
by mod-us
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Remote

modus_get_attrition_risks

Predict employee attrition risk with machine learning. Returns confidence scores and risk factors, using cached data for speed or real-time analysis on demand.

Instructions

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
thresholdNoMinimum risk threshold (0-1). Default: 0.7 (70% risk)
departmentNoFilter by role/department name (e.g., 'Account Executive', 'SDR')
freshNoGenerate fresh insights (slower but current). Default: false (uses cached data for speed)

Implementation Reference

  • modus-mcp-server.js:79-103 (schema)
    Tool registration and input schema definition for 'modus_get_attrition_risks'. Defines the tool name, description, and input schema with parameters: threshold (0-1, default 0.7), department (string filter), and fresh (boolean, default false).
      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)",
      },
    },
  },
},
  • modus-mcp-server.js:462-561 (handler)
    Handler implementation for 'modus_get_attrition_risks'. Makes API call to /api/sales-insights with ATTRITION_RISK category, extracts at-risk employees from insights, applies threshold and department filtering, converts risk levels to confidence scores (HIGH=0.85, MEDIUM=0.7, LOW=0.5), builds summary statistics (totalAtRisk, averageConfidence, effectiveFTEAtRisk, byDepartment, byRiskLevel, topRiskFactors), and returns structured response.
    case "modus_get_attrition_risks": {
  const { threshold = 0.7, department, fresh = false } = args || {};

  // Generate fresh attrition insights using the full detection flow
  // This calls: generateSalesInsights → generateInsightByCategory → getCategoryData →
  // getAttritionRiskData → generateAttritionInsights → detectAttritionRisk
  response = await modusApi.get(`/api/sales-insights`, {
    params: {
      categories: 'ATTRITION_RISK',
      skipCache: fresh ? 'true' : 'false',  // Fresh generation or use cache
      includeRecommendations: 'true'
    }
  });

  // Extract insights from response
  const insights = response.data?.insights || [];

  // Extract at-risk employees from insights
  const allAtRiskEmployees = [];
  insights.forEach((insight) => {
    if (insight.recommendations && insight.recommendations.length > 0) {
      const rec = insight.recommendations[0];
      if (rec.affectedEmployees) {
        rec.affectedEmployees.forEach((emp) => {
          // Convert risk level to confidence score
          const confidence = emp.riskLevel === "HIGH" ? 0.85 : emp.riskLevel === "MEDIUM" ? 0.7 : 0.5;

          // Filter by department if specified
          if (!department || emp.department === department) {
            // Only include if meets threshold
            if (confidence >= threshold) {
              allAtRiskEmployees.push({
                employee_id: emp.employee_id,
                name: emp.name,
                riskLevel: emp.riskLevel,
                confidence,
                riskFactors: emp.riskFactors || [],
                department: insight.data?.roleInfo?.jobRoleName || "Unknown",
                predictedTerminationDate: emp.predictedTerminationDate,
                performance: emp.performance,
                riskAnalysis: emp.riskAnalysis,
                gongActivitySignals: emp.gongActivitySignals,
              });
            }
          }
        });
      }
    }
  });

  // Build summary
  const summary = {
    totalAtRisk: allAtRiskEmployees.length,
    averageConfidence: allAtRiskEmployees.reduce((sum, r) => sum + r.confidence, 0) / allAtRiskEmployees.length || 0,
    effectiveFTEAtRisk: allAtRiskEmployees.reduce((sum, r) => sum + r.confidence, 0),
    byDepartment: {},
    byRiskLevel: {},
    topRiskFactors: {},
  };

  allAtRiskEmployees.forEach((emp) => {
    // By department
    if (emp.department) {
      summary.byDepartment[emp.department] = (summary.byDepartment[emp.department] || 0) + 1;
    }
    // By risk level
    if (emp.riskLevel) {
      summary.byRiskLevel[emp.riskLevel] = (summary.byRiskLevel[emp.riskLevel] || 0) + 1;
    }
    // Top risk factors
    if (emp.riskFactors) {
      emp.riskFactors.forEach((factor) => {
        summary.topRiskFactors[factor] = (summary.topRiskFactors[factor] || 0) + 1;
      });
    }
  });

  return {
    content: [
      {
        type: "text",
        text: JSON.stringify(
          {
            summary,
            atRiskEmployees: allAtRiskEmployees,
            threshold,
            rawInsights: insights.map((i) => ({
              id: i.id,
              title: i.title,
              severity: i.severity,
              atRiskCount: i.data?.atRiskCount || 0,
            })),
          },
          null,
          2
        ),
      },
    ],
  };
}
  • modus-mcp-server.js:53-385 (registration)
    Tool registration in the TOOLS array at lines 53-385. Line 79 specifically defines the modus_get_attrition_risks entry in the register of all available tools.
    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",
        },
      },
    },
  },
];

Tool Definition Quality

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the description discloses key behavioral traits: uses cached insights by default, fresh=true for real-time analysis, and returns risk factors with confidence. No mention of rate limits or auth, but adequate for a read-only tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose, no redundant information. Every part earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter tool with no output schema, the description completely covers what to expect (employees at risk, risk factors, confidence levels) and the key behavioral nuance (caching). No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers all three parameters with descriptions, and the description adds value by explaining the default caching behavior and the effect of the fresh parameter, which the schema only partially conveys.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves ML-powered attrition risk predictions with confidence scores. It specifies the resource (attrition risks) and distinguishes from sibling tools focused on historical data or team performance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use cached vs fresh data, but lacks explicit guidance on when to prefer this tool over alternatives like modus_get_historical_attrition or modus_get_employee_insights.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mod-us/modus-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server