Skip to main content
Glama
mod-us

Modus MCP Server

Official
by mod-us
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Remote

modus_get_hiring_timeline

Retrieve planned hiring timeline with ramp details and quota assignments including time to hire, start/end dates, territory assignments, monthly ramp percentages, and quarterly quotas.

Instructions

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
yearNoYear to get hiring timeline for
scenarioIdNoOptional scenario ID to analyze

Implementation Reference

  • modus-mcp-server.js:245-262 (schema)
    Input schema definition for modus_get_hiring_timeline tool. Defines parameters: year (optional, defaults to 2025) and scenarioId (optional).
      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",
      },
    },
  },
},
  • modus-mcp-server.js:53-385 (registration)
    Tool registration in the TOOLS array. The tool named 'modus_get_hiring_timeline' is registered as part of the list of available tools for the MCP server.
    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",
        },
      },
    },
  },
];
  • modus-mcp-server.js:864-899 (handler)
    Handler implementation for modus_get_hiring_timeline. Calls the Modus API at /api/sales/hiring-timeline with year and optional scenarioId, processes the response to build a summary with hires by quarter, territory, total annual quota, average time to hire, and average ramp time.
    case "modus_get_hiring_timeline": {
  const { year = 2025, scenarioId } = args || {};
  const params = new URLSearchParams();

  params.append("year", year.toString());
  if (scenarioId) params.append("scenarioId", scenarioId.toString());

  response = await modusApi.get(`/api/sales/hiring-timeline?${params.toString()}`);
  const data = response.data || {};
  const timeline = data.hiringTimeline || [];

  // Add summary statistics
  const summary = {
    totalPlannedHires: timeline.length,
    hiresByQuarter: groupHiresByQuarter(timeline),
    hiresByTerritory: groupHiresByTerritory(timeline),
    totalAnnualQuota: timeline.reduce((sum, hire) => sum + (hire.quotaAnnual || 0), 0),
    averageTimeToHire: timeline.reduce((sum, hire) => sum + (hire.timeToHire || 0), 0) / timeline.length || 0,
    averageRampTime: calculateAverageRampTime(timeline),
  };

  return {
    content: [
      {
        type: "text",
        text: JSON.stringify({
          summary,
          timeline,
          year: data.year,
          totalPositions: data.totalPositions || 0,
          territoryIds: data.territoryIds || []
        }, null, 2),
      },
    ],
  };
}
  • modus-mcp-server.js:1222-1234 (helper)
    Helper function groupHiresByQuarter - groups hires from the timeline into Q1-Q4 buckets based on startDate.
    function groupHiresByQuarter(timeline) {
  const groups = { Q1: 0, Q2: 0, Q3: 0, Q4: 0 };
  if (!timeline || !Array.isArray(timeline)) return groups;
  timeline.forEach((hire) => {
    if (hire.startDate) {
      const date = new Date(hire.startDate);
      const month = date.getMonth() + 1;
      const quarter = Math.ceil(month / 3);
      groups[`Q${quarter}`]++;
    }
  });
  return groups;
}
  • modus-mcp-server.js:1236-1246 (helper)
    Helper function groupHiresByTerritory - groups hires from the timeline by territory name.
    function groupHiresByTerritory(timeline) {
  const groups = {};
  if (!timeline || !Array.isArray(timeline)) return groups;
  timeline.forEach((hire) => {
    if (hire.territory) {
      const territoryName = hire.territory.name || "Unknown";
      groups[territoryName] = (groups[territoryName] || 0) + 1;
    }
  });
  return groups;
}

Tool Definition Quality

B3.3/5.0
Behavior2/5

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

No annotations provided, so the description carries full burden for behavioral traits. It only states what the tool returns, omitting any side effects, permissions, rate limits, or data freshness considerations. For a 'get' tool, minimal transparency.

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 concise sentences front-loaded with purpose and output details. No wasted words, efficient structure.

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

Completeness3/5

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

No output schema, so description must describe return structure. It lists key fields (dates, territory, ramp, quotas) but lacks structure details (e.g., per position vs aggregated). Adequate but not fully complete.

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

Parameters3/5

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

Schema coverage is 100% (both params have descriptions). The description does not add significant meaning beyond 'year' and 'scenarioId'—it mentions returns but not how to use parameters. Baseline 3 is appropriate.

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

Purpose4/5

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

The description clearly states the tool gets a 'planned hiring timeline' and lists specific details included (ramp, quota, dates, territories). It distinguishes from siblings like modus_get_quota_assignments by combining elements, but does not explicitly differentiate.

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

Usage Guidelines3/5

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

No explicit guidance on when to use this tool vs alternatives like modus_get_ramp_profiles or modus_get_quota_assignments. The context implies it is for a holistic hiring timeline, but no when-not-to or prerequisite info.

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