Toolmark

Appearance

toolmark-monorepo / @toolmark/core / ToolDefinition

Interface: ToolDefinition<I, O> ​

Defined in: packages/core/src/tool.ts:106

A tool declaration (spec §5). name is the local name; the full name is the scope path + . + name.

Type Parameters ​

I ​

I = unknown

O ​

O = unknown

Properties ​

anchors? ​

optional anchors?: AnchorSpec

Defined in: packages/core/src/tool.ts:145

Tour anchors, read through tm.anchor.

description ​

description: string

Defined in: packages/core/src/tool.ts:112

For the LLM: what the tool does and when to use it.

hints? ​

optional hints?: ToolHints

Defined in: packages/core/src/tool.ts:141

Behaviour hints.

input? ​

optional input?: StandardSchemaV1<unknown, I>

Defined in: packages/core/src/tool.ts:114

Input schema (Standard Schema v1). Input is validated before run.

jsonSchema? ​

optional jsonSchema?: JsonSchema

Defined in: packages/core/src/tool.ts:139

Per-tool JSON Schema override for the input (D14). With input, input validates and this only replaces the advertised schema (it is never compiled).

A tool with jsonSchema and no input is validated against it, compiled with fromJsonSchema. Registration fails with schema_conversion_failed (a throw in dev, the tool not registered otherwise) when the schema cannot be compiled: a non-object root or an invalid schema (a non-schema value in a schema position, such as a draft-07 tuple items: [...]); a $ref that is not a resolvable local #/$defs/<name>; a pattern that does not compile with the u flag; or an unsafe pattern (backreferences, nested quantifiers, overlapping repeated alternation).

Only the fromJsonSchema subset is checked: type, enum, const, properties, required, additionalProperties, items, minItems, maxItems, uniqueItems, minLength, maxLength, pattern, minimum, maximum, multipleOf, format (date, time, date-time, email, uri), anyOf, oneOf, allOf, $defs and local $ref. Every other keyword (for example exclusiveMinimum, not, if/then/else, patternProperties) is accepted but ignored, so validation can be looser than the schema that is advertised; keep the real check on the server. See Forms: fromJsonSchema for the exact rules.

mode? ​

optional mode?: "stepwise"

Defined in: packages/core/src/tool.ts:156

'stepwise' marks a stepwise wizard's tools; reported in manifest entries (spec §8.2).

name ​

name: string

Defined in: packages/core/src/tool.ts:108

Local name (A–Z a–z 0–9 _ - .).

nativeName? ​

optional nativeName?: string

Defined in: packages/core/src/tool.ts:163

For origin: 'native-form': the form's toolname, so consumers that the browser already serves natively (WebMCP) can skip the tool. Read via tm.info, never in a manifest.

origin? ​

optional origin?: ToolOrigin

Defined in: packages/core/src/tool.ts:158

Where the tool came from (default 'code'); read via tm.info, never in a manifest.

output? ​

optional output?: StandardSchemaV1<unknown, O>

Defined in: packages/core/src/tool.ts:116

Output schema; validated in development only.

sensitivePaths? ​

optional sensitivePaths?: () => string[]

Defined in: packages/core/src/tool.ts:154

Input paths whose values are sensitive (passwords, cc-* fields, app-declared ones), evaluated on every read. Surfaced as tm.info(name).sensitivePaths so state() and telemetry share one redaction rule (spec §14). Never part of a manifest. The registry does not redact state() with it: the tool's own state() must (form and wizard tools do).

Returns ​

string[]

state? ​

optional state?: () => ToolState<I>

Defined in: packages/core/src/tool.ts:147

Synchronous, side-effect-free state snapshot, read through tm.state.

Returns ​

ToolState<I>

summary? ​

optional summary?: (input) => string

Defined in: packages/core/src/tool.ts:143

User-facing one-liner for confirmation cards.

Parameters ​

input ​

I

Returns ​

string

title? ​

optional title?: string

Defined in: packages/core/src/tool.ts:110

User-facing, app-localized title.

Methods ​

run() ​

run(input, ctx): ToolResult<O> | Promise<ToolResult<O>>

Defined in: packages/core/src/tool.ts:165

Runs the tool with validated input. Never needs to throw: return a ToolResult.

Parameters ​

input ​

I

ctx ​

ToolContext

Returns ​

ToolResult<O> | Promise<ToolResult<O>>