Generate Tools from TypeScript Source Code

You have existing TypeScript functions and you want to turn them into agent capabilities without rewriting anything. Forge scans your source files, reads the exported function signatures and JSDoc comments, and generates tool specs and runnable capability code automatically. This walkthrough uses a billing module as the running example.

Prerequisites

TypeScript source files with exported functions
JSDoc comments on the functions you want to expose (recommended but not strictly required)
The Svantic CLI installed (npm install -g @svantic/cli)

Step 1: Write Your Functions

Forge works best with exported functions that have JSDoc annotations. Here is a typical billing module:

// src/billing.ts

/**
 * Charge a customer's payment method.
 * @param customer_id - The unique customer identifier.
 * @param amount_cents - Amount to charge in cents.
 * @param currency - ISO 4217 currency code (default: "usd").
 * @returns The charge object with id, status, and amount.
 */
export async function charge(
  customer_id: string,
  amount_cents: number,
  currency: string = 'usd',
): Promise<{ id: string; status: string; amount: number }> {
  // your implementation
}

/**
 * Refund a previous charge, fully or partially.
 * @param charge_id - The ID of the charge to refund.
 * @param amount_cents - Amount to refund in cents. Omit for a full refund.
 */
export async function refund(
  charge_id: string,
  amount_cents?: number,
): Promise<{ id: string; status: string }> {
  // your implementation
}

/**
 * List all charges for a customer within a date range.
 * @param customer_id - The customer to query.
 * @param from_date - Start of range (ISO 8601).
 * @param to_date - End of range (ISO 8601).
 */
export async function list_charges(
  customer_id: string,
  from_date: string,
  to_date: string,
): Promise<Array<{ id: string; amount: number; status: string; created_at: string }>> {
  // your implementation
}

// Not exported -- Forge ignores this
function validate_amount(cents: number): boolean {
  return cents > 0;
}

Step 2: Scan the File

svantic forge tool --scan src/billing.ts

Output:

Scanned src/billing.ts — found 3 exported functions:

  charge          (customer_id, amount_cents, currency?)
  refund          (charge_id, amount_cents?)
  list_charges    (customer_id, from_date, to_date)

Run with --pick to select specific functions, or omit to generate all.

Step 3: Generate Tools

Generate all functions:

svantic forge tool --scan src/billing.ts --out ./tools/

Or pick specific ones:

svantic forge tool --scan src/billing.ts --pick charge,refund --out ./tools/

This produces:

File	Contents
`billing.tool-spec.yaml`	The intermediate Tool Spec YAML
`billing.capabilities.ts`	Capability wrappers that call your original functions

Step 4: Review the Generated Code

The generated capabilities delegate to your original functions:

import { define_tool } from '@svantic/sdk/forge';
import { charge as charge_impl } from '../src/billing';

export const charge = define_tool({
  name: 'charge',
  description: 'Charge a customer\'s payment method.',
  parameters: {
    type: 'object',
    properties: {
      customer_id: { type: 'string', description: 'The unique customer identifier' },
      amount_cents: { type: 'number', description: 'Amount to charge in cents' },
      currency: { type: 'string', description: 'ISO 4217 currency code (default: "usd")' },
    },
    required: ['customer_id', 'amount_cents'],
  },
  execute: async (params) => {
    return await charge_impl(
      params.customer_id,
      params.amount_cents,
      params.currency,
    );
  },
});

How JSDoc Becomes LLM Descriptions

Forge maps your JSDoc annotations directly to tool and parameter descriptions:

JSDoc Element	Maps To
Function-level comment	`description` field on the tool
`@param name - text`	`description` on the matching parameter property
`@returns text`	Appended to the tool description as “Returns: …”
`@default value`	`default` field on the parameter
`@example`	Ignored (not included in tool spec)

If a function has no JSDoc, Forge generates a description from the function name (charge becomes "Invoke the charge function"). This works but produces weaker LLM tool selection — add real descriptions whenever possible.

Type Mapping

