Class: FluentToolBuilder<TContext, TInput, TCtx>

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:77

Fluent builder that accumulates types at each step.

Type Parameters

Type Parameter	Default type	Description
`TContext`	-	Base application context (from `initVurb<TContext>()`)
`TInput`	`Record`<`string`, `never`>	Accumulated input type (built by `with*()` methods)
`TCtx`	`TContext`	Accumulated context type (enriched by `.use()`)

Constructors

Constructor

new FluentToolBuilder<TContext, TInput, TCtx>(name, defaults?): FluentToolBuilder<TContext, TInput, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:132

Parameters

Parameter	Type	Description
`name`	`string`	Tool name in `domain.action` format (e.g. `'users.list'`)
`defaults`	`SemanticDefaults`	Semantic defaults from the verb (`query`, `mutation`, `action`)

Returns

FluentToolBuilder<TContext, TInput, TCtx>

Methods

annotations()

annotations(a): FluentToolBuilder<TContext, TInput, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:870

Set MCP tool annotations.

Parameters

Parameter	Type	Description
`a`	`Record`<`string`, `unknown`>	Annotation key-value pairs

Returns

FluentToolBuilder<TContext, TInput, TCtx>

this for chaining

bindState()

bindState(states, transition?): FluentToolBuilder<TContext, TInput, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:1028

Bind this tool to specific FSM states.

When a StateMachineGate is configured on the server, this tool will only appear in tools/list when the FSM is in one of the specified states. The LLM physically cannot call tools that don't exist in its reality.

Parameters

Parameter	Type	Description
`states`	`string` \| `string`[]	FSM state(s) where this tool is visible
`transition?`	`string`	Event to send to the FSM on successful execution

Returns

FluentToolBuilder<TContext, TInput, TCtx>

this for chaining

Example

typescript

// Visible only in 'has_items' state, sends CHECKOUT on success
const checkout = f.mutation('cart.checkout')
    .bindState('has_items', 'CHECKOUT')
    .handle(async (input, ctx) => { ... });

// Visible in multiple states
const addItem = f.mutation('cart.add_item')
    .bindState(['empty', 'has_items'], 'ADD_ITEM')
    .handle(async (input, ctx) => { ... });

cached()

cached(): FluentToolBuilder<TContext, TInput, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:893

Mark this tool's data as immutable (safe to cache forever).

Returns

FluentToolBuilder<TContext, TInput, TCtx>

this for chaining

concurrency()

concurrency(config): FluentToolBuilder<TContext, TInput, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:916

Set concurrency limits for this tool (Semaphore + Queue pattern).

Parameters

Parameter	Type	Description
`config`	`ConcurrencyConfig`	Concurrency configuration

Returns

FluentToolBuilder<TContext, TInput, TCtx>

this for chaining

describe()

describe(text): FluentToolBuilder<TContext, TInput, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:151

Set the tool description shown to the LLM.

Parameters

Parameter	Type	Description
`text`	`string`	Human-readable description

Returns

FluentToolBuilder<TContext, TInput, TCtx>

this for chaining

destructive()

destructive(): FluentToolBuilder<TContext, TInput, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:843

Override: mark this tool as destructive (irreversible)

Returns

FluentToolBuilder<TContext, TInput, TCtx>

egress()

egress(bytes): FluentToolBuilder<TContext, TInput, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:927

Set maximum payload size for tool responses (Egress Guard).

Parameters

Parameter	Type	Description
`bytes`	`number`	Maximum payload size in bytes

Returns

FluentToolBuilder<TContext, TInput, TCtx>

this for chaining

fromModel()

fromModel<M>(model, operation): FluentToolBuilder<TContext, TInput & Record<string, any>, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:696

Derive tool input parameters from a Model's fillable profile.

Reads the specified operation from model.input (fillable profiles), then adds each field as a parameter using the type and description from the Model's casts. For create, fields respect their schema optionality. For update and filter, all fields become optional.

Type Parameters

Type Parameter
`M` extends `Model`

Parameters

Parameter	Type	Description
`model`	`M`	A `Model` from `defineModel()`
`operation`	`string`	The fillable profile name (e.g. `'create'`, `'update'`, `'filter'`)

Returns

FluentToolBuilder<TContext, TInput & Record<string, any>, TCtx>

Builder with additional parameters from the Model

Example

typescript

f.mutation('task.create')
  .fromModel(TaskModel, 'create')
  .withStrings({ company_slug: '...', project_slug: '...' })
  .handle(async (input, ctx) => { ... });

handle()

handle(handler): GroupedToolBuilder<TContext>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:1059

Set the handler and build the tool — the terminal step.

The handler receives (input, ctx) with fully typed TInput and TCtx. Implicit success() wrapping: if the handler returns raw data (not a ToolResponse), the framework wraps it with success().

Parameters

Parameter	Type	Description
`handler`	(`input`, `ctx`) => `Promise`<`unknown`>	Async function receiving typed `(input, ctx)`

Returns

GroupedToolBuilder<TContext>

A GroupedToolBuilder ready for registration

Example

typescript

const getProject = f.query('projects.get')
    .describe('Get a project by ID')
    .withString('project_id', 'The exact project ID')
    .handle(async (input, ctx) => {
        return await ctx.db.projects.findUnique({ where: { id: input.project_id } });
    });

idempotent()

idempotent(): FluentToolBuilder<TContext, TInput, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:849

Override: mark this tool as idempotent (safe to retry)

Returns

FluentToolBuilder<TContext, TInput, TCtx>

instructions()

instructions(text): FluentToolBuilder<TContext, TInput, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:174

Set AI-First instructions — injected as system-level guidance in the tool description.

This is Prompt Engineering embedded in the framework. The instructions tell the LLM WHEN and HOW to use this tool, reducing hallucination.

Parameters

Parameter	Type	Description
`text`	`string`	System prompt for the tool

Returns

FluentToolBuilder<TContext, TInput, TCtx>

this for chaining

Example

typescript

f.query('docs.search')
    .describe('Search internal documentation')
    .instructions('Use ONLY when the user asks about internal policies.')
    .withString('query', 'Search term')
    .handle(async (input) => { ... });

interactive()

interactive(): FluentToolBuilder<TContext, TInput, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:996

Enable human-in-the-loop interaction for this tool.

When enabled, the handler can use the standalone ask() function to pause execution and request user input via a client-rendered form, or ask.redirect() to send the user to an external URL.

The transport context is bound via AsyncLocalStorage — the developer never needs to pass or receive any transport objects.

Returns

FluentToolBuilder<TContext, TInput, TCtx>

this for chaining (no type augmentation needed — ask() is standalone)

Example

typescript

import { ask } from '@vurb/core';

const deploy = f.mutation('infra.deploy')
    .withString('app_id', 'Application ID')
    .interactive()
    .handle(async (input) => {
        const prefs = await ask('Confirm deployment:', {
            region: ask.enum(['us-east-1', 'eu-west-1'] as const, 'Region'),
        });
        if (prefs.declined) return f.error('CANCELLED', 'Aborted');
        return { region: prefs.data.region };
    });

invalidates()

invalidates(...patterns): FluentToolBuilder<TContext, TInput, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:883

Declare glob patterns invalidated when this tool succeeds.

Parameters

Parameter	Type	Description
...`patterns`	`string`[]	Glob patterns (e.g. `'sprints.'`, `'tasks.'`)

Returns

FluentToolBuilder<TContext, TInput, TCtx>

this for chaining

proxy()

proxy(endpoint, options?): GroupedToolBuilder<TContext>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:1102

Auto-generate a handler that proxies to ctx.client HTTP methods.

Eliminates boilerplate by deriving the HTTP method from the semantic verb (query → GET, mutation → POST) and passing model input directly as query params or request body.

For tools with non-trivial logic (data transformation, multi-step calls, conditional behavior), use .handle() instead.

Parameters

