Graphorin API reference v0.1.0

---

Graphorin API reference / @graphorin/core / / Tool

Interface: Tool<TInput, TOutput, TDeps>

Defined in: packages/core/src/contracts/tool.ts:35

Pluggable function call exposed to an LLM. Concrete Tool instances are produced by the tool({...}) factory in @graphorin/tools and by the MCP / Skills loaders. The interface lives in core because every package above the persistence layer (agent runtime, workflow engine, server, sessions, observability, …) carries Tool[] references on its public surface.

The interface is intentionally minimal — extension fields covered by later phases (per-tool secretsAllowed ACL, inbound sanitization policy, result truncation strategy, streaming hint, …) are added additively by their owning packages so that v0.1 consumers can type their tool list against Tool<...> today without having to worry about future fields.

Stable

Extended by

• ResolvedTool

Type Parameters

Type Parameter	Default type
TInput	unknown
TOutput	unknown
TDeps	unknown

Properties

Property	Modifier	Type	Description	Defined in
defer_loading?	readonly	boolean	Defer the tool from the per-step catalogue until the model invokes the built-in tool_search to look it up. Tools with deferred loading are not advertised to the model on every step, which keeps the input-token cost bounded for installations with dozens of MCP-derived tools. Default false	packages/core/src/contracts/tool.ts:93
description	readonly	string	-	packages/core/src/contracts/tool.ts:37
examples?	readonly	readonly ToolExample<TInput, TOutput>[]	Worked examples shown to the model alongside the tool's description. Bounded [1, 5] — overflow emits a one-time WARN at registration. Each example's input and output is validated against the tool's inputSchema / outputSchema.	packages/core/src/contracts/tool.ts:111
examplesEagerlyRendered?	readonly	boolean	Render examples eagerly (every step) regardless of defer_loading. When undefined the runtime applies the auto-rule: defer_loading: true ⇒ false; defer_loading: false ⇒ true; neither ⇒ undefined (the agent runtime decides at assembly time).	packages/core/src/contracts/tool.ts:118
executionMode?	readonly	"parallel" | "sequential"	Sequential execution mode hints. Tools tagged 'sequential' are never executed in parallel with each other; the executor serializes them inside the per-step batch. Default 'parallel'	packages/core/src/contracts/tool.ts:59
failClosed?	readonly	boolean	When true, an inbound-sanitization hit returns ToolError({ kind: 'inbound_sanitization_blocked' }) instead of forwarding the (sanitized) result. Intended for regulated deployments. Default false	packages/core/src/contracts/tool.ts:83
idempotencyKey?	readonly	(input, ctx) => string | Promise<string>	Optional callback returning a deterministic dedup key per (input, ctx) tuple. REQUIRED-by-WARN for 'side-effecting' / 'external-stateful' tools. The framework does not validate determinism — that is the operator's contract.	packages/core/src/contracts/tool.ts:132
inboundSanitization?	readonly	InboundSanitizationPolicy	Inbound prompt-injection sanitization policy.	packages/core/src/contracts/tool.ts:75
inputSchema	readonly	ZodLikeSchema<TInput>	-	packages/core/src/contracts/tool.ts:38
maxResultTokens?	readonly	number	Maximum number of tokens the assembled tool result may carry into the conversation history. 0 disables the cap (logs a one-time WARN at registration). Counted against text-shaped output and text-shaped contentParts entries; non-text parts pass through. Default 16384	packages/core/src/contracts/tool.ts:102
memoryGuardTier?	readonly	MemoryGuardTier	Memory-modification guard tier (DEC-153).	packages/core/src/contracts/tool.ts:73
name	readonly	string	-	packages/core/src/contracts/tool.ts:36
needsApproval?	readonly	boolean | ((input, ctx) => boolean | Promise<boolean>)	Either a static boolean or a predicate consulted at runtime against the realized input. true means the runtime suspends the run with a tool.approval.requested event before the tool executes.	packages/core/src/contracts/tool.ts:45
outputSchema?	readonly	ZodLikeSchema<TOutput, unknown>	-	packages/core/src/contracts/tool.ts:39
preferredModel?	readonly	| ModelHint | ModelSpec	Per-tool author-time model hint. Either a cost-tier vocabulary literal (`'fast'	'balanced'
sandboxPolicy?	readonly	SandboxPolicy	Sandbox isolation level. Defaults are picked by @graphorin/security.	packages/core/src/contracts/tool.ts:49
secretsAllowed?	readonly	readonly string[]	Per-tool secrets ACL. Tool execution is wrapped in a scope where ctx.secrets.require(...) only resolves keys present here. Empty / undefined means the tool may not request any secret.	packages/core/src/contracts/tool.ts:65
sensitivity?	readonly	Sensitivity	Sensitivity ceiling of the tool's input + output payload. Used by the redaction validator to decide whether the result may flow to a given sink (provider / exporter).	packages/core/src/contracts/tool.ts:71
sideEffectClass?	readonly	SideEffectClass	REQUIRED side-effect classification. v0.1 transition mode emits a one-time WARN per tool name on missing classification and applies the conservative deferred default 'side-effecting'; v0.2 may promote the WARN to a registration error.	packages/core/src/contracts/tool.ts:125
streamingHint?	readonly	true	Opt-in flag for streaming-tool execution. The ?: true typing rejects streamingHint: false on purpose — absence is the canonical "non-streaming" signal preserving v0.1 behaviour. When true, Tool.execute(...) may call ctx.streamContent(...) / ctx.reportProgress(...) and may return Promise<void>.	packages/core/src/contracts/tool.ts:143
tags?	readonly	readonly string[]	Free-form labels surfaced to operators and to the model.	packages/core/src/contracts/tool.ts:51
truncationStrategy?	readonly	TruncationStrategy	Truncation strategy applied when maxResultTokens is exceeded.	packages/core/src/contracts/tool.ts:104

Methods

execute()

execute(input, ctx): Promise<
  | void
  | TOutput
| ToolReturn<TOutput>>;

Defined in: packages/core/src/contracts/tool.ts:157

Execute the tool. Concrete implementations may return either a raw TOutput or a ToolReturn<TOutput> envelope when extra content parts (images, files, …) need to be appended to the conversation. Streaming-hint tools may also return void once the per-chunk buffer has been populated.

Parameters

Parameter	Type
input	TInput
ctx	ToolExecutionContext<TDeps>

Returns

Promise< | void | TOutput | ToolReturn&lt;TOutput&gt;>