Skip to content

Annotations Tool API

Submodule of Annotations. Exposes annotation context as Tool API plugins for on-demand retrieval by function-calling AI agents.

When an AI agent needs to understand how a content type or field is used, it calls one of these tools. The tools delegate to annotations_context for assembly and return clean markdown — the same output a human would see from the context preview page.

Requirements

  • annotations (core Annotations module)
  • annotations_context
  • tool (Drupal Tool API module)
  • tool_ai_connector

Installation

ddev drush en annotations_tool

No configuration required. The two tool plugins are registered automatically on install.

What it provides

Get Annotations (annotations_read)

Returns annotation documentation for a Drupal entity bundle as markdown. Pass a target ID (e.g. node__article) to scope the result to one bundle, or omit it to return all configured targets.

The tool filters annotation types by the calling user's consume {type} annotations permissions, and further restricts results to types opted into annotations_context's in_ai_context third-party setting (set via the annotation type edit form) — the same gate the MCP endpoint applies. A type must be both consumable by the account and opted into AI context to appear in the output.

List Annotation Targets (annotations_list_targets)

Returns all annotation targets configured on the site, one per line in the format target_id — Label (entity_type). Use this to discover valid target IDs before calling Get Annotations.

Permissions

Both tools require view annotations context or administer annotations. Assign view annotations context to any role whose AI agent should be able to retrieve annotation documentation.

Per-type consume {type} annotations permissions further filter which annotation types appear in the Get Annotations output.

Relationship to other context delivery methods

Method Best for
annotations_tool Function-calling agents that pull context on demand
annotations_context MCP endpoint MCP-compatible tools and IDE integrations
annotations_export Offline documentation pipelines and Obsidian vaults