Parameter	Type	Description
`endpoint`	`string`	API path (e.g. `'companies/standup/summary'`)
`options?`	{ `method?`: `"GET"` \| `"POST"` \| `"PUT"` \| `"DELETE"`; `unwrap?`: `boolean`; }	Optional overrides
`options.method?`	`"GET"` \| `"POST"` \| `"PUT"` \| `"DELETE"`	Force HTTP method (`'GET'`, `'POST'`, `'PUT'`, `'DELETE'`)
`options.unwrap?`	`boolean`	Auto-unwrap `response.data` (default: `true`)

Returns

GroupedToolBuilder<TContext>

A GroupedToolBuilder ready for registration

Example

typescript

const pulse = analytics.query('pulse')
    .fromModel(AnalyticsModel, 'query')
    .proxy('companies/manager-dashboard/pulse');

const create = note.mutation('create')
    .fromModel(NoteModel, 'create')
    .proxy('notes');

const update = note.mutation('update')
    .fromModel(NoteModel, 'update')
    .proxy('notes/:uuid', { method: 'PUT' });

readOnly()

readOnly(): FluentToolBuilder<TContext, TInput, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:837

Override: mark this tool as read-only (no side effects)

Returns

FluentToolBuilder<TContext, TInput, TCtx>

returns()

returns(presenter): FluentToolBuilder<TContext, TInput, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:815

Set the MVA Presenter for automatic response formatting.

When a Presenter is attached, the handler can return raw data and the framework pipes it through schema validation, system rules, and UI block generation.

Parameters

Parameter	Type	Description
`presenter`	`Presenter`<`any`>	A Presenter instance

Returns

FluentToolBuilder<TContext, TInput, TCtx>

this for chaining

sandboxed()

sandboxed(config?): FluentToolBuilder<TContext, TInput, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:961

Enable zero-trust sandboxed execution for this tool.

When enabled:

A SandboxEngine is lazily created on the GroupedToolBuilder
A system instruction is auto-injected into the tool description (HATEOAS auto-prompting) so the LLM knows to send JS functions
The handler can use SandboxEngine.execute() to run LLM code in a sealed V8 isolate (no process, require, fs, network)

Parameters

Parameter	Type	Description
`config?`	`SandboxConfig`	Optional sandbox configuration (timeout, memory, output size)

Returns

FluentToolBuilder<TContext, TInput, TCtx>

this for chaining

Example

typescript

f.query('data.compute')
    .describe('Run safe computation on server data')
    .sandboxed({ timeout: 3000, memoryLimit: 64 })
    .withString('expression', 'JS arrow function: (data) => result')
    .handle(async (input, ctx) => {
        const data = await ctx.db.records.findMany();
        const engine = new SandboxEngine({ timeout: 3000 });
        const result = await engine.execute(input.expression, data);
        return result.ok ? result.value : { error: result.error };
    });

stale()

stale(): FluentToolBuilder<TContext, TInput, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:903

Mark this tool's data as volatile (never cache).

Returns

FluentToolBuilder<TContext, TInput, TCtx>

this for chaining

tags()

tags(...tags): FluentToolBuilder<TContext, TInput, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:829

Add capability tags for selective tool exposure.

Tags are accumulated — calling .tags() multiple times (or inheriting from a router) appends rather than replaces.

Parameters

Parameter	Type	Description
...`tags`	`string`[]	Tag strings for filtering

Returns

FluentToolBuilder<TContext, TInput, TCtx>

this for chaining

toonDescription()

toonDescription(): FluentToolBuilder<TContext, TInput, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:859

Enable TOON-formatted descriptions for token optimization.

Returns

FluentToolBuilder<TContext, TInput, TCtx>

this for chaining

use()

Call Signature

use<TDerived>(mw): FluentToolBuilder<TContext, TInput, TCtx & TDerived>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:765

Add context-derivation middleware (tRPC-style).

Accepts either:

A MiddlewareDefinition from f.middleware() (recommended)
An inline function ({ ctx, next }) => Promise<ToolResponse>

Type Parameters

Type Parameter
`TDerived` extends `Record`<`string`, `unknown`>

Parameters

Parameter	Type	Description
`mw`	`MiddlewareDefinition`<`TCtx`, `TDerived`>	Middleware definition or inline function

