v0.1.12 - Add /tool -h help shorthand and enrich core tool parameter descriptions

docs/TOOLS.md

@@ -181,6 +181,537 @@ These tools manage the agent's short-term and long-term memory, persisted on Nos
 
 ---
 
+## Tool Execution Examples
+
+These examples show the JSON structure for tool calls.
+
+### Nostr Event & Messaging
+
+**nostr_post**
+```json
+{
+  "name": "nostr_post",
+  "arguments": {
+    "kind": 1,
+    "content": "Hello from Didactyl!",
+    "tags": [["t", "didactyl"]]
+  }
+}
+```
+
+**nostr_delete**
+```json
+{
+  "name": "nostr_delete",
+  "arguments": {
+    "event_ids": ["<event_id_hex>"],
+    "reason": "Mistake"
+  }
+}
+```
+
+**nostr_react**
+```json
+{
+  "name": "nostr_react",
+  "arguments": {
+    "event_id": "<event_id_hex>",
+    "event_pubkey": "<pubkey_hex>",
+    "reaction": "🤙"
+  }
+}
+```
+
+**nostr_query**
+```json
+{
+  "name": "nostr_query",
+  "arguments": {
+    "filter": {
+      "kinds": [1],
+      "limit": 5
+    },
+    "timeout_ms": 5000
+  }
+}
+```
+
+**nostr_my_events**
+```json
+{
+  "name": "nostr_my_events",
+  "arguments": {
+    "kind": 1,
+    "limit": 10
+  }
+}
+```
+
+**nostr_dm_send**
+```json
+{
+  "name": "nostr_dm_send",
+  "arguments": {
+    "recipient_pubkey": "<pubkey_hex>",
+    "message": "Secret message"
+  }
+}
+```
+
+**nostr_dm_send_nip17**
+```json
+{
+  "name": "nostr_dm_send_nip17",
+  "arguments": {
+    "recipient_pubkey": "<pubkey_hex>",
+    "message": "Private message via NIP-17",
+    "subject": "Confidential"
+  }
+}
+```
+
+### Nostr Identity & Utility
+
+**nostr_profile_get**
+```json
+{
+  "name": "nostr_profile_get",
+  "arguments": {
+    "pubkey": "<pubkey_hex>"
+  }
+}
+```
+
+**nostr_nip05_lookup**
+```json
+{
+  "name": "nostr_nip05_lookup",
+  "arguments": {
+    "identifier": "user@domain.com"
+  }
+}
+```
+
+**nostr_encode**
+```json
+{
+  "name": "nostr_encode",
+  "arguments": {
+    "type": "npub",
+    "hex": "<pubkey_hex>"
+  }
+}
+```
+
+**nostr_decode**
+```json
+{
+  "name": "nostr_decode",
+  "arguments": {
+    "uri": "nostr:npub1..."
+  }
+}
+```
+
+**nostr_relay_status**
+```json
+{
+  "name": "nostr_relay_status",
+  "arguments": {}
+}
+```
+
+**nostr_relay_info**
+```json
+{
+  "name": "nostr_relay_info",
+  "arguments": {
+    "relay_url": "wss://relay.damus.io"
+  }
+}
+```
+
+**nostr_subscription_status**
+```json
+{
+  "name": "nostr_subscription_status",
+  "arguments": {}
+}
+```
+
+**nostr_subscription_set**
+```json
+{
+  "name": "nostr_subscription_set",
+  "arguments": {
+    "name": "admin_context_profile",
+    "enabled": true
+  }
+}
+```
+
+**nostr_encrypt**
+```json
+{
+  "name": "nostr_encrypt",
+  "arguments": {
+    "recipient_pubkey": "<pubkey_hex>",
+    "plaintext": "Sensitive data"
+  }
+}
+```
+
+**nostr_decrypt**
+```json
+{
+  "name": "nostr_decrypt",
+  "arguments": {
+    "sender_pubkey": "<pubkey_hex>",
+    "ciphertext": "<nip44_ciphertext>"
+  }
+}
+```
+
+**nostr_list_manage**
+```json
+{
+  "name": "nostr_list_manage",
+  "arguments": {
+    "list_kind": 10000,
+    "action": "add",
+    "items": [["p", "<pubkey_hex>"]]
+  }
+}
+```
+
+**nostr_block_list**
+```json
+{
+  "name": "nostr_block_list",
+  "arguments": {
+    "type": "p"
+  }
+}
+```
+
+**nostr_block_edit**
+```json
+{
+  "name": "nostr_block_edit",
+  "arguments": {
+    "action": "add",
+    "items": [["p", "<pubkey_hex>"]],
+    "public": false
+  }
+}
+```
+
+### Context & Identity
+
+**nostr_pubkey** / **my_pubkey**
+```json
+{
+  "name": "nostr_pubkey",
+  "arguments": {}
+}
+```
+
+**agent_identity**
+```json
+{
+  "name": "agent_identity",
+  "arguments": {}
+}
+```
+
+**admin_identity**
+```json
+{
+  "name": "admin_identity",
+  "arguments": {}
+}
+```
+
+**nostr_admin_profile**
+```json
+{
+  "name": "nostr_admin_profile",
+  "arguments": {}
+}
+```
+
+**nostr_agent_notes** / **my_notes**
+```json
+{
+  "name": "my_notes",
+  "arguments": {}
+}
+```
+
+### Skills & Triggers
+
+**skill_create**
+```json
+{
+  "name": "skill_create",
+  "arguments": {
+    "d": "weather-skill",
+    "content": "I can tell you the weather.",
+    "description": "Fetches weather data",
+    "auto_adopt": true
+  }
+}
+```
+
+**skill_edit**
+```json
+{
+  "name": "skill_edit",
+  "arguments": {
+    "d": "weather-skill",
+    "description": "Updated weather skill description"
+  }
+}
+```
+
+**skill_list**
+```json
+{
+  "name": "skill_list",
+  "arguments": {
+    "adopted": true
+  }
+}
+```
+
+**skill_adopt**
+```json
+{
+  "name": "skill_adopt",
+  "arguments": {
+    "pubkey": "<author_pubkey_hex>",
+    "d": "cool-skill"
+  }
+}
+```
+
+**skill_search**
+```json
+{
+  "name": "skill_search",
+  "arguments": {
+    "query": "bitcoin",
+    "popular": true
+  }
+}
+```
+
+**trigger_list**
+```json
+{
+  "name": "trigger_list",
+  "arguments": {}
+}
+```
+
+### Tasks & Memory
+
+**task_list**
+```json
+{
+  "name": "task_list",
+  "arguments": {}
+}
+```
+
+**task_manage**
+```json
+{
+  "name": "task_manage",
+  "arguments": {
+    "action": "add",
+    "text": "Finish documentation",
+    "status": "active"
+  }
+}
+```
+
+**memory_save**
+```json
+{
+  "name": "memory_save",
+  "arguments": {
+    "content": "User likes coffee."
+  }
+}
+```
+
+**memory_recall**
+```json
+{
+  "name": "memory_recall",
+  "arguments": {}
+}
+```
+
+### LLM & Configuration
+
+**model_get**
+```json
+{
+  "name": "model_get",
+  "arguments": {}
+}
+```
+
+**model_set**
+```json
+{
+  "name": "model_set",
+  "arguments": {
+    "model": "gpt-4o",
+    "temperature": 0.7
+  }
+}
+```
+
+**config_store**
+```json
+{
+  "name": "config_store",
+  "arguments": {
+    "d_tag": "custom_setting",
+    "content": "{\"value\": 42}"
+  }
+}
+```
+
+**config_recall**
+```json
+{
+  "name": "config_recall",
+  "arguments": {
+    "d_tag": "custom_setting"
+  }
+}
+```
+
+### System & Runtime
+
+**agent_version**
+```json
+{
+  "name": "agent_version",
+  "arguments": {}
+}
+```
+
+**local_http_fetch**
+```json
+{
+  "name": "local_http_fetch",
+  "arguments": {
+    "url": "https://api.github.com/zen",
+    "method": "GET"
+  }
+}
+```
+
+**local_shell_exec**
+```json
+{
+  "name": "local_shell_exec",
+  "arguments": {
+    "command": "ls -la"
+  }
+}
+```
+
+**local_file_read**
+```json
+{
+  "name": "local_file_read",
+  "arguments": {
+    "path": "README.md"
+  }
+}
+```
+
+**local_file_write**
+```json
+{
+  "name": "local_file_write",
+  "arguments": {
+    "path": "test.txt",
+    "content": "Hello world",
+    "append": false
+  }
+}
+```
+
+**tool_list**
+```json
+{
+  "name": "tool_list",
+  "arguments": {}
+}
+```
+
+### Cashu Wallet
+
+**cashu_wallet_balance**
+```json
+{
+  "name": "cashu_wallet_balance",
+  "arguments": {}
+}
+```
+
+**cashu_wallet_mint_quote**
+```json
+{
+  "name": "cashu_wallet_mint_quote",
+  "arguments": {
+    "amount": 100,
+    "unit": "sat"
+  }
+}
+```
+
+**cashu_wallet_receive_token**
+```json
+{
+  "name": "cashu_wallet_receive_token",
+  "arguments": {
+    "token": "cashuA..."
+  }
+}
+```
+
+**cashu_wallet_send_token**
+```json
+{
+  "name": "cashu_wallet_send_token",
+  "arguments": {
+    "amount": 21
+  }
+}
+```
+
+**cashu_wallet_mints_set**
+```json
+{
+  "name": "cashu_wallet_mints_set",
+  "arguments": {
+    "target": "both",
+    "wallet_mints": ["https://mint.host.com"],
+    "public_mints": ["https://mint.host.com"]
+  }
+}
+```
+
+---
+
 ## Security Model
 
 Tool access is gated by sender tier: