AI Tools Overview

Last updated: June 5, 2026

AI tools should be exposed as WordPress Ability projections whenever a single registered ability already owns the execution contract. inc/Engine/AI/Tools/ToolServiceProvider.php still instantiates tool classes so they can register configuration handlers and ability projections, but the model-facing declaration should use datamachine_register_ability_tool() instead of a class/method handler when possible.

The legacy datamachine_tools class/method registry remains for composite orchestration tools and adjacent handler tools that do not map cleanly to one public ability. Tools declare where they can run (chat, pipeline, or pipeline-policy mode) and the ability or access level required to execute them.

Registered Tool Inventory

Mutation risk means what the tool can change when called successfully:

Read-only: reads data or runs diagnostics without changing site content/config.
Low mutation: writes agent memory, logs, queues, generated media, or external notifications.
Config mutation: changes pipeline, flow, handler, schedule, auth, or default configuration.
Content mutation: creates, updates, assigns, merges, or deletes WordPress content/taxonomy/files.
Destructive: deletes durable workflow objects, files, logs, jobs, or terms.

Chat And Pipeline Tools

Tool	Modes	Mutation risk	Purpose	Docs
`image_generation`	chat, pipeline	Low mutation	Create image-generation jobs and sideload generated media.	Image Generation
`internal_link_audit`	chat, pipeline	Low mutation	Audit internal links, backlinks, orphans, and broken URLs.	Internal Link Audit
`local_search`	chat, pipeline	Read-only	Search local WordPress posts/pages.	Local Search
`web_fetch`	chat, pipeline	Read-only	Fetch readable content from a URL.	Web Fetch
`wordpress_post_reader`	chat, pipeline	Read-only	Read a WordPress post by permalink URL.	WordPress Post Reader

Chat And Pipeline-Policy Tools

Pipeline-policy tools are available while resolving pipeline tool policy, not as regular adjacent handler tools.

Tool	Modes	Mutation risk	Purpose	Docs
`agent_daily_memory`	chat, pipeline policy	Low mutation	Read, write, list, and search daily memory journal files.	Agent Daily Memory
`agent_memory`	chat, pipeline policy	Low mutation	Read and update agent markdown files by section.	Agent Memory

Chat-Only Read And Diagnostics Tools

Tool	Mutation risk	Purpose	Docs
`api_query`	Read-only	Query documented Data Machine REST endpoints with mutation operations restricted.	API Query
`get_handler_defaults`	Read-only	Read site-wide handler defaults for one handler or all handlers.	Get Handler Defaults
`list_flows`	Read-only	List flows with pipeline, handler, and pagination filters.	List Flows
`read_logs`	Read-only	Read Data Machine logs with agent/job/pipeline/flow filters.	Read Logs
`search_taxonomy_terms`	Read-only	Search taxonomy terms before create/update/assign operations.	Search Taxonomy Terms
`system_health_check`	Read-only	Run unified Data Machine and extension diagnostics.	System Health Check

Chat-Only Workflow Configuration Tools

Tool	Mutation risk	Purpose	Docs
`add_pipeline_step`	Config mutation	Add a step to a pipeline and sync flows.	Add Pipeline Step
`authenticate_handler`	Config mutation	Manage handler credentials and OAuth status.	Authenticate Handler
`configure_flow_steps`	Config mutation	Configure handler settings and AI user messages for one or many flow steps.	Configure Flow Steps
`configure_pipeline_step`	Config mutation	Configure pipeline-level AI system prompt and tool policy.	Configure Pipeline Step
`copy_flow`	Config mutation	Duplicate a flow within or across compatible pipelines.	Copy Flow
`create_flow`	Config mutation	Create one or more flows with optional schedules and step configs.	Create Flow
`create_pipeline`	Config mutation	Create one or more pipelines and their initial flow.	Create Pipeline
`manage_queue`	Config mutation	Add/list/clear/remove/update/move prompt queue items and set queue mode.	Manage Queue
`reorder_pipeline_steps`	Config mutation	Reorder pipeline steps.	Reorder Pipeline Steps
`run_flow`	Low mutation	Run a flow now or schedule a future run.	Run Flow
`set_handler_defaults`	Config mutation	Update site-wide defaults for handler configs.	Set Handler Defaults
`update_flow`	Config mutation	Update flow title and/or schedule.	Update Flow

Chat-Only Content And File Mutation Tools

