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_contexttool(Drupal Tool API module)tool_ai_connector
Installation
ddev drush en annotations_tool
No configuration required. The three tool plugins are registered automatically on install.
What it provides
Read 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). 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 Read Annotations or Write Annotation.
Write Annotation (annotations_write)
Creates or updates a single annotation's value. Pass target_id, field_name (empty string for a bundle-level annotation), type_id, and value; an optional langcode defaults to the current content language. Finds the latest-revision annotation for that target/field/type combination and updates it, or creates a new one if none exists.
Authorization for the write itself is enforced by AnnotationStorageService::writeValue(), not by this tool's own access gate (see Permissions below) — the calling account needs edit {type} annotations for the type being written, same as a human editor using the UI form.
Permissions
All three tools require view annotations context or administer annotations just to be invoked at all — this mirrors annotations_context's own route access and only gates tool usage in general, not any specific mutation.
Per-type consume {type} annotations permissions further filter which annotation types appear in the Read Annotations output. For Write Annotation, the account additionally needs edit {type} annotations for the type it's writing — enforced inside AnnotationStorageService::writeValue(), the same check AnnotationEditForm relies on. A caller with only view annotations context can call the write tool but every write will be denied unless it also holds that per-type edit permission.
Relationship to other context delivery methods
| Method | Best for |
|---|---|
annotations_tool |
Function-calling agents (in-Drupal, via ai_agents/tool_ai_connector) that pull context on demand |
annotations_export |
Offline documentation pipelines and Obsidian vaults |