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 setterinherited
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 setterinherited
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