Returns

FluentToolBuilder<TContext, TInput, TCtx & TDerived>

A new type of FluentToolBuilder with TCtx enriched

Example

typescript

// Option 1: f.middleware() (recommended)
const withAuth = f.middleware(async (ctx) => {
    if (ctx.role === 'GUEST') throw error('Unauthorized');
    return { verified: true };
});
f.mutation('users.delete')
    .use(withAuth)
    .handle(async (input, ctx) => { ... });

// Option 2: inline
f.mutation('users.delete')
    .use(async ({ ctx, next }) => {
        const admin = await requireAdmin(ctx.headers);
        return next({ ...ctx, adminUser: admin });
    })
    .handle(async (input, ctx) => { ... });

Call Signature

use<TDerived>(mw): FluentToolBuilder<TContext, TInput, TCtx & TDerived>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:768

Add context-derivation middleware (tRPC-style).

Accepts either:

A MiddlewareDefinition from f.middleware() (recommended)
An inline function ({ ctx, next }) => Promise<ToolResponse>

Type Parameters

Type Parameter
`TDerived` extends `Record`<`string`, `unknown`>

Parameters

Parameter	Type	Description
`mw`	(`args`) => `Promise`<`ToolResponse`>	Middleware definition or inline function

Returns

FluentToolBuilder<TContext, TInput, TCtx & TDerived>

A new type of FluentToolBuilder with TCtx enriched

Example

typescript

// Option 1: f.middleware() (recommended)
const withAuth = f.middleware(async (ctx) => {
    if (ctx.role === 'GUEST') throw error('Unauthorized');
    return { verified: true };
});
f.mutation('users.delete')
    .use(withAuth)
    .handle(async (input, ctx) => { ... });

// Option 2: inline
f.mutation('users.delete')
    .use(async ({ ctx, next }) => {
        const admin = await requireAdmin(ctx.headers);
        return next({ ...ctx, adminUser: admin });
    })
    .handle(async (input, ctx) => { ... });

withArray()

withArray<K, I>(
   name, 
   itemType, 
description?): FluentToolBuilder<TContext, TInput & Record<K, I extends "string" ? string : I extends "number" ? number : boolean[]>, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:488

Add a required array parameter.

Type Parameters

Type Parameter
`K` extends `string`
`I` extends `"string"` \| `"number"` \| `"boolean"`

Parameters

Parameter	Type	Description
`name`	`K`	Parameter name
`itemType`	`I`	Type of array items (`'string'`, `'number'`, `'boolean'`)
`description?`	`string`	Human-readable description for the LLM

Returns

FluentToolBuilder<TContext, TInput & Record<K, I extends "string" ? string : I extends "number" ? number : boolean[]>, TCtx>

Builder with narrowed TInput type

Example

typescript

f.mutation('tasks.tag')
    .withString('task_id', 'The task to tag')
    .withArray('tags', 'string', 'Tags to apply')
    .handle(async (input) => { ... });
// input.tags: string[] ✅

withArrays()

withArrays<I, R>(itemType, fields): FluentToolBuilder<TContext, TInput & { [K in string]: (I extends "string" ? string : I extends "number" ? number : boolean)[] }, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:634

Add multiple required array parameters in bulk, sharing the same item type.

Type Parameters

Type Parameter
`I` extends `"string"` \| `"number"` \| `"boolean"`
`R` extends `Record`<`string`, `string`>

Parameters

Parameter	Type	Description
`itemType`	`I`	Type of array items (`'string'`, `'number'`, `'boolean'`)
`fields`	`R`	Record of `{ paramName: 'description' }`

Returns

FluentToolBuilder<TContext, TInput & { [K in string]: (I extends "string" ? string : I extends "number" ? number : boolean)[] }, TCtx>

Builder with narrowed TInput type

Example

typescript

f.mutation('tasks.update')
    .withArrays('string', {
        tags:   'Tags to apply',
        labels: 'Category labels',
    })
    .handle(async (input) => { ... });
// input.tags: string[] ✅
// input.labels: string[] ✅

withBoolean()

withBoolean<K>(name, description?): FluentToolBuilder<TContext, TInput & Record<K, boolean>, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:256

Add a required boolean parameter.

Type Parameters

Type Parameter
`K` extends `string`

Parameters

Parameter	Type	Description
`name`	`K`	Parameter name
`description?`	`string`	Human-readable description for the LLM

Returns

FluentToolBuilder<TContext, TInput & Record<K, boolean>, TCtx>

Builder with narrowed TInput type

withBooleans()

withBooleans<R>(fields): FluentToolBuilder<TContext, TInput & { [K in string]: boolean }, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:392

Add multiple required boolean parameters in bulk.

Type Parameters

Type Parameter
`R` extends `Record`<`string`, `string`>

Parameters

Parameter	Type	Description
`fields`	`R`	Record of `{ paramName: 'description' }`

Returns

FluentToolBuilder<TContext, TInput & { [K in string]: boolean }, TCtx>

Builder with narrowed TInput type

withEnum()

withEnum<K, V>(
   name, 
   values, 
description?): FluentToolBuilder<TContext, TInput & Record<K, V>, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:445

Add a required enum parameter.

Type Parameters

Type Parameter
`K` extends `string`
`V` extends `string`

Parameters

Parameter	Type	Description
`name`	`K`	Parameter name
`values`	readonly [`V`, `V`]	Allowed enum values
`description?`	`string`	Human-readable description for the LLM

Returns

FluentToolBuilder<TContext, TInput & Record<K, V>, TCtx>

Builder with narrowed TInput type

Example

typescript

f.query('invoices.list')
    .withEnum('status', ['draft', 'sent', 'paid'], 'Filter by status')
    .handle(async (input) => { ... });
// input.status: 'draft' | 'sent' | 'paid' ✅

withEnums()

withEnums<R>(fields): FluentToolBuilder<TContext, TInput & { [K in string]: R[K][0][number] }, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:578

Add multiple required enum parameters in bulk.

Each entry is paramName: [allowedValues, description?].

Type Parameters

Type Parameter
`R` extends `Record`<`string`, readonly [readonly [`string`, `string`], `string` \| `undefined`]>

Parameters

Parameter	Type	Description
`fields`	`R`	Record of `{ paramName: [values, description?] }`

Returns

FluentToolBuilder<TContext, TInput & { [K in string]: R[K][0][number] }, TCtx>

Builder with narrowed TInput type

Example

typescript

f.query('tasks.filter')
    .withEnums({
        status:   [['open', 'closed', 'archived'], 'Task status'],
        priority: [['low', 'medium', 'high'], 'Priority level'],
    })
    .handle(async (input) => { ... });
// input.status: 'open' | 'closed' | 'archived' ✅

withJson()

withJson<K>(name, description?): FluentToolBuilder<TContext, TInput & Record<K, Record<string, unknown>>, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:534

Add a required JSON object parameter.

Accepts an arbitrary key–value object. Useful for tools that receive structured payloads, configuration maps, or filter sets.

Type Parameters

Type Parameter
`K` extends `string`

Parameters

Parameter	Type	Description
`name`	`K`	Parameter name
`description?`	`string`	Human-readable description for the LLM

Returns

FluentToolBuilder<TContext, TInput & Record<K, Record<string, unknown>>, TCtx>

Builder with narrowed TInput type

Example

typescript

f.action('reports.generate')
    .withJson('payload', 'Report configuration (dates, metrics, grouping)')
    .handle(async (input) => { ... });
// input.payload: Record<string, unknown> ✅

withNumber()

withNumber<K>(name, description?): FluentToolBuilder<TContext, TInput & Record<K, number>, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:226

Add a required number parameter.

Type Parameters

Type Parameter
`K` extends `string`

Parameters

Parameter	Type	Description
`name`	`K`	Parameter name
`description?`	`string`	Human-readable description for the LLM

Returns

FluentToolBuilder<TContext, TInput & Record<K, number>, TCtx>

Builder with narrowed TInput type

withNumbers()

