chore: auto-document Tools

Author: phil65

docs/configuration/toolsets/agent-management.md

@@ -19,12 +19,13 @@ agents:
 
 ## Available Tools
 
-| Tool | Description |
-|------|-------------|
-| `create_worker_agent` | Create a new worker agent |
-| `add_agent` | Add an agent to the pool |
-| `add_team` | Create a new team |
-| `connect_nodes` | Connect agents in the pool |
+```python exec="true"
+from agentpool_toolsets.builtin import AgentManagementTools
+from agentpool.docs.utils import generate_tool_docs
+
+toolset = AgentManagementTools()
+print(generate_tool_docs(toolset))
+```
 
 ## Tool Selection
 

docs/configuration/toolsets/code.md

@@ -17,6 +17,16 @@ agents:
       - type: code
 ```
 
+## Available Tools
+
+```python exec="true"
+from agentpool_toolsets.builtin.code import CodeTools
+from agentpool.docs.utils import generate_tool_docs
+
+toolset = CodeTools()
+print(generate_tool_docs(toolset))
+```
+
 ## Configuration Reference
 
 /// mknodes

docs/configuration/toolsets/execution.md

@@ -55,14 +55,13 @@ Execute on remote machines via SSH or other protocols.
 
 ## Available Tools
 
-| Tool | Description |
-|------|-------------|
-| `execute_code` | Execute code in a specific language |
-| `execute_command` | Run shell commands |
-| `start_process` | Start a background process |
-| `get_process_output` | Get output from a running process |
-| `wait_for_process` | Wait for process completion |
-| `kill_process` | Terminate a running process |
+```python exec="true"
+from agentpool_toolsets.builtin.execution_environment import ExecutionEnvironmentTools
+from agentpool.docs.utils import generate_tool_docs
+
+toolset = ExecutionEnvironmentTools()
+print(generate_tool_docs(toolset))
+```
 
 ## Tool Selection
 

docs/configuration/toolsets/file-access.md

@@ -61,18 +61,13 @@ toolsets:
 
 ## Available Tools
 
-The toolset provides these tools to agents:
-
-| Tool | Description |
-|------|-------------|
-| `list_directory` | List files with glob patterns and filtering |
-| `read_file` | Read file contents (text or binary/images) |
-| `write_file` | Write content to files |
-| `edit_file` | Smart find-and-replace editing |
-| `delete_path` | Delete files or directories |
-| `grep` | Search file contents with regex |
-| `agentic_edit` | AI-powered file editing |
-| `download_file` | Download files from URLs |
+```python exec="true"
+from agentpool_toolsets.fsspec_toolset import FSSpecTools
+from agentpool.docs.utils import generate_tool_docs
+
+toolset = FSSpecTools()
+print(generate_tool_docs(toolset))
+```
 
 ## Configuration Reference
 

docs/configuration/toolsets/subagent.md

@@ -19,11 +19,13 @@ agents:
 
 ## Available Tools
 
-| Tool | Description |
-|------|-------------|
-| `list_available_nodes` | List agents available for delegation |
-| `delegate_to` | Delegate a task to another agent |
-| `ask_agent` | Ask another agent a question |
+```python exec="true"
+from agentpool_toolsets.builtin.subagent_tools import SubagentTools
+from agentpool.docs.utils import generate_tool_docs
+
+toolset = SubagentTools()
+print(generate_tool_docs(toolset))
+```
 
 ## Configuration Reference
 

docs/configuration/toolsets/user-interaction.md

@@ -19,11 +19,13 @@ agents:
 
 ## Available Tools
 
-| Tool | Description |
-|------|-------------|
-| `ask_user` | Ask the user a question |
-| `show_message` | Display a message to the user |
-| `confirm` | Request user confirmation |
+```python exec="true"
+from agentpool_toolsets.builtin import UserInteractionTools
+from agentpool.docs.utils import generate_tool_docs
+
+toolset = UserInteractionTools()
+print(generate_tool_docs(toolset))
+```
 
 ## Configuration Reference
 

docs/configuration/toolsets/vfs.md

@@ -32,11 +32,13 @@ agents:
 
 ## Available Tools
 
-| Tool | Description |
-|------|-------------|
-| `vfs_list` | List contents of a resource path |
-| `vfs_read` | Read content from a resource |
-| `vfs_info` | Get information about configured resources |
+```python exec="true"
+from agentpool_toolsets.vfs_toolset import VFSTools
+from agentpool.docs.utils import generate_tool_docs
+
+toolset = VFSTools()
+print(generate_tool_docs(toolset))
+```
 
 ## Usage Examples
 

src/agentpool/docs/utils.py

@@ -232,6 +232,41 @@ def check_docs_for_union(
     return missing_docs, extra_docs
 
 
+def _strip_docstring_sections(description: str) -> str:
+    """Strip Args/Returns/Raises sections from a docstring, keeping only the summary.
+
+    Args:
+        description: The full docstring
+
+    Returns:
+        Just the summary/description part without parameter documentation
+    """
+    lines = description.split("\n")
+    result = []
+    in_section = False
+
+    for line in lines:
+        stripped = line.strip()
+        # Check if we're entering a standard docstring section
+        if stripped in ("Args:", "Arguments:", "Returns:", "Raises:", "Yields:", "Note:"):
+            in_section = True
+            continue
+        # Check if we're in a section (indented content after section header)
+        if in_section:
+            # If line is empty or still indented, skip it
+            if not stripped or line.startswith("    ") or line.startswith("\t"):
+                continue
+            # Non-indented non-empty line means new content
+            in_section = False
+        result.append(line)
+
+    # Clean up trailing empty lines
+    while result and not result[-1].strip():
+        result.pop()
+
+    return "\n".join(result)
+
+
 def tool_to_markdown(tool: Tool) -> str:
     """Generate markdown documentation for a single tool.
 
@@ -244,8 +279,11 @@ def tool_to_markdown(tool: Tool) -> str:
     lines = [f"### `{tool.name}`", ""]
 
     if tool.description:
-        lines.append(tool.description)
-        lines.append("")
+        # Strip Args/Returns sections since we have a parameters table
+        desc = _strip_docstring_sections(tool.description)
+        if desc:
+            lines.append(desc)
+            lines.append("")
 
     # Get parameters from schema
     schema = tool.schema["function"]