fix(hermes): expose Agency tool parameters (#717)

Co-authored-by: Michael Sitarzewski <michael@sitarzewski.com>

scripts/build-hermes-plugin.py

@@ -225,13 +225,17 @@ SEARCH_DESCRIPTION = (
     "Swami specialist, role, discipline, or wants help choosing the right agent."
 )
 SEARCH_SCHEMA = {
-    "type": "object",
-    "properties": {
-        "query": {"type": "string", "description": "Natural-language search query."},
-        "division": {"type": "string", "description": "Optional division filter, e.g. engineering, marketing, testing."},
-        "limit": {"type": "integer", "description": "Maximum results, default 8, max 25."},
+    "name": "agency_agents_search",
+    "description": SEARCH_DESCRIPTION,
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string", "description": "Natural-language search query."},
+            "division": {"type": "string", "description": "Optional division filter, e.g. engineering, marketing, testing."},
+            "limit": {"type": "integer", "description": "Maximum results, default 8, max 25."},
+        },
+        "required": ["query"],
     },
-    "required": ["query"],
 }
 
 READ_DESCRIPTION = (
@@ -239,13 +243,17 @@ READ_DESCRIPTION = (
     "and includes the full specialist instructions only when include_body is true."
 )
 READ_SCHEMA = {
-    "type": "object",
-    "properties": {
-        "agent": {"type": "string", "description": "Agent slug or exact display name."},
-        "slug": {"type": "string", "description": "Alias for agent. Pass the slug from agency_agents_search results."},
-        "include_body": {"type": "boolean", "description": "Include full specialist instructions."},
+    "name": "agency_agents_inspect",
+    "description": READ_DESCRIPTION,
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "agent": {"type": "string", "description": "Agent slug or exact display name."},
+            "slug": {"type": "string", "description": "Alias for agent. Pass the slug from agency_agents_search results."},
+            "include_body": {"type": "boolean", "description": "Include full specialist instructions."},
+        },
+        "required": [],
     },
-    "required": [],
 }
 
 PROMPT_DESCRIPTION = (
@@ -253,13 +261,17 @@ PROMPT_DESCRIPTION = (
     "Use after agency_agents_search when you need one specialist's full context."
 )
 PROMPT_SCHEMA = {
-    "type": "object",
-    "properties": {
-        "agent": {"type": "string", "description": "Agent slug or exact display name."},
-        "slug": {"type": "string", "description": "Alias for agent. Pass the slug from agency_agents_search results."},
-        "task": {"type": "string", "description": "The user's task to pair with the specialist context."},
+    "name": "agency_agents_load",
+    "description": PROMPT_DESCRIPTION,
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "agent": {"type": "string", "description": "Agent slug or exact display name."},
+            "slug": {"type": "string", "description": "Alias for agent. Pass the slug from agency_agents_search results."},
+            "task": {"type": "string", "description": "The user's task to pair with the specialist context."},
+        },
+        "required": [],
     },
-    "required": [],
 }
 
 DELEGATE_DESCRIPTION = (
@@ -268,18 +280,22 @@ DELEGATE_DESCRIPTION = (
     "specialist prompt if delegation is unavailable."
 )
 DELEGATE_SCHEMA = {
-    "type": "object",
-    "properties": {
-        "agent": {"type": "string", "description": "Agent slug or exact display name."},
-        "slug": {"type": "string", "description": "Alias for agent. Pass the slug from agency_agents_search results."},
-        "task": {"type": "string", "description": "Concrete task for the specialist."},
-        "toolsets": {
-            "type": "array",
-            "items": {"type": "string"},
-            "description": "Optional Hermes toolsets for the delegated worker, e.g. ['terminal','file'].",
+    "name": "agency_agents_delegate",
+    "description": DELEGATE_DESCRIPTION,
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "agent": {"type": "string", "description": "Agent slug or exact display name."},
+            "slug": {"type": "string", "description": "Alias for agent. Pass the slug from agency_agents_search results."},
+            "task": {"type": "string", "description": "Concrete task for the specialist."},
+            "toolsets": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Optional Hermes toolsets for the delegated worker, e.g. ['terminal','file'].",
+            },
         },
+        "required": ["task"],
     },
-    "required": ["task"],
 }
 
 
@@ -402,7 +418,7 @@ def readme(agent_count: int) -> str:
         Generated by `scripts/convert.sh --tool hermes`.
 
         This integration installs one Hermes plugin named `{PLUGIN_NAME}` instead
-        of adding 232+ generated skills to `skills.external_dirs`. Hermes sees a
+        of adding hundreds of generated skills to `skills.external_dirs`. Hermes sees a
         small fixed tool surface at startup, while the complete Agency roster is
         stored on disk in `data/agents.json` and searched/loaded lazily.
 
@@ -415,6 +431,20 @@ def readme(agent_count: int) -> str:
         - `agency_agents_load` — compose one specialist prompt for the current task.
         - `agency_agents_delegate` — delegate through Hermes `delegate_task` when available.
 
+        Each tool is registered with Hermes' complete function-tool schema, including
+        its name, description, and JSON `parameters`. The available arguments are:
+
+        | Tool | Arguments |
+        | --- | --- |
+        | `agency_agents_search` | `query` (required), optional `division` and `limit` |
+        | `agency_agents_inspect` | `agent` or `slug`, optional `include_body` |
+        | `agency_agents_load` | `agent` or `slug`, optional `task` |
+        | `agency_agents_delegate` | `agent` or `slug`, `task` (required), optional `toolsets` |
+
+        A normal flow is: search by capability, take a returned `slug`, then inspect,
+        load, or delegate to that specialist. You can ask Hermes to do this in natural
+        language; direct tool calls are not required.
+
         ## Specialist usage instruction for Hermes
 
         When a Hermes project needs Agency specialists, explicitly ask Hermes to use
@@ -457,6 +487,11 @@ def readme(agent_count: int) -> str:
 
         It then enables `{PLUGIN_NAME}` under `plugins.enabled` in the Hermes
         config. It does **not** write to `skills.external_dirs`.
+
+        Restart Hermes or start a new session after installing so the plugin and its
+        tool schemas are loaded. If Hermes displays these tools without their documented
+        arguments, regenerate and reinstall the plugin from the latest Agency Agents
+        checkout, then restart Hermes.
         """
     ).lstrip()