@smartytalent/openai-tools

OpenAI function / tool calling definitions for the SmartyTalent recruitment API.

This package ships a pre-built tools.json generated from the SmartyTalent OpenAPI spec — one tool per API operation — ready to drop into the tools parameter of the OpenAI Chat Completions or Responses API.

Install

npm install @smartytalent/openai-tools

What's inside

An array of tool definitions in OpenAI's { type: "function", function: {...} } format:

interface OpenAITool {
  type: 'function'
  function: {
    name: string                                    // snake_case, e.g. "list_tenants"
    description: string                             // from OpenAPI summary/description
    parameters: Record<string, unknown>             // JSON Schema
  }
}

Quick start

import OpenAI from 'openai'
import { tools } from '@smartytalent/openai-tools'

const openai = new OpenAI()

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'List all active tenants' }],
  tools,
})

const toolCall = response.choices[0].message.tool_calls?.[0]
if (toolCall) {
  const args = JSON.parse(toolCall.function.arguments)
  const result = await executeSmartyTalentTool(toolCall.function.name, args)
  // feed result back into the conversation...
}

Executing tool calls

This package only defines the tool schemas — it doesn't ship an executor. Pair it with @smartytalent/api-client to dispatch tool calls against the live API:

import { Configuration, TenantsApi } from '@smartytalent/api-client'

const config = new Configuration({ basePath: '...', apiKey: `Bearer ${token}` })

async function executeSmartyTalentTool(name: string, args: Record<string, unknown>) {
  switch (name) {
    case 'list_tenants':
      return new TenantsApi(config).listTenants(args)
    // ... map other tool names to their API methods
  }
}

A generic dispatcher can be built by parsing the tool name back to an operationId and routing through the appropriate API class.

Filtering the tool catalog

The API exposes a lot of operations — feeding all of them to a model wastes context. Filter to the ones relevant for your use case:

import { tools } from '@smartytalent/openai-tools'

const candidateTools = tools.filter((t) =>
  t.function.name.includes('candidate') || t.function.name.includes('job'),
)

Raw JSON

import tools from '@smartytalent/openai-tools/dist/tools.json'

Versioning

Published in lockstep with @smartytalent/api-client. Pin both packages to the same version.

License

Licensed under the Apache License, Version 2.0.

Copyright © 2026 SmartyTalent (SmartyMeet sp. z o.o.)