Skip to content

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 ​

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

Properties ​

PropertyTypeDescription
nameString
typeString
descriptionString
requiredbool
itemsMap<String, dynamic>?JSON Schema for array element type. Required by OpenAI's strict function-calling validator when [type] is 'array'.
callIdToolCallIdThe call-site identifier, set by the agent. Empty when produced directly by a [Tool].
successboolWhether the invocation succeeded. false flags the UI and LLM that the tool could not complete its task.
contentStringPrimary payload sent to the LLM. For errors, a human-readable description.
summaryString?Optional one-liner preferred by the UI (e.g. "Read foo.dart (42 lines)"). When null, renderers fall back to truncating [content].
metadataMap<String, dynamic>Structured metadata populated by the tool (bytes, line_count, exit_code, match_count, entry_count, etc.). Always non-null.
contentPartsList<ContentPart>?Multimodal artifacts (e.g. screenshots). When present, these replace [content] in the LLM payload.
nameString getMachine-readable tool name (e.g. read_file).
descriptionString getHuman-readable description shown to the LLM.
parametersList<ToolParameter> getParameter definitions used to build the JSON schema sent to the LLM.
requiredParametersList<ToolParameter> getSubset of [parameters] where [ToolParameter.required] is true.
trustToolTrust getThe trust level this tool requires. Defaults to [ToolTrust.safe].
isMutatingbool getWhether this tool can mutate state (files, shell commands, etc.).
innerTool
nameString get
descriptionString get
parametersList<ToolParameter> get
trustToolTrust get
isMutatingbool get
nameString getMachine-readable tool name (e.g. read_file).
descriptionString getHuman-readable description shown to the LLM.
parametersList<ToolParameter> getParameter definitions used to build the JSON schema sent to the LLM.
requiredParametersList<ToolParameter> getSubset of [parameters] where [ToolParameter.required] is true.
trustToolTrust getThe trust level this tool requires. Defaults to [ToolTrust.safe].
isMutatingbool getWhether this tool can mutate state (files, shell commands, etc.).
nameString get
descriptionString get
parametersList<ToolParameter> get
trustToolTrust get
isMutatingbool 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 ​

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

Properties ​

PropertyTypeDescription
callIdToolCallIdThe call-site identifier, set by the agent. Empty when produced directly by a [Tool].
successboolWhether the invocation succeeded. false flags the UI and LLM that the tool could not complete its task.
contentStringPrimary payload sent to the LLM. For errors, a human-readable description.
summaryString?Optional one-liner preferred by the UI (e.g. "Read foo.dart (42 lines)"). When null, renderers fall back to truncating [content].
metadataMap&lt;String, dynamic&gt;Structured metadata populated by the tool (bytes, line_count, exit_code, match_count, entry_count, etc.). Always non-null.
contentPartsList&lt;ContentPart&gt;?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&lt;ContentPart&gt; 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 ​

PropertyTypeDescription
nameString getMachine-readable tool name (e.g. read_file).
descriptionString getHuman-readable description shown to the LLM.
parametersList&lt;ToolParameter&gt; getParameter definitions used to build the JSON schema sent to the LLM.
requiredParametersList&lt;ToolParameter&gt; getSubset of [parameters] where [ToolParameter.required] is true.
trustToolTrust getThe trust level this tool requires. Defaults to [ToolTrust.safe].
isMutatingbool getWhether this tool can mutate state (files, shell commands, etc.).
nameString getMachine-readable tool name (e.g. read_file).
descriptionString getHuman-readable description shown to the LLM.
parametersList&lt;ToolParameter&gt; getParameter definitions used to build the JSON schema sent to the LLM.
requiredParametersList&lt;ToolParameter&gt; getSubset of [parameters] where [ToolParameter.required] is true.
trustToolTrust getThe trust level this tool requires. Defaults to [ToolTrust.safe].
isMutatingbool getWhether this tool can mutate state (files, shell commands, etc.).

Methods ​

Future&lt;ToolResult&gt; execute(Map&lt;String, dynamic&gt; 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&lt;void&gt; 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 ​

dart
ForwardingTool(this.inner)

Properties ​

PropertyTypeDescription
innerTool
nameString get
descriptionString get
parametersList&lt;ToolParameter&gt; get
trustToolTrust get
isMutatingbool get
nameString get
descriptionString get
parametersList&lt;ToolParameter&gt; get
trustToolTrust get
isMutatingbool get

Methods ​

Future&lt;ToolResult&gt; execute(Map&lt;String, dynamic&gt; args) ​
Future&lt;void&gt; dispose() ​

Released under the MIT License.