Merge pull request #1419 from 3clyp50/prompts

prompts: restore tool examples for better model guidance

Author: frdel

plugins/_code_execution/prompts/agent.system.tool.code_exe.md

@@ -6,11 +6,17 @@ args:
 - `session`: terminal session id; default `0`
 - `reset`: kill a session before running; `true` or `false`
 rules:
+- place the command or script in `code`
 - use `runtime=output` to poll running work
 - use `input` for interactive terminal prompts
+- if a session is stuck, call again with the same `session` and `reset=true`
+- check dependencies before running code
+- replace placeholder or demo data with real values before execution
+- use `print()` or `console.log()` when you need explicit output
 - do not interleave other tools while waiting
 - ignore framework `[SYSTEM: ...]` info in output
-example:
+examples:
+1 terminal command
 ~~~json
 {
   "thoughts": ["I should run a terminal command in the default session."],
@@ -24,3 +30,31 @@ example:
   }
 }
 ~~~
+
+2 python snippet
+~~~json
+{
+  "thoughts": ["A short Python check is faster than using the shell."],
+  "headline": "Running Python snippet",
+  "tool_name": "code_execution_tool",
+  "tool_args": {
+    "runtime": "python",
+    "session": 0,
+    "reset": false,
+    "code": "import os\nprint(os.getcwd())"
+  }
+}
+~~~
+
+3 wait for running output
+~~~json
+{
+  "thoughts": ["The previous command is still running, so I should poll for output."],
+  "headline": "Waiting for command output",
+  "tool_name": "code_execution_tool",
+  "tool_args": {
+    "runtime": "output",
+    "session": 0
+  }
+}
+~~~

prompts/agent.system.tool.call_sub.md

@@ -18,3 +18,7 @@ example:
 }
 ~~~
 reuse long subordinate output with `§§include(path)` instead of rewriting it
+{{if agent_profiles}}
+available profiles:
+{{agent_profiles}}
+{{endif}}

prompts/agent.system.tool.document_query.md

@@ -4,5 +4,37 @@ args:
 - `document`: url path or list of them
 - `queries`: optional list of questions
 - `query`: optional single-question alias
-without `query` or `queries` it returns document content
-for local files use full path; for web documents use full urls
+- without `query` or `queries` it returns document content
+- `document` accepts one path/url or a list for cross-document comparison
+- for local files use full paths; for web documents use full urls
+examples:
+1 read a document
+~~~json
+{
+  "thoughts": ["I need the full contents of the report before answering."],
+  "headline": "Loading report contents",
+  "tool_name": "document_query",
+  "tool_args": {
+    "document": "https://example.com/report.pdf"
+  }
+}
+~~~
+
+2 compare documents with questions
+~~~json
+{
+  "thoughts": ["I need targeted answers across two documents."],
+  "headline": "Comparing two documents",
+  "tool_name": "document_query",
+  "tool_args": {
+    "document": [
+      "https://example.com/report-one.pdf",
+      "/path/to/report-two.pdf"
+    ],
+    "queries": [
+      "Compare the main conclusions.",
+      "What changed between the two versions?"
+    ]
+  }
+}
+~~~

prompts/agent.system.tool.scheduler.md

@@ -14,3 +14,14 @@ methods:
 - `scheduler:create_adhoc_task`: `name`, `system_prompt`, `prompt`, optional `attachments[]`, optional `dedicated_context`
 - `scheduler:create_planned_task`: `name`, `system_prompt`, `prompt`, optional `attachments[]`, `plan[]` iso datetimes like `2025-04-29T18:25:00`, optional `dedicated_context`
 - `scheduler:wait_for_task`: `uuid`; works for dedicated-context tasks
+example:
+~~~json
+{
+  "thoughts": ["I should check for an existing task before I create or run anything."],
+  "headline": "Looking up scheduled task",
+  "tool_name": "scheduler:find_task_by_name",
+  "tool_args": {
+    "name": "daily backup"
+  }
+}
+~~~

prompts/agent.system.tool.search_engine.md

@@ -2,3 +2,14 @@
 find live news, prices, and other real-time web data
 arg: `query` (text search query)
 returns urls, titles, and descriptions
+example:
+~~~json
+{
+  "thoughts": ["I need current information rather than relying on memory."],
+  "headline": "Searching the web",
+  "tool_name": "search_engine",
+  "tool_args": {
+    "query": "latest LiteLLM release notes"
+  }
+}
+~~~

prompts/agent.system.tool.skills.md

@@ -1,6 +1,18 @@
 ### skills_tool
 use skills only when relevant
+workflow:
 - `skills_tool:list`: discover available skills
 - `skills_tool:load`: load one skill by `skill_name`
 after loading a skill, follow its instructions and use referenced files or scripts with other tools
 reload a skill if its instructions are no longer in context
+example:
+~~~json
+{
+  "thoughts": ["A skill may already encode the workflow I need."],
+  "headline": "Loading relevant skill",
+  "tool_name": "skills_tool:load",
+  "tool_args": {
+    "skill_name": "playwright"
+  }
+}
+~~~

prompts/agent.system.tools_vision.md

@@ -1,4 +1,22 @@
+## multimodal vision tools
+
 ### vision_load
-load images into the model
-args: `paths` list of image paths
-use when visual inspection is needed
+load images into the model for visual reasoning
+args: `paths` list of absolute image paths
+rules:
+- load all relevant images in one call when comparing screenshots or pages
+- use when the task depends on screenshots, diagrams, scanned documents, charts, or photos
+- only bitmaps are supported; convert other formats first if needed
+example:
+```json
+{
+  "thoughts": [
+    "I need to inspect the screenshot before answering."
+  ],
+  "headline": "Loading screenshot for visual analysis",
+  "tool_name": "vision_load",
+  "tool_args": {
+    "paths": ["/path/to/screenshot.png"]
+  }
+}
+```