Tool

Category: Tools

Source: tool.dart

Tool abstraction shared by the agent loop and the LLM strategies.

Status: part of the proposed core data model — see docs/plans/2026-04-29-harness-layers.md. Originally lived in agent/tools.dart; relocated so strategies (LLM clients, providers) can depend on these types without crossing the harness boundary.

Tool implementations (ReadFileTool, BashTool, …) stay in agent/tools.dart because they pull in I/O and runtime dependencies. Only the abstract surface area moves here.

Enums

ToolTrust

How much trust a tool requires from the permission system.

Classes

ToolParameter

Schema for a single tool parameter.

Constructor

const ToolParameter({
    required this.name,
    required this.type,
    required this.description,
    this.required = true,
    this.items,
  })

Properties

Property	Type	Description
name	String
type	String
description	String
required	bool
items	Map<String, dynamic>?	JSON Schema for array element type. Required by OpenAI's strict function-calling validator when [type] is 'array'.
callId	ToolCallId	The call-site identifier, set by the agent. Empty when produced directly by a [Tool].
success	bool	Whether the invocation succeeded. false flags the UI and LLM that the tool could not complete its task.
content	String	Primary payload sent to the LLM. For errors, a human-readable description.
summary	String?	Optional one-liner preferred by the UI (e.g. "Read foo.dart (42 lines)"). When null, renderers fall back to truncating [content].
metadata	Map<String, dynamic>	Structured metadata populated by the tool (bytes, line_count, exit_code, match_count, entry_count, etc.). Always non-null.
contentParts	List<ContentPart>?	Multimodal artifacts (e.g. screenshots). When present, these replace [content] in the LLM payload.
name	String get	Machine-readable tool name (e.g. read_file).
description	String get	Human-readable description shown to the LLM.
parameters	List<ToolParameter> get	Parameter definitions used to build the JSON schema sent to the LLM.
requiredParameters	List<ToolParameter> get	Subset of [parameters] where [ToolParameter.required] is true.
trust	ToolTrust get	The trust level this tool requires. Defaults to [ToolTrust.safe].
isMutating	bool get	Whether this tool can mutate state (files, shell commands, etc.).
inner	Tool
name	String get
description	String get
parameters	List<ToolParameter> get
trust	ToolTrust get
isMutating	bool get
name	String get	Machine-readable tool name (e.g. read_file).
description	String get	Human-readable description shown to the LLM.
parameters	List<ToolParameter> get	Parameter definitions used to build the JSON schema sent to the LLM.
requiredParameters	List<ToolParameter> get	Subset of [parameters] where [ToolParameter.required] is true.
trust	ToolTrust get	The trust level this tool requires. Defaults to [ToolTrust.safe].
isMutating	bool get	Whether this tool can mutate state (files, shell commands, etc.).
name	String get
description	String get
parameters	List<ToolParameter> get
trust	ToolTrust get
isMutating	bool get

Methods

ToolResult withCallId(ToolCallId id)

Returns a copy with [callId] set. The agent invokes this to stamp a tool's bare output with the originating call's identifier.

List<ContentPart> toContentParts()

Serialises the LLM-facing payload into [ContentPart]s.

When [contentParts] is non-null (e.g. a screenshot) those parts are returned directly; otherwise [content] is wrapped in a single [TextPart].

Future<ToolResult> execute(Map<String, dynamic> args)

Executes this tool with the given [args] and returns a [ToolResult].

Implementations should leave [ToolResult.callId] as its default (empty) — the agent stamps it in via [ToolResult.withCallId] when wrapping the result for the conversation.

Future<void> dispose()

Releases any resources held by this tool.

Future<ToolResult> execute(Map<String, dynamic> args)

Future<void> dispose()

ToolResult

Structured result of a tool invocation.

Tools produce a [ToolResult] with [callId] left as the empty [ToolCallId] — the agent fills it in via [withCallId] when wrapping the result for the conversation envelope. The [content] string is what the LLM sees; [summary] is an optional one-liner preferred by the UI; [metadata] carries structured fields (bytes, line_count, exit_code, paths, …).

Constructor

ToolResult({
    this.callId = const ToolCallId(''),
    this.success = true,
    required this.content,
    this.summary,
    Map<String, dynamic>? metadata,
    this.contentParts,
  })

factory ToolResult.denied(ToolCallId callId)

Properties

Property	Type	Description
callId	ToolCallId	The call-site identifier, set by the agent. Empty when produced directly by a [Tool].
success	bool	Whether the invocation succeeded. false flags the UI and LLM that the tool could not complete its task.
content	String	Primary payload sent to the LLM. For errors, a human-readable description.
summary	String?	Optional one-liner preferred by the UI (e.g. "Read foo.dart (42 lines)"). When null, renderers fall back to truncating [content].
metadata	Map<String, dynamic>	Structured metadata populated by the tool (bytes, line_count, exit_code, match_count, entry_count, etc.). Always non-null.
contentParts	List<ContentPart>?	Multimodal artifacts (e.g. screenshots). When present, these replace [content] in the LLM payload.

Methods

ToolResult withCallId(ToolCallId id)

Returns a copy with [callId] set. The agent invokes this to stamp a tool's bare output with the originating call's identifier.

List<ContentPart> toContentParts()

Serialises the LLM-facing payload into [ContentPart]s.

When [contentParts] is non-null (e.g. a screenshot) those parts are returned directly; otherwise [content] is wrapped in a single [TextPart].

abstract Tool

Base class for all tools available to the agent.

Each tool declares its [name], [description], and [parameters] so the LLM can decide when and how to invoke it. The [execute] method performs the actual work and returns a [ToolResult].

Properties

Property	Type	Description
name	String get	Machine-readable tool name (e.g. read_file).
description	String get	Human-readable description shown to the LLM.
parameters	List<ToolParameter> get	Parameter definitions used to build the JSON schema sent to the LLM.
requiredParameters	List<ToolParameter> get	Subset of [parameters] where [ToolParameter.required] is true.
trust	ToolTrust get	The trust level this tool requires. Defaults to [ToolTrust.safe].
isMutating	bool get	Whether this tool can mutate state (files, shell commands, etc.).
name	String get	Machine-readable tool name (e.g. read_file).
description	String get	Human-readable description shown to the LLM.
parameters	List<ToolParameter> get	Parameter definitions used to build the JSON schema sent to the LLM.
requiredParameters	List<ToolParameter> get	Subset of [parameters] where [ToolParameter.required] is true.
trust	ToolTrust get	The trust level this tool requires. Defaults to [ToolTrust.safe].
isMutating	bool get	Whether this tool can mutate state (files, shell commands, etc.).

Methods

Future<ToolResult> execute(Map<String, dynamic> args)

Executes this tool with the given [args] and returns a [ToolResult].

Implementations should leave [ToolResult.callId] as its default (empty) — the agent stamps it in via [ToolResult.withCallId] when wrapping the result for the conversation.

Future<void> dispose()

Releases any resources held by this tool.

ForwardingTool

Base class for tool decorators. Forwards all methods to [inner].

Extend this and override only what you need. When new methods are added to [Tool], only this class needs updating — all decorators inherit the forwarding automatically.

Constructor

ForwardingTool(this.inner)

Properties

Property	Type	Description
inner	Tool
name	String get
description	String get
parameters	List<ToolParameter> get
trust	ToolTrust get
isMutating	bool get
name	String get
description	String get
parameters	List<ToolParameter> get
trust	ToolTrust get
isMutating	bool get

Methods

Future<ToolResult> execute(Map<String, dynamic> args)

Future<void> dispose()