Tool API

A pluggable API for defining executable logic with typed inputs and outputs.

Tool API is a modern, typed, extensible framework for defining executable units of logic in Drupal. Think of it as a next-generation replacement for core Actions - with clear input and output schemas, validation and access control built into the contract, and one definition that every consumer can discover and run: AI agents, MCP clients, ECA workflows, Drush, or your own code.

Key capabilities

• Typed input and output definitions with defaults, constraints and examples, self-documenting down to nested list items and map properties.
• JSON Schema advertisement for AI function calling and MCP tools/list, generated from the definitions.
• Validation before execution: declared Symfony constraints run against the typed values, with violations reported per item and property.
• Access as part of the contract: access() gates every invocation, and results carry cacheability.
• Entity handles: LLM-facing invokers exchange entities by opaque handle instead of serialized field data, so agents can chain tools without seeing or fabricating internal structure.
• Refinable definitions: a tool can tighten its own schema at runtime - narrow allowed values, preset inputs - so consumers see a restricted variant instead of the tool's full capability.
• Results with messages: success or failure plus a safe, human-readable message for the caller.
• Forms and config schema generated from input definitions.
• Events for altering definitions and transforming values at the invoker boundary.

Why Tool API?

Drupal's Actions API is useful but limited:

• Input is loosely defined; outputs do not exist.
• Inputs, forms and configuration are defined separately, with nothing binding them together.
• Extending Actions for new use cases - AI integration, automation engines - is difficult.

Tool API addresses this by building inputs, outputs and result messages into the plugin contract, declaring them directly on core's Typed Data API so every tool is self-describing, and generating the schemas, forms and validation from the one definition. Tools can be driven entirely from configuration, entirely from call-time arguments, or a mix of both.

Tool API also owes a debt to the Typed Data API enhancements module, which proved out typed, self-describing logic on Drupal's data model years before AI tool calling existed. Tool API applies those ideas to a new, deliberately small contract that could be adopted to AI and UI consumers alike and move at their pace.

What's in the box

• Tool API - the plugin framework: attribute-based discovery, typed definitions, validation, access, results, events and the entity handle layer.
• Tool Explorer (submodule) - an administrative UI to browse every tool on the site, inspect its schemas and permissions, and execute it from a generated form.
• Tool AI Connector (submodule) - exposes tools to the AI module's function calling, so AI Agents can use them today. In AI 2.0, Tool API works natively with agents.
• Drush - tool:list, tool:search, tool:info and tool:run, plus a drush generate tool scaffold for new tools.

Quick start

Tool API ships the framework; tools come from the ecosystem below or your own modules. With Tool Belt:

composer require drupal/tool drupal/tool_belt
drush en tool_belt_system -y
drush tool:list
drush tool:run tool_belt:system_status

Then visit the Tool Explorer at /admin/config/tool/explorer to browse and execute tools from the UI, or read Creating a tool to write your first one.

Get tools: the ecosystem

Tool API deliberately ships no tools of its own, so collections can grow independently. Current sources of tools:

• Tool Belt - the starter collection for common Drupal core operations: content and entity CRUD, fields and bundles, users, moderation, translations, workspaces, image styles and system tasks. Every tool mirrors the administrative UI and checks the same permissions the equivalent admin screen would.
• Tool Shop (early development) - the developer-only companion: raw configuration and state, queues, cache and router rebuilds, module installation and log access. Operations that mirror code, CLI or database access rather than an admin screen, triple-gated for safety: a require --dev dependency, a settings.php switch, and restricted permissions.
• Canvas Tools - build Drupal Canvas pages, page templates and content templates through typed operations: drafts first, published only on request, with the same access as the Canvas editor.
• MCP Tools - a large catalog of site building and administration tools together with its own MCP transports; its tools also work as plain Tool API plugins for any other consumer.
• MCP Client - connect to external MCP servers and make the world's MCP tools available inside Drupal.
• Your module - tools are small attribute-discovered plugins. We encourage maintainers to ship tools with their own modules and to share collections that work well together.

Use tools everywhere

These modules consume tools registered through the Tool API:

• AI Agents - install the Tool AI Connector submodule and every tool is available to agents. In AI 2.0, Tool API works with agents natively.
• MCP Server with the MCP Server Tool Bridge - expose any tool on your site to Claude, Cursor or any other MCP client, over STDIO or HTTP with OAuth 2.1, through configuration alone.
• ECA - install ECA Tool Integration and tools become actions in event-driven, no-code workflows.
• FlowDrop - workflow orchestration with a visual builder.
• Maestro - workflow solution; install the maestro_ai_tools submodule.

Status and roadmap

Tool API is in beta on the road to a stable 1.0.0. Current release: 1.0.0-beta10, supporting Drupal 10.5+ and 11 on PHP 8.2+.

The beta10 series finished re-parenting definitions onto core's Typed Data API and settled the definition language: explicit list and map definitions (the multiple shorthand is now deprecated), uniform empty-value semantics, constraint validation on nested structures, and coerced output wire formats. Each release ships detailed notes with upgrade guidance.

Heading to rc1:

• Declared permissions on tool definitions, so pickers and tool listings can filter by account without instantiating tools (#3583064, in review).
• Removal of the deprecated multiple shorthand in favor of explicit list definitions (#3583050).
• Continued hardening of validation and schema agreement across invokers (#3583061).

APIs may still change between betas; breaking changes are called out in each release note.

Documentation

• Documentation index - installation, configuration and usage.
• Creating a tool and input and output definitions.
• Entity handles and events.

Supporting this module

Creation of this module and my work toward the AI initiative have been split between donating my own time and supporting organizations. If you are interested in supporting my efforts, please reach out through direct message or Drupal Slack.