withNumbers<R>(fields): FluentToolBuilder<TContext, TInput & { [K in string]: number }, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:351

Add multiple required number parameters in bulk.

Type Parameters

Type Parameter
`R` extends `Record`<`string`, `string`>

Parameters

Parameter	Type	Description
`fields`	`R`	Record of `{ paramName: 'description' }`

Returns

FluentToolBuilder<TContext, TInput & { [K in string]: number }, TCtx>

Builder with narrowed TInput type

withOptionalArray()

withOptionalArray<K, I>(
   name, 
   itemType, 
description?): FluentToolBuilder<TContext, TInput & Partial<Record<K, I extends "string" ? string : I extends "number" ? number : boolean[]>>, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:505

Add an optional array parameter.

Type Parameters

Type Parameter
`K` extends `string`
`I` extends `"string"` \| `"number"` \| `"boolean"`

Parameters

Parameter	Type	Description
`name`	`K`	Parameter name
`itemType`	`I`	Type of array items (`'string'`, `'number'`, `'boolean'`)
`description?`	`string`	Human-readable description for the LLM

Returns

FluentToolBuilder<TContext, TInput & Partial<Record<K, I extends "string" ? string : I extends "number" ? number : boolean[]>>, TCtx>

Builder with narrowed TInput type

withOptionalArrays()

withOptionalArrays<I, R>(itemType, fields): FluentToolBuilder<TContext, TInput & { [K in string]?: (I extends "string" ? string : I extends "number" ? number : boolean)[] }, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:663

Add multiple optional array parameters in bulk, sharing the same item type.

Type Parameters

Type Parameter
`I` extends `"string"` \| `"number"` \| `"boolean"`
`R` extends `Record`<`string`, `string`>

Parameters

Parameter	Type	Description
`itemType`	`I`	Type of array items (`'string'`, `'number'`, `'boolean'`)
`fields`	`R`	Record of `{ paramName: 'description' }`

Returns

FluentToolBuilder<TContext, TInput & { [K in string]?: (I extends "string" ? string : I extends "number" ? number : boolean)[] }, TCtx>

Builder with narrowed TInput type

Example

typescript

f.query('tasks.filter')
    .withOptionalArrays('string', {
        tags:   'Filter by tags',
        labels: 'Filter by labels',
    })
    .handle(async (input) => { ... });
// input.tags?: string[] | undefined ✅

withOptionalBoolean()

withOptionalBoolean<K>(name, description?): FluentToolBuilder<TContext, TInput & Partial<Record<K, boolean>>, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:271

Add an optional boolean parameter.

Type Parameters

Type Parameter
`K` extends `string`

Parameters

Parameter	Type	Description
`name`	`K`	Parameter name
`description?`	`string`	Human-readable description for the LLM

Returns

FluentToolBuilder<TContext, TInput & Partial<Record<K, boolean>>, TCtx>

Builder with narrowed TInput type

withOptionalBooleans()

withOptionalBooleans<R>(fields): FluentToolBuilder<TContext, TInput & { [K in string]?: boolean }, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:420

Add multiple optional boolean parameters in bulk.

Type Parameters

Type Parameter
`R` extends `Record`<`string`, `string`>

Parameters

Parameter	Type	Description
`fields`	`R`	Record of `{ paramName: 'description' }`

Returns

FluentToolBuilder<TContext, TInput & { [K in string]?: boolean }, TCtx>

Builder with narrowed TInput type

Example

typescript

f.query('tasks.filter')
    .withOptionalBooleans({
        is_blocker:  'Only blockers',
        is_bug:      'Only bugs',
        unassigned:  'Only unassigned tasks',
        is_archived: 'Include archived tasks',
    })
    .handle(async (input) => { ... });
// input.is_blocker?: boolean | undefined ✅

withOptionalEnum()

withOptionalEnum<K, V>(
   name, 
   values, 
description?): FluentToolBuilder<TContext, TInput & Partial<Record<K, V>>, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:462

Add an optional enum parameter.

Type Parameters

Type Parameter
`K` extends `string`
`V` extends `string`

Parameters

Parameter	Type	Description
`name`	`K`	Parameter name
`values`	readonly [`V`, `V`]	Allowed enum values
`description?`	`string`	Human-readable description for the LLM

Returns

FluentToolBuilder<TContext, TInput & Partial<Record<K, V>>, TCtx>

Builder with narrowed TInput type

withOptionalEnums()

withOptionalEnums<R>(fields): FluentToolBuilder<TContext, TInput & { [K in string]?: R[K][0][number] }, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:606

Add multiple optional enum parameters in bulk.

Each entry is paramName: [allowedValues, description?].

Type Parameters

Type Parameter
`R` extends `Record`<`string`, readonly [readonly [`string`, `string`], `string` \| `undefined`]>

Parameters

Parameter	Type	Description
`fields`	`R`	Record of `{ paramName: [values, description?] }`

Returns

FluentToolBuilder<TContext, TInput & { [K in string]?: R[K][0][number] }, TCtx>

Builder with narrowed TInput type

Example

typescript

f.query('tasks.filter')
    .withOptionalEnums({
        status:   [['open', 'closed'], 'Filter by status'],
        priority: [['low', 'medium', 'high'], 'Filter by priority'],
    })
    .handle(async (input) => { ... });
// input.status?: 'open' | 'closed' | undefined ✅

withOptionalJson()

withOptionalJson<K>(name, description?): FluentToolBuilder<TContext, TInput & Partial<Record<K, Record<string, unknown>>>, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:549

Add an optional JSON object parameter.

Type Parameters

Type Parameter
`K` extends `string`

Parameters

Parameter	Type	Description
`name`	`K`	Parameter name
`description?`	`string`	Human-readable description for the LLM

Returns

FluentToolBuilder<TContext, TInput & Partial<Record<K, Record<string, unknown>>>, TCtx>

Builder with narrowed TInput type

withOptionalNumber()

withOptionalNumber<K>(name, description?): FluentToolBuilder<TContext, TInput & Partial<Record<K, number>>, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:241

Add an optional number parameter.

Type Parameters

Type Parameter
`K` extends `string`

Parameters

Parameter	Type	Description
`name`	`K`	Parameter name
`description?`	`string`	Human-readable description for the LLM

Returns

FluentToolBuilder<TContext, TInput & Partial<Record<K, number>>, TCtx>

Builder with narrowed TInput type

withOptionalNumbers()

withOptionalNumbers<R>(fields): FluentToolBuilder<TContext, TInput & { [K in string]?: number }, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:377

Add multiple optional number parameters in bulk.

Type Parameters

Type Parameter
`R` extends `Record`<`string`, `string`>

Parameters

Parameter	Type	Description
`fields`	`R`	Record of `{ paramName: 'description' }`

Returns

FluentToolBuilder<TContext, TInput & { [K in string]?: number }, TCtx>

Builder with narrowed TInput type

Example

typescript

f.query('tasks.filter')
    .withOptionalNumbers({
        per_page:  'Results per page (default: 50)',
        offset:    'Pagination offset',
    })
    .handle(async (input) => { ... });
// input.per_page?: number | undefined ✅

withOptionalString()

withOptionalString<K>(name, description?): FluentToolBuilder<TContext, TInput & Partial<Record<K, string>>, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:211

Add an optional string parameter.

Type Parameters

Type Parameter
`K` extends `string`

Parameters

Parameter	Type	Description
`name`	`K`	Parameter name
`description?`	`string`	Human-readable description for the LLM

Returns

FluentToolBuilder<TContext, TInput & Partial<Record<K, string>>, TCtx>

Builder with narrowed TInput type

withOptionalStrings()

withOptionalStrings<R>(fields): FluentToolBuilder<TContext, TInput & { [K in string]?: string }, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:336

Add multiple optional string parameters in bulk.

Type Parameters

Type Parameter
`R` extends `Record`<`string`, `string`>

Parameters

Parameter	Type	Description
`fields`	`R`	Record of `{ paramName: 'description' }`

Returns

FluentToolBuilder<TContext, TInput & { [K in string]?: string }, TCtx>

