ToolAnnotations class

Metadata hints that describe a Tool's behavior to MCP clients.

These annotations inform clients how a tool functions — whether it reads or mutates state, whether repeated calls are safe, and whether it interacts with external systems — enabling clients to automatically permit safe queries or request approval before risky actions.

Important: All properties are hints. Clients should not rely on them for security decisions.

Example:

@Tool(
  description: 'Delete a user permanently',
  annotations: ToolAnnotations(
    destructiveHint: true,
    idempotentHint: true,
    openWorldHint: false,
  ),
)
Future<void> deleteUser(String id) async { ... }

Example — read-only tool:

@Tool(
  description: 'Look up a user by ID',
  annotations: ToolAnnotations(
    title: 'Get User',
    readOnlyHint: true,
    openWorldHint: false,
  ),
)
Future<User?> getUser(int id) async { ... }

Annotations

• @immutable

Constructors

ToolAnnotations({String? title, bool? readOnlyHint, bool? destructiveHint, bool? idempotentHint, bool? openWorldHint})

Creates tool annotations.

const

Properties

destructiveHint → bool?

If true, the tool may perform destructive updates to its environment.

final

hashCode → int

The hash code for this object.

no setter, inherited

idempotentHint → bool?

If true, calling the tool repeatedly with the same arguments will have no additional effect on its environment.

final

openWorldHint → bool?

If true, this tool may interact with an "open world" of external entities (e.g., the internet, third-party APIs).

final

readOnlyHint → bool?

If true, the tool does not modify its environment.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

title → String?

A human-readable title for the tool.

final

Methods

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited