From cf48d297dd3d84e59aefe895764f60317a3fd4bc Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 23 Dec 2025 00:29:38 +0000 Subject: [PATCH] docs: explain tool exposure in pi-mono --- docs/tools.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/tools.md b/docs/tools.md index 283e0dfa5..e49f552d9 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -99,3 +99,26 @@ Node targeting: - Avoid `system.run` (not exposed as a tool). - Respect user consent for camera/screen capture. - Use `status/describe` to ensure permissions before invoking media commands. + +## How the model sees tools (pi-mono internals) + +Tools are exposed to the model in **two parallel channels**: + +1) **System prompt text**: a human-readable list + guidelines. +2) **Provider tool schema**: the actual function/tool declarations sent to the model API. + +In pi-mono: +- System prompt builder: `packages/coding-agent/src/core/system-prompt.ts` + - Builds the `Available tools:` list from `toolDescriptions`. + - Appends skills and project context. +- Tool schemas passed to providers: + - OpenAI: `packages/ai/src/providers/openai-responses.ts` (`convertTools`) + - Anthropic: `packages/ai/src/providers/anthropic.ts` (`convertTools`) + - Gemini: `packages/ai/src/providers/google-shared.ts` (`convertTools`) +- Tool execution loop: + - Agent loop: `packages/ai/src/agent/agent-loop.ts` + - Validates tool arguments and executes tools, then appends `toolResult` messages. + +In Clawdis: +- System prompt append: `src/agents/system-prompt.ts` +- Tool list injected via `createClawdisCodingTools()` in `src/agents/pi-tools.ts`