mcpengine/servers/greenhouse/src/tools/scorecards.ts

import { z } from 'zod';
import { GreenhouseClient } from '../client/greenhouse-client.js';

const ListScorecardsInput = z.object({
  per_page: z.number().min(1).max(500).default(100).describe('Results per page'),
  page: z.number().min(1).default(1).describe('Page number for pagination'),
  created_after: z.string().optional().describe('Filter by creation date (ISO 8601)'),
  updated_after: z.string().optional().describe('Filter by update date (ISO 8601)'),
});

const GetScorecardInput = z.object({
  id: z.number().describe('Scorecard ID'),
});

const CreateScorecardInput = z.object({
  application_id: z.number().describe('Application ID this scorecard is for'),
  interviewed_at: z.string().optional().describe('Interview date/time (ISO 8601)'),
  submitted_by: z.number().optional().describe('User ID of submitter'),
  interview: z.number().optional().describe('Interview ID this scorecard is for'),
  overall_recommendation: z.enum(['definitely_not', 'no', 'yes', 'strong_yes', 'no_decision']).describe('Overall recommendation'),
  attributes: z.array(z.object({
    attribute_id: z.number(),
    rating: z.string().optional(),
    note: z.string().optional(),
  })).optional().describe('Array of attribute ratings and notes'),
  questions: z.array(z.object({
    question_id: z.number(),
    answer: z.string().optional(),
  })).optional().describe('Array of interview question responses'),
});

export default [
  {
    name: 'greenhouse_list_scorecards',
    description: 'Lists scorecards from Greenhouse with pagination support. Use when the user wants to browse interview feedback, review evaluation history, analyze interviewer assessments, or export scorecard data. Returns paginated list of scorecards with interviewer names, overall recommendations, ratings, interview questions/answers, and submission dates. Supports filtering by creation and update dates. Returns up to 500 scorecards per page.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        per_page: {
          type: 'number',
          description: 'Results per page (max 500)',
          default: 100,
        },
        page: {
          type: 'number',
          description: 'Page number for pagination',
          default: 1,
        },
        created_after: {
          type: 'string',
          description: 'Filter by creation date (ISO 8601)',
        },
        updated_after: {
          type: 'string',
          description: 'Filter by update date (ISO 8601)',
        },
      },
    },
    handler: async (input: unknown, client: GreenhouseClient) => {
      const validated = ListScorecardsInput.parse(input);
      const result = await client.get('/scorecards', validated);
      return {
        content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
      };
    },
  },
  {
    name: 'greenhouse_get_scorecard',
    description: 'Retrieves a single scorecard by ID from Greenhouse with complete interview feedback. Use when the user needs detailed information about a specific interview evaluation including all attribute ratings, interview question responses, overall recommendation, interviewer comments, and submission details. Returns full scorecard with all assessment data.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        id: {
          type: 'number',
          description: 'Scorecard ID',
        },
      },
      required: ['id'],
    },
    handler: async (input: unknown, client: GreenhouseClient) => {
      const validated = GetScorecardInput.parse(input);
      const result = await client.get(`/scorecards/${validated.id}`);
      return {
        content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
      };
    },
  },
  {
    name: 'greenhouse_create_scorecard',
    description: 'Creates a new scorecard (interview evaluation) in Greenhouse. Use when submitting interview feedback, recording candidate assessments, or programmatically creating evaluation records. Requires application ID and overall recommendation. Can include attribute ratings, interview question answers, and custom notes. Returns the newly created scorecard with assigned ID.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        application_id: {
          type: 'number',
          description: 'Application ID this scorecard is for',
        },
        interviewed_at: {
          type: 'string',
          description: 'Interview date/time (ISO 8601)',
        },
        submitted_by: {
          type: 'number',
          description: 'User ID of submitter',
        },
        interview: {
          type: 'number',
          description: 'Interview ID this scorecard is for',
        },
        overall_recommendation: {
          type: 'string',
          enum: ['definitely_not', 'no', 'yes', 'strong_yes', 'no_decision'],
          description: 'Overall recommendation',
        },
        attributes: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              attribute_id: { type: 'number' },
              rating: { type: 'string' },
              note: { type: 'string' },
            },
          },
          description: 'Array of attribute ratings and notes',
        },
        questions: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              question_id: { type: 'number' },
              answer: { type: 'string' },
            },
          },
          description: 'Array of interview question responses',
        },
      },
      required: ['application_id', 'overall_recommendation'],
    },
    handler: async (input: unknown, client: GreenhouseClient) => {
      const validated = CreateScorecardInput.parse(input);
      const result = await client.post('/scorecards', validated);
      return {
        content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
      };
    },
  },
];