Interface: ToolBuilder<TContext>

Defined in: packages/core/src/core/types.ts:46

Interface that all tool builders must implement.

This is the abstraction that ToolRegistry depends on, following the Dependency Inversion Principle. You can create custom builders by implementing this interface.

Example

// The built-in GroupedToolBuilder implements this interface:
const builder: ToolBuilder<AppContext> = new GroupedToolBuilder<AppContext>('projects');

// Register with the registry:
const registry = new ToolRegistry<AppContext>();
registry.register(builder);

See

• GroupedToolBuilder for the default implementation
• ToolRegistry for registration and routing

Type Parameters

Type Parameter	Default type	Description
TContext	void	Application context passed to every handler

Methods

buildToolDefinition()

buildToolDefinition(): {
  _meta?: {
   [key: string]: unknown;
  };
  annotations?: {
     destructiveHint?: boolean;
     idempotentHint?: boolean;
     openWorldHint?: boolean;
     readOnlyHint?: boolean;
     title?: string;
  };
  description?: string;
  execution?: {
     taskSupport?: "optional" | "required" | "forbidden";
  };
  icons?: {
     mimeType?: string;
     sizes?: string[];
     src: string;
     theme?: "light" | "dark";
  }[];
  inputSchema: {
   [key: string]: unknown;
     properties?: {
      [key: string]: object;
     };
     required?: string[];
     type: "object";
  };
  name: string;
  outputSchema?: {
   [key: string]: unknown;
     properties?: {
      [key: string]: object;
     };
     required?: string[];
     type: "object";
  };
  title?: string;
};

Defined in: packages/core/src/core/types.ts:60

Build and return the MCP Tool definition. May cache internally.

Returns

{
  _meta?: {
   [key: string]: unknown;
  };
  annotations?: {
     destructiveHint?: boolean;
     idempotentHint?: boolean;
     openWorldHint?: boolean;
     readOnlyHint?: boolean;
     title?: string;
  };
  description?: string;
  execution?: {
     taskSupport?: "optional" | "required" | "forbidden";
  };
  icons?: {
     mimeType?: string;
     sizes?: string[];
     src: string;
     theme?: "light" | "dark";
  }[];
  inputSchema: {
   [key: string]: unknown;
     properties?: {
      [key: string]: object;
     };
     required?: string[];
     type: "object";
  };
  name: string;
  outputSchema?: {
   [key: string]: unknown;
     properties?: {
      [key: string]: object;
     };
     required?: string[];
     type: "object";
  };
  title?: string;
}

Name	Type	Defined in
_meta?	{ [key: string]: unknown; }	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2397
annotations?	{ destructiveHint?: boolean; idempotentHint?: boolean; openWorldHint?: boolean; readOnlyHint?: boolean; title?: string; }	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2383
annotations.destructiveHint?	boolean	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2386
annotations.idempotentHint?	boolean	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2387
annotations.openWorldHint?	boolean	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2388
annotations.readOnlyHint?	boolean	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2385
annotations.title?	string	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2384
description?	string	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2372
execution?	{ taskSupport?: "optional" | "required" | "forbidden"; }	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2390
execution.taskSupport?	"optional" | "required" | "forbidden"	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2391
icons?	{ mimeType?: string; sizes?: string[]; src: string; theme?: "light" | "dark"; }[]	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2398
inputSchema	{ [key: string]: unknown; properties?: { [key: string]: object; }; required?: string[]; type: "object"; }	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2373
inputSchema.properties?	{ [key: string]: object; }	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2375
inputSchema.required?	string[]	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2376
inputSchema.type	"object"	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2374
name	string	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2407
outputSchema?	{ [key: string]: unknown; properties?: { [key: string]: object; }; required?: string[]; type: "object"; }	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2378
outputSchema.properties?	{ [key: string]: object; }	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2380
outputSchema.required?	string[]	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2381
outputSchema.type	"object"	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2379
title?	string	node_modules/@modelcontextprotocol/sdk/dist/esm/types.d.ts:2408

---

execute()

execute(
   ctx, 
   args, 
   progressSink?, 
signal?): Promise<ToolResponse>;

Defined in: packages/core/src/core/types.ts:63

Execute a tool call with the given context and arguments

Parameters

Parameter	Type
ctx	TContext
args	Record<string, unknown>
progressSink?	ProgressSink
signal?	AbortSignal

Returns

Promise<ToolResponse>

---

getActionMetadata()

getActionMetadata(): ActionMetadata[];

Defined in: packages/core/src/core/types.ts:57

Get metadata for all registered actions

Returns

ActionMetadata[]

---

getActionNames()

getActionNames(): string[];

Defined in: packages/core/src/core/types.ts:54

Get all registered action keys

Returns

string[]

---

getActions()?

optional getActions(): readonly InternalAction<TContext>[];

Defined in: packages/core/src/core/types.ts:80

Get all registered internal actions. Used by Exposition Compiler for atomic tool expansion.

Returns

readonly InternalAction<TContext>[]

---

getCommonSchema()?

optional getCommonSchema(): 
  | ZodObject<ZodRawShape, UnknownKeysParam, ZodTypeAny, {
[key: string]: any;
}, {
[key: string]: any;
}>
  | undefined;

Defined in: packages/core/src/core/types.ts:84

Get the common schema shared across all actions.

Returns

| ZodObject<ZodRawShape, UnknownKeysParam, ZodTypeAny, { [key: string]: any; }, { [key: string]: any; }> | undefined

---

getDiscriminator()?

optional getDiscriminator(): string;

Defined in: packages/core/src/core/types.ts:82

Get the discriminator field name (e.g. "action").

Returns

string

---

getName()

getName(): string;

Defined in: packages/core/src/core/types.ts:48

Get the tool name (used as the registration key)

Returns

string

---

getSelectEnabled()?

optional getSelectEnabled(): boolean;

Defined in: packages/core/src/core/types.ts:86

Check if _select reflection is enabled for context window optimization.

Returns

boolean

---

getStateSyncHints()?

optional getStateSyncHints(): ReadonlyMap<string, StateSyncHint>;

Defined in: packages/core/src/core/types.ts:91

Get per-action state sync hints declared via fluent .invalidates() / .cached().

Returns

ReadonlyMap<string, StateSyncHint>

---

getTags()

getTags(): string[];

Defined in: packages/core/src/core/types.ts:51

Get the capability tags for selective exposure

Returns

string[]

---

previewPrompt()

previewPrompt(): string;

Defined in: packages/core/src/core/types.ts:75

Preview the exact MCP prompt payload that the LLM will receive.

Returns a formatted string showing the compiled tool definition (name, description, input schema, annotations) with approximate token count. Auto-calls buildToolDefinition() if needed.

Use this to optimize token usage and verify LLM-facing grammar without starting an MCP server.

Returns

string