Shared descriptions of data and operations could be Drupal's next CCK and Views moment.
User interfaces also keep changing: web pages, then native mobile apps, then headless front ends, then chat, and now AI assistants and agents. I don't know what comes after agents. But if modules describe their data and operations, new interfaces can build on the capabilities we already have. The next interface reads the description and gets to work. That won't make Drupal immune to change, but it makes us fast to adapt, and fast to adapt helps us win.
The question then becomes how to make that practical for thousands of module maintainers. Tool API gives us a starting point, alongside years of work on Typed Data, Single Directory Components, JSON:API, Drupal Canvas Code Components, [Modeler API](https://www.drupal.org/project/modeler_api), and more. We need the people behind that work to help shape the approach, including whether Tool API, or parts of it, belongs in Drupal Core.
That's why I'm organizing the Rosetta Sprint: a few days for the people behind these projects to get together in person to compare the existing approaches, identify what is missing and agree on next steps with the relevant maintainers and Core committers.
## Describe existing data and expose functions as tools
Tool API supports two ways to define a tool: (1) you can write a dedicated plugin class that Drupal discovers as a tool, or (2) add PHP attributes to an existing public method on a class registered as a [Drupal service](https://www.drupal.org/docs/drupal-apis/services-and-dependency-injection/structure-of-a-service-file).
I started with a dedicated plugin class but ultimately switched to PHP attributes. Attribute support was still experimental when I started, and I helped improve Tool API as I used it ([#3583030](https://git.drupalcode.org/project/tool/-/work_items/3583030), [#3583031](https://git.drupalcode.org/project/tool/-/work_items/3583031), [#3583032](https://git.drupalcode.org/project/tool/-/work_items/3583032), [#3583041](https://git.drupalcode.org/project/tool/-/work_items/3583041), [#3583085](https://git.drupalcode.org/project/tool/-/work_items/3583085)). The [attribute support is now merged and available in Tool API's development version](https://git.drupalcode.org/project/tool/-/work_items/3518120). Dedicated plugin classes remain fully supported.
I'll show the basic pieces here rather than walk through a full tutorial. Here is how the method that searches my photos becomes the `find_images` tool, simplified a little:
```php
/**
* Searches the images.
*
* @param string $query
* Words to look for in the title, caption or alt text.
*
* @return \Drupal\album\Image[]
* The matching images.
*/
#[ToolMethod(
id: 'find_images',
label: 'Find images',
description: "Searches the site's images. …",
operation: ToolOperation::Read,
permission: 'access content',
)]
public function search(string $query): array {
// The search code is unchanged.
}
```
The method body stays the same: it takes a search query and returns the matching images. The `#[ToolMethod]` attribute gives the tool its ID, label and description. It also declares that the operation reads data and that the caller needs the `access content` permission. The search code must still enforce any restrictions on which photos the caller can see.
Tool API reads the input's name and type, `query` and `string`, from the method signature. When type information is missing, Tool API tries to infer it from the method signature and docblock. Here, the `Image[]` return annotation tells Tool API that the array contains `Image` objects.
Knowing that the result is a list of `Image` objects doesn't tell other software which properties a photo has. I describe those with `#[ToolProperty]` attributes on the `Image` class's getters, like `getAlt()` above.
The attributes also explain what each property means. In PHP, a title, a caption and a URL can all be strings, but other software needs to know which is plain text, which contains HTML and which is a URL. I illustrated that distinction in the keynote:
*A slide from
my DrupalCon Rotterdam 2026 keynote: all three values have PHP's
string type, but
#\[ToolProperty\] attributes describe the title as plain text, the caption as HTML and the URL as a URI.*