shumengya/sproutclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(coding-agent): fix promptGuidelines examples to name tools explicitly (#3489)

Browse Source 
promptGuidelines bullets are appended flat to the Guidelines section
with no tool name prefix. Using 'Use this tool when...' is ambiguous
because the LLM cannot tell which tool 'this' refers to. Updated docs
and examples to use explicit tool names instead.
This commit is contained in:
Aliou Diallo
2026-04-21 13:07:42 +02:00
committed by GitHub
parent b2a1997ea0
commit 01ec6e2e7f
2 changed files with 7 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
packages/coding-agent/docs/extensions.md
View File

@@ -1105,6 +1105,8 @@ Use `pi.setActiveTools()` to enable or disable tools (including dynamically adde
Use `promptSnippet` to opt a custom tool into a one-line entry in `Available tools`, and `promptGuidelines` to append tool-specific bullets to the default `Guidelines` section when the tool is active.
**Important:** `promptGuidelines` bullets are appended flat to the `Guidelines` section with no tool name prefix. Each guideline must name the tool it refers to — avoid "Use this tool when..." because the LLM cannot tell which tool "this" means. Write "Use my_tool when..." instead.
See [dynamic-tools.ts](../examples/extensions/dynamic-tools.ts) for a full example.
```typescript
@@ -1116,7 +1118,7 @@ pi.registerTool({
label: "My Tool",
description: "What this tool does",
promptSnippet: "Summarize or transform text according to action",
promptGuidelines: ["Use this tool when the user asks to summarize previously generated text."],
promptGuidelines: ["Use my_tool when the user asks to summarize previously generated text."],
parameters: Type.Object({
action: StringEnum(["list", "add"] as const),
text: Type.Optional(Type.String()),
@@ -1542,6 +1544,8 @@ Use `promptSnippet` for a short one-line entry in the `Available tools` section
Use `promptGuidelines` to add tool-specific bullets to the default system prompt `Guidelines` section. These bullets are included only while the tool is active (for example, after `pi.setActiveTools([...])`).
**Important:** `promptGuidelines` bullets are appended flat to the `Guidelines` section with no tool name prefix or grouping. Each guideline must name the tool it refers to — avoid "Use this tool when..." because the LLM cannot tell which tool "this" means. Write "Use my_tool when..." instead.
Note: Some models are idiots and include the @ prefix in tool path arguments. Built-in tools strip a leading @ before resolving paths. If your custom tool accepts a path, normalize a leading @ as well.
If your custom tool mutates files, use `withFileMutationQueue()` so it participates in the same per-file queue as built-in `edit` and `write`. This matters because tool calls run in parallel by default. Without the queue, two tools can read the same old file contents, compute different updates, and then whichever write lands last overwrites the other.
@@ -1587,7 +1591,7 @@ pi.registerTool({
description: "What this tool does (shown to LLM)",
promptSnippet: "List or add items in the project todo list",
promptGuidelines: [
"Use this tool for todo planning instead of direct file edits when the user asks for a task list."
"Use my_tool for todo planning instead of direct file edits when the user asks for a task list."
],
parameters: Type.Object({
action: StringEnum(["list", "add"] as const), // Use StringEnum for Google compatibility

2
packages/coding-agent/examples/extensions/dynamic-tools.ts
View File

@@ -35,7 +35,7 @@ export default function dynamicToolsExtension(pi: ExtensionAPI) {
label,
description: `Echo a message with prefix: ${prefix}`,
promptSnippet: `Echo back user-provided text with ${prefix.trim()} prefix`,
promptGuidelines: ["Use this tool when the user asks for exact echo output."],
promptGuidelines: ["Use echo_session when the user asks for exact echo output."],
parameters: ECHO_PARAMS,
async execute(_toolCallId, params) {
return {