Tool plugin SDK: how defineToolPlugin changes OpenClaw extensions
Tool plugin SDK support in OpenClaw 2026.5.18 gives extension authors a cleaner way to package simple agent tools: define the tool contract, build it, validate it, and ship it with manifest metadata that operators can inspect. The release adds defineToolPlugin plus openclaw plugins build, openclaw plugins validate, and openclaw plugins init for typed simple tool plugins.
That sounds like developer plumbing. It is, but it matters. Agent tools are not ordinary helper functions. They can read files, call APIs, send messages, trigger browser actions, or touch local infrastructure. If the contract is vague, the agent guesses. If the package is hard to inspect, the operator delays installing it.
Table of contents
- What changed in 2026.5.18
- Why a tool plugin SDK matters
- Tool plugin vs skill vs MCP server
- A practical extension checklist
- Where this helps self-hosted agents
- FAQ
What changed in 2026.5.18
The 2026.5.18 release notes describe the new extension path directly: CLI/plugins added defineToolPlugin plus openclaw plugins build, validate, and init for typed simple tool plugins with generated manifest metadata, optional tool declarations, and context factories.
The important part is not the existence of one more helper. It is the shape of the workflow:
| Step | What the author does | What the operator gains |
|---|---|---|
| Initialize | Start from a plugin scaffold instead of a blank package | fewer one-off layouts to audit |
| Define | Declare tool names, descriptions, inputs, and execution context | clearer agent-facing contracts |
| Build | Generate packaged output and manifest metadata | repeatable artifacts |
| Validate | Check the plugin before it enters an install path | earlier failure, less runtime surprise |
| Install | Add a narrow extension instead of changing core | smaller blast radius |
This fits the direction OpenClaw has been taking across recent releases. The 2026.5.12 provider split moved heavy provider and channel dependency cones out of the core runtime. The 2026.5.18 plugin SDK work applies the same idea to developer extensions: keep the core lean, make optional power explicit, and give operators something concrete to review.
For broader context, see the OpenClaw architecture overview and the recent post on agent provider plugins.
Why a tool plugin SDK matters
A tool plugin SDK matters because agent integrations fail in three places: unclear inputs, unclear permissions, and unclear packaging.
Input clarity is the first problem. Tool descriptions and schemas are part of the prompt surface. A model decides whether to call a tool partly from the name, description, and argument shape it sees. If a tool says “sync data” but accepts six loosely typed strings, the model has to infer too much. A typed contract narrows that ambiguity.
Permission clarity is the second problem. A local agent has access to a different risk profile than a hosted chatbot. It may run near private files, API keys, browser sessions, or chat channels. A plugin should make its operating surface visible before a human trusts it. Generated metadata is not a security policy by itself, but it gives the review process something stable to inspect.
Packaging clarity is the third problem. The npm documentation defines a package as a directory or tarball described by package.json. That sounds basic, but it is exactly where agent extensions get messy. A plugin is not just code; it is an installable artifact with a contract, dependencies, build output, and operational expectations.
The OpenClaw plugin SDK does not remove the need to review code. It removes some avoidable ambiguity around how simple tools are declared and shipped.
Tool plugin vs skill vs MCP server
OpenClaw now has several extension shapes. They overlap, but they should not be used for the same job.
| Extension type | Best for | Avoid when |
|---|---|---|
| Skill | Procedures, operating playbooks, writing patterns, review checklists | the agent needs a callable API action |
| Tool plugin | A narrow executable capability inside OpenClaw, with typed inputs and runtime context | the integration needs to serve many different MCP clients |
| MCP server | A protocol-level bridge that exposes tools/resources/prompts to MCP-compatible clients | the tool is only useful inside one OpenClaw runtime |
| Provider or channel plugin | Model backends, chat adapters, voice/media providers, and larger runtime surfaces | the extension is just one small action |
MCP is useful because it gives agents a common way to call external systems. The official TypeScript SDK for Model Context Protocol exists for servers and clients, and the ecosystem has moved toward explicit tool schemas. Speakeasy’s MCP write-up makes the same point from an API-platform angle: generated Zod schemas can give the agent an accurate request format, and each method becomes a discrete tool.
OpenClaw tool plugins sit closer to the runtime. They are the right fit when the operator wants a capability installed into OpenClaw itself, with OpenClaw’s config, execution context, channel policies, and plugin lifecycle around it.
If you are deciding between a skill and a plugin, use this rule: if the agent needs instructions, write a skill; if the agent needs to execute a capability, write a tool plugin. The existing guide on custom OpenClaw skills covers the first case. The 2026.5.18 SDK work is about the second.
A practical extension checklist
A simple tool plugin should be boring to review. That is a feature.
Before building one, write down five things:
- The smallest useful action. One tool that does one thing well is easier to route than a broad tool with mode flags.
- The input schema. Use narrow field names, enums where possible, and required fields only when the agent truly must provide them.
- The side effects. Say whether the tool reads, writes, sends, deletes, purchases, posts, or mutates state.
- The context it needs. Separate user-provided arguments from runtime context such as auth, workspace path, channel identity, or configured account.
- The failure messages. A good tool should fail with text the agent can act on, not an exception blob.
That last point is easy to underrate. Agent tools do not only serve developers. They serve the model loop. If a tool fails with “403”, the next step may be random. If it fails with “Slack account not configured for this workspace; run plugin setup first”, the agent has a recovery path.
Zod is relevant here because schema validation is not just a TypeScript nicety. Zod describes itself as a TypeScript-first validation library with static type inference and JSON Schema conversion. For agent tools, that combination is practical: humans get typed code, and runtimes get structured input contracts.
Where this helps self-hosted agents
The strongest use case is a self-hosted agent stack with local needs that will never become a universal SaaS integration.
Examples include:
- a private inventory lookup for a small ecommerce operator;
- a local media processing wrapper around an existing CLI;
- a team-specific deployment check that reads internal status endpoints;
- a finance export tool that writes a CSV into a controlled folder;
- a channel-specific moderation helper for Discord, Telegram, or Slack.
Those tools are often too specific for a marketplace, but too important to leave as untyped shell snippets. A tool plugin gives them a home. It lets the operator keep the core runtime clean while still giving the agent a real capability.
This is also where OpenClaw’s self-hosted positioning matters. A hosted agent platform can offer many integrations, but it usually cannot know your local machine, private LAN, SSH jump host, personal media folder, or weird internal process. A self-hosted runtime can, if the extension boundary is explicit enough to trust.
Start with the OpenClaw overview if you are new to the project, then compare the self-hosted model against other agent tools on OpenClaw vs alternatives. The plugin question is mostly an ownership question: who controls what the agent can do, and how clearly can they inspect it before it runs?
FAQ
Is a tool plugin the same as an MCP server?
No. An MCP server exposes tools through the Model Context Protocol so MCP-compatible clients can call them. An OpenClaw tool plugin installs a capability into OpenClaw’s own plugin/runtime system. Use MCP when you want a protocol bridge. Use a tool plugin when the capability belongs inside an OpenClaw deployment.
Does defineToolPlugin make plugins safe automatically?
No. Typed declarations and generated metadata help review, but they do not replace code review, permission boundaries, or runtime policy. Treat the SDK as a sharper packaging and validation path, not a security guarantee.
When should I write a skill instead of a plugin?
Write a skill when the agent needs reusable instructions: how to review a pull request, run a release checklist, or write a specific kind of content. Write a plugin when the agent needs a callable capability with inputs, outputs, and side effects.
What should the first tool plugin do?
Pick one low-risk, high-friction task. Good candidates read from a known API, generate a report, normalize a file, or check a status endpoint. Avoid destructive actions until the tool contract, auth, and failure behavior are boring.
Sources: OpenClaw 2026.5.18 release notes, Model Context Protocol TypeScript SDK, Zod documentation, npm packages and modules, Speakeasy on MCP TypeScript SDKs