Builder with narrowed TInput type

Example

typescript

f.query('tasks.filter')
    .withOptionalStrings({
        title:    'Filter by title (partial match)',
        workflow: 'Column name (e.g. "In Progress")',
        labels:   'Comma-separated label names',
    })
    .handle(async (input) => { ... });
// input.title?: string | undefined ✅

withString()

withString<K>(name, description?): FluentToolBuilder<TContext, TInput & Record<K, string>, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:196

Add a required string parameter.

Type Parameters

Type Parameter
`K` extends `string`

Parameters

Parameter	Type	Description
`name`	`K`	Parameter name
`description?`	`string`	Human-readable description for the LLM

Returns

FluentToolBuilder<TContext, TInput & Record<K, string>, TCtx>

Builder with narrowed TInput type

Example

typescript

f.query('projects.get')
    .withString('project_id', 'The project ID to retrieve')
    .handle(async (input) => { ... });
// input.project_id: string ✅

withStrings()

withStrings<R>(fields): FluentToolBuilder<TContext, TInput & { [K in string]: string }, TCtx>;

Defined in: packages/core/src/core/builder/FluentToolBuilder.ts:309

Add multiple required string parameters in bulk.

Type Parameters

Type Parameter
`R` extends `Record`<`string`, `string`>

Parameters

Parameter	Type	Description
`fields`	`R`	Record of `{ paramName: 'description' }`

Returns

FluentToolBuilder<TContext, TInput & { [K in string]: string }, TCtx>

Builder with narrowed TInput type

Example

typescript

f.query('tasks.get')
    .withStrings({
        company_slug: 'Workspace identifier',
        project_slug: 'Project identifier',
    })
    .handle(async (input) => { ... });
// input.company_slug: string ✅
// input.project_slug: string ✅

Class: FluentToolBuilder<TContext, TInput, TCtx> ​

Type Parameters ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Methods ​

annotations() ​

Parameters ​

Returns ​

bindState() ​

Parameters ​

Returns ​

Example ​

cached() ​

Returns ​

concurrency() ​

Parameters ​

Returns ​

describe() ​

Parameters ​

Returns ​

destructive() ​

Returns ​

egress() ​

Parameters ​

Returns ​

fromModel() ​

Type Parameters ​

Parameters ​

Returns ​

Example ​

handle() ​

Parameters ​

Returns ​

Example ​

idempotent() ​

Returns ​

instructions() ​

Parameters ​

Returns ​

Example ​

interactive() ​

Returns ​

Example ​

invalidates() ​

Parameters ​

Returns ​

proxy() ​

Parameters ​

Returns ​

Example ​

readOnly() ​

Returns ​

returns() ​

Parameters ​

Returns ​

sandboxed() ​

Parameters ​

Returns ​

Example ​

stale() ​

Returns ​

tags() ​

Parameters ​

Returns ​

toonDescription() ​

Returns ​

use() ​

Call Signature ​

Type Parameters ​

Parameters ​

Returns ​

Example ​

Call Signature ​

Type Parameters ​

Parameters ​

Returns ​

Example ​

withArray() ​

Class: FluentToolBuilder<TContext, TInput, TCtx>

Type Parameters

Constructors

Constructor

Parameters

Returns

Methods

annotations()

Parameters

Returns

bindState()

Parameters

Returns

Example

cached()

Returns

concurrency()

Parameters

Returns

describe()

Parameters

Returns

destructive()

Returns

egress()

Parameters

Returns

fromModel()

Type Parameters

Parameters

Returns

Example

handle()

Parameters

Returns

Example

idempotent()

Returns

instructions()

Parameters

Returns

Example

interactive()

Returns

Example

invalidates()

Parameters

Returns

proxy()

Parameters

Returns

Example

readOnly()

Returns

returns()

Parameters

Returns

sandboxed()

Parameters

Returns

Example

stale()

Returns

tags()

Parameters

Returns

toonDescription()

Returns

use()

Call Signature

Type Parameters

Parameters

Returns

Example

Call Signature

Type Parameters

Parameters

Returns

Example

withArray()