Graphorin API reference v0.7.0

---

Graphorin API reference / @graphorin/core / / ResolvedTool

Interface: ResolvedTool<TInput, TOutput, TDeps>

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

Resolved record returned by the ToolRegistry getter. Carries every non-public registration-time field downstream layers consume (sanitization, audit, retrieval, side-effect classification, collision resolution, …) so consumers do not have to recompute it.

Stable

Extends

• Tool<TInput, TOutput, TDeps>

Type Parameters

Type Parameter	Default type
TInput	unknown
TOutput	unknown
TDeps	unknown

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
__effectiveDeferLoading	readonly	boolean	-	-	packages/core/src/contracts/tool.ts:227
__exampleCount	readonly	number	-	-	packages/core/src/contracts/tool.ts:231
__hasIdempotencyKey	readonly	boolean	-	-	packages/core/src/contracts/tool.ts:229
__preferredModel?	readonly	| ModelHint | ModelSpec	-	-	packages/core/src/contracts/tool.ts:232
__sideEffectClass	readonly	SideEffectClass	-	-	packages/core/src/contracts/tool.ts:228
__source	readonly	ToolSource	-	-	packages/core/src/contracts/tool.ts:226
__streamingHint	readonly	boolean	-	-	packages/core/src/contracts/tool.ts:230
__trustClass	readonly	ToolTrustClass	-	-	packages/core/src/contracts/tool.ts:225
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. Naming note (W-127): the snake_case is DELIBERATE - this field mirrors the wire-level defer_loading flag of the Anthropic tool-use surface one-to-one, so grep and serialized payloads match. It is the only snake_case field on Tool by design, not an oversight. Default false	Tool.defer_loading	packages/core/src/contracts/tool.ts:112
description	readonly	string	-	Tool.description	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.	Tool.examples	packages/core/src/contracts/tool.ts:130
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).	Tool.examplesEagerlyRendered	packages/core/src/contracts/tool.ts:137
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'	Tool.executionMode	packages/core/src/contracts/tool.ts:66
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	Tool.failClosed	packages/core/src/contracts/tool.ts:96
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.	Tool.idempotencyKey	packages/core/src/contracts/tool.ts:151
inboundSanitization?	readonly	InboundSanitizationPolicy	Inbound prompt-injection sanitization policy.	Tool.inboundSanitization	packages/core/src/contracts/tool.ts:88
inputSchema	readonly	ZodLikeSchema<TInput>	-	Tool.inputSchema	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	Tool.maxResultTokens	packages/core/src/contracts/tool.ts:121
memoryGuardTier?	readonly	MemoryGuardTier	Memory-modification guard tier (DEC-153). ACTIVE when the agent is created with memory wired (SDF-1): the runtime binds a scope-aware region reader over working memory and the executor snapshots/verifies the region around guarded calls. Without memory the guard is skipped and the agent emits a one-time WARN.	Tool.memoryGuardTier	packages/core/src/contracts/tool.ts:86
name	readonly	string	-	Tool.name	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.	Tool.needsApproval	packages/core/src/contracts/tool.ts:45
outputSchema?	readonly	ZodLikeSchema<TOutput, unknown>	-	Tool.outputSchema	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'	'smart') OR an explicit ModelSpec` that always wins over the agent-side tier mapping.
sandboxPolicy?	readonly	SandboxPolicy	Sandbox isolation level. Defaults are picked by @graphorin/security. ADVISORY in the default agent build (AG-18): inline config.tools closures cannot be serialised out-of-process, so the resolved policy is surfaced on the tool.execute span / audit but the tool runs in-process. Real isolation applies to module-loadable (skill / MCP) tools.	Tool.sandboxPolicy	packages/core/src/contracts/tool.ts:56
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.	Tool.secretsAllowed	packages/core/src/contracts/tool.ts:72
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).	Tool.sensitivity	packages/core/src/contracts/tool.ts:78
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.	Tool.sideEffectClass	packages/core/src/contracts/tool.ts:144
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>.	Tool.streamingHint	packages/core/src/contracts/tool.ts:162
tags?	readonly	readonly string[]	Free-form labels surfaced to operators and to the model.	Tool.tags	packages/core/src/contracts/tool.ts:58
truncationStrategy?	readonly	TruncationStrategy	Truncation strategy applied when maxResultTokens is exceeded.	Tool.truncationStrategy	packages/core/src/contracts/tool.ts:123

Methods

execute()

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

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

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< | TOutput | ToolReturn&lt;TOutput&gt; | undefined>

Inherited from

Tool.execute