From da4153ac5c8dd321df7c8d0939adc1901c22b2ba Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Fri, 14 Aug 2026 22:01:12 -0700
Subject: [PATCH] docs: document provides_tools client-tool registration for
 platform plugins

Follow-up docs for PR #86660 (#81163/#78050): platform-adapter developer
guide gains a `provides_tools` section (deferred adapters vs eager client
tools, tools.py convention, per-platform enablement incl. plugin platform
names as --platform targets); a2a user guide shows the concrete enable
commands including the inbound-task chaining case.
---
 .../adding-platform-adapters.md               | 28 +++++++++++++++++++
 website/docs/user-guide/messaging/a2a.md      | 10 ++++++-
 2 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/website/docs/developer-guide/adding-platform-adapters.md b/website/docs/developer-guide/adding-platform-adapters.md
index 2847ba974b53d..870c6608dd034 100644
--- a/website/docs/developer-guide/adding-platform-adapters.md
+++ b/website/docs/developer-guide/adding-platform-adapters.md
@@ -61,6 +61,34 @@ optional_env:
     password: false
 ```
 
+#### Outbound client tools: `provides_tools`
+
+`kind: platform` plugins are **deferred**: the adapter module (and its SDK
+imports) only load when a gateway, cron, or `send_message` path first asks the
+platform registry for the platform. If your plugin also ships outbound *client
+tools* the agent should be able to call from any session (the bundled `a2a`
+plugin's `a2a_call` / `a2a_discover` etc.), put them in a dedicated `tools.py`
+with a `register_tools(ctx)` function and declare them in the manifest:
+
+```yaml
+provides_tools:
+  - my_platform_call
+  - my_platform_list
+```
+
+With `provides_tools` declared, Hermes imports only `tools.py` during plugin
+discovery and registers the client tools in every process — CLI and TUI
+included — while the adapter stays deferred. Keep the package `__init__.py`
+import-light and pull the adapter in from inside `register()` so the eager
+import stays cheap. Without the field, nothing changes: the whole plugin stays
+deferred.
+
+Users enable the toolset per platform like any other, e.g.
+`hermes tools enable my_platform --platform cli`, or by listing the toolset
+key under `platform_toolsets` in `config.yaml`. Plugin platform names are
+also valid `--platform` targets, so an inbound session on your platform can
+be granted its own outbound tools.
+
 ### adapter.py
 
 ```python
diff --git a/website/docs/user-guide/messaging/a2a.md b/website/docs/user-guide/messaging/a2a.md
index 71aecfaa0ae3a..92d98d19d9408 100644
--- a/website/docs/user-guide/messaging/a2a.md
+++ b/website/docs/user-guide/messaging/a2a.md
@@ -29,7 +29,15 @@ gateway:
         port: 9900
 ```
 
-The outbound client tools ship as the `a2a` toolset, **off by default** — enable it with `hermes tools`.
+The outbound client tools ship as the `a2a` toolset, **off by default** — enable it per platform:
+
+```bash
+hermes tools enable a2a --platform cli        # CLI/TUI sessions
+hermes tools enable a2a --platform telegram   # or any messaging platform
+hermes tools enable a2a --platform a2a        # let inbound A2A tasks call peers (agent chaining)
+```
+
+The tools are available in every process type — CLI, TUI, gateway, and cron — without the inbound platform needing to be enabled.
 
 ## Outbound: calling other agents