Tool	Mutation risk	Purpose	Docs
`assign_taxonomy_term`	Content mutation	Assign a term to one or more posts.	Assign Taxonomy Term
`create_taxonomy_term`	Content mutation	Create a taxonomy term if it does not exist.	Create Taxonomy Term
`delete_file`	Destructive	Delete an uploaded file scoped to a flow step.	Delete File
`merge_taxonomy_terms`	Destructive	Reassign posts from a source term to a target term and delete the source term.	Merge Taxonomy Terms
`update_taxonomy_term`	Content mutation	Update taxonomy term fields and meta.	Update Taxonomy Term

Chat-Only Destructive Workflow Tools

Tool	Mutation risk	Purpose	Docs
`delete_flow`	Destructive	Delete a flow.	Delete Flow
`delete_pipeline`	Destructive	Delete a pipeline and its associated flows.	Delete Pipeline
`delete_pipeline_step`	Destructive	Remove a pipeline step and cascade to flows.	Delete Pipeline Step
`manage_jobs`	Destructive	List/summarize jobs and delete, fail, retry, or recover jobs.	Manage Jobs
`manage_logs`	Destructive	Clear logs or read log metadata.	Manage Logs

Chat-Only External Execution Tools

Tool	Mutation risk	Purpose	Docs
`execute_workflow`	Content mutation	Execute an ephemeral workflow through the Execute API.	Execute Workflow
`send_ping`	Low mutation	POST a prompt/context payload to one or more webhook URLs.	Send Ping

Chat-Only Duplicate Prevention Tool

Tool	Mutation risk	Purpose	Docs
`queue_validator`	Read-only	Check if a topic exists in published content or a flow queue.	Queue Validator

Handler-Specific Tools

Handler tools are registered by handlers into the unified datamachine_tools registry as deferred _handler_callable entries. They become available at runtime when an adjacent step uses the matching handler or step type.

Examples include:

wordpress_publish: create WordPress posts; accepts content_format (markdown, html, or blocks).
wordpress_update: update existing WordPress content.
twitter_publish, bluesky_publish, facebook_publish, threads_publish: publish social posts.
google_sheets_publish: append rows to Google Sheets.

Extension-Owned Tools

GitHub and workspace tools are not registered by Data Machine core. They are provided by the data-machine-code extension when that extension is installed.

Common extension tools include:

create_github_issue, list_github_issues, get_github_issue, manage_github_issue
list_github_pulls, list_github_repos
workspace_path, workspace_list, workspace_show, workspace_ls, workspace_read

Unregistered Core Class

inc/Api/Chat/Tools/GetProblemFlows.php defines get_problem_flows, but ToolServiceProvider.php does not instantiate it. It is not part of the registered core inventory until the provider registers it or another bootstrap path instantiates the class.

Tool Architecture

Ability-native projections are the preferred model-tool path:

Register the underlying WordPress ability with wp_register_ability().
Expose it to model runs with datamachine_register_ability_tool() or the datamachine_ability_tool_projections filter.
Put model-facing overrides such as description, modes, parameters, requires_config, and action-policy metadata on the projection declaration.

Class/method tool declarations are still explicit exceptions:

agent_memory and agent_daily_memory compose several file/memory abilities behind one action router and resolve agent/user scope before dispatch.
internal_link_audit composes several internal-link abilities behind one action router and strips internal response keys.
queue_validator contains duplicate-prevention orchestration across published posts and queue state that is reused by queue-add behavior.
web_fetch has no registered WordPress ability yet; it remains a class/method tool until a first-class fetch ability exists.
Chat-only workflow/admin tools in inc/Api/Chat/Tools/ remain Data Machine product tools until each one has a public ability contract worth projecting.
Adjacent handler tools remain runtime-generated class/method declarations because their schemas depend on neighboring pipeline handler configuration.

Legacy tool classes extend BaseTool and register themselves with registerTool(). Registration declares:

tool slug
definition callback
mode list
required ability or access level

ToolPolicyResolver resolves the active tool set for a context. ToolExecutor handles execution. Handler-specific tools are resolved from _handler_callable registry entries against adjacent step runtime configuration.

Content Authoring Formats

For normal prose, AI tools should write markdown and omit content_format unless a workflow explicitly asks for HTML or serialized blocks. Raw ability/API callers can still pass content_format; omitted raw datamachine/upsert-post calls keep the legacy block-markup default.

Directory Reference

Directory	Contents
`inc/Engine/AI/Tools/Global/`	Chat/pipeline global tools such as search, analytics, memory, image generation, and audits.
`inc/Api/Chat/Tools/`	Chat-only admin/workflow/content tools.
`inc/Engine/AI/Tools/`	Tool registration, policy resolution, execution, and shared base classes.
`inc/Abilities/Analytics/`	Analytics ability implementations used by analytics tools.

View on GitHub