Forge infers JSON Schema types from your TypeScript signatures:

TypeScript Type	JSON Schema Type
`string`	`{ type: 'string' }`
`number`	`{ type: 'number' }`
`boolean`	`{ type: 'boolean' }`
`string[]`, `Array<string>`	`{ type: 'array', items: { type: 'string' } }`
`{ key: string }` (inline object)	`{ type: 'object', properties: { key: { type: 'string' } } }`
Named interface/type alias	Resolved and inlined as `{ type: 'object', properties: {...} }`
`T \| undefined`, `T?`	Property is omitted from `required`
Literal union `'a' \| 'b'`	`{ type: 'string', enum: ['a', 'b'] }`
`Record<string, T>`	`{ type: 'object', additionalProperties: { type: ... } }`
`unknown`, `any`	`{ type: 'string', description: 'JSON-encoded value' }`

Complex or deeply nested generics may not resolve cleanly. In those cases, Forge emits a warning and falls back to { type: 'string' }. Simplify the signature or add a @param override.

Programmatic Usage

import { scan_file, list_functions } from '@svantic/sdk/forge';

const functions = await list_functions('./src/billing.ts');
console.log(functions);
// [
//   { name: 'charge', params: ['customer_id', 'amount_cents', 'currency?'] },
//   { name: 'refund', params: ['charge_id', 'amount_cents?'] },
//   { name: 'list_charges', params: ['customer_id', 'from_date', 'to_date'] },
// ]

const result = await scan_file({
  file_path: './src/billing.ts',
  pick: ['charge', 'refund'],
  output_dir: './tools/',
});

console.log(result.tool_spec);    // Parsed YAML object
console.log(result.capabilities); // Array of generated tool definitions

Scanning Multiple Files

Pass multiple --scan flags or use a glob:

svantic forge tool --scan src/billing.ts --scan src/inventory.ts --out ./tools/

svantic forge tool --scan "src/**/*.ts" --out ./tools/

Each file produces its own .tool-spec.yaml and .capabilities.ts pair. Combine them later with svantic forge agent (see Composing Agents).

Handling Classes

Forge scans exported class methods as well as standalone functions. Each public method becomes a separate tool, prefixed with the class name:

export class Billing {
  /** Charge a customer. */
  async charge(customer_id: string, amount: number) { /* ... */ }

  /** Refund a charge. */
  async refund(charge_id: string) { /* ... */ }
}

Generated tool names: billing_charge, billing_refund. Private and protected methods are skipped. Static methods are included.

Updating After Code Changes

Re-run the scan command after modifying your source files. Forge regenerates the Tool Spec and capabilities, overwriting previous output. Any manual edits in *.custom.ts files in the output directory are preserved.

Get Started

Build Agents

Deep Dive

Knowledge & Self-Learning

Security

Policies & Guardrails

Notifications & Alerts

Deploying Your Agents

Forge

Plugins

From source code

Generate Tools from TypeScript Source Code

Prerequisites

Step 1: Write Your Functions

Step 2: Scan the File

Step 3: Generate Tools

Step 4: Review the Generated Code

How JSDoc Becomes LLM Descriptions

Type Mapping

Programmatic Usage

Scanning Multiple Files

Handling Classes

Updating After Code Changes

​Generate Tools from TypeScript Source Code

​Prerequisites

​Step 1: Write Your Functions

​Step 2: Scan the File

​Step 3: Generate Tools

​Step 4: Review the Generated Code

​How JSDoc Becomes LLM Descriptions

​Type Mapping

​Programmatic Usage

​Scanning Multiple Files

​Handling Classes

​Updating After Code Changes

Generate Tools from TypeScript Source Code

Prerequisites

Step 1: Write Your Functions

Step 2: Scan the File

Step 3: Generate Tools

Step 4: Review the Generated Code

How JSDoc Becomes LLM Descriptions

Type Mapping

Programmatic Usage

Scanning Multiple Files

Handling Classes

Updating After Code Changes