ref(tools): move tool guidance into descriptions, deprecate promptSnippet/promptGuidelines#460
Merged
Merged
Conversation
…ppet/promptGuidelines
All guidance for built-in tools (editFile, writeFile, slackCanvasEdit,
slackCanvasWrite, all scheduler tools) now lives in the tool description
and parameter descriptions — where the model sees it at selection time —
rather than in the <tool-guidance> system-prompt block.
Research across Codex, Claude Code, and pi (earendil-works/pi-mono)
shows none of them use a separate structured guidance block. Anthropic
explicitly recommends putting selection/usage guidance in tool descriptions.
The <tool-guidance> block was duplicating information already visible in
tool schemas, burning context-window tokens needlessly.
Changes:
- editFile: comparative preference over writeFile moved into description
- writeFile: redirect to editFile moved into description
- slackCanvasEdit/Write: same pattern as editFile/writeFile
- scheduler tools: all 8 behavioral guidelines distributed across tool
descriptions and parameter descriptions; removed dead ACTIVE_DESTINATION_
GUIDELINE, ACTIVE_TASK_ID_GUIDELINE, RECURRING_GUIDELINE constants
- advisor: description reordered to lead with proactive triggers
('before committing to a non-obvious plan') rather than fallback/stuck
framing; spec updated to match
- ToolDefinition and AgentPluginToolDefinition: promptSnippet and
promptGuidelines marked @deprecated with migration note; infrastructure
retained for plugin compatibility
Co-Authored-By: claude-opus-4-5 <noreply@anthropic.com>
---
[View Session in Sentry](https://sentry.sentry.io/traces/?project=4510944073809921&query=gen_ai.conversation.id%3A%22slack%3AC0AHB7N2JCR%3A1780251764.433629%22)
Co-authored-by: David Cramer <david@sentry.io>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…recurrence union - slackCanvasWrite: removed trailing 'Do not use for targeted edits' which was redundant after the redirect to slackCanvasEdit already stated - schedule-tools: dropped recurrenceInputSchema constant (now only used once); inlined literals in Update tool as a flat Union with Null to avoid the nested Union([Union([...]), Null]) shape Co-Authored-By: claude-opus-4-5 <noreply@anthropic.com> Co-authored-by: David Cramer <david@sentry.io>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Moves all tool-selection and usage guidance for built-in tools from the
<tool-guidance>system-prompt block into each tool'sdescriptionfield and parameter descriptions. DeprecatespromptSnippet/promptGuidelineson theToolDefinitionandAgentPluginToolDefinitioninterfaces.Also rewords the advisor tool description to lead with proactive triggers instead of fallback framing.
Why
Research across Codex (GPT-5.5), Claude Code, and pi (earendil-works/pi-mono) shows none of them use a separate structured guidance block. Anthropic's published context-engineering guidance explicitly recommends putting selection/usage guidance in tool descriptions, where the model sees it at tool-selection time. The
<tool-guidance>block was duplicating information already in the tool schemas, wasting context-window attention budget.Changes
descriptionand parameterdescriptionfields; removed deadACTIVE_DESTINATION_GUIDELINE,ACTIVE_TASK_ID_GUIDELINE,RECURRING_GUIDELINEconstantsspecs/advisor-tool.md) updated to matchpromptSnippetandpromptGuidelinesmarked@deprecatedwith migration note; infrastructure retained for plugin backward compatibilityVerified
pnpm typecheckpasses (all packages)tests/unit/— 877 tests passtests/integration/slack-schedule-tools.test.ts— 25 tests passpromptSnippetorpromptGuidelines; only infrastructurerespond.tsreads them (for plugin compat) and one test fixture still exercises the mechanismNot Changed
The
formatToolGuidanceForPromptinfrastructure inprompt.tsand the collection inrespond.tsare retained so external plugins usingpromptGuidelinescontinue to work. The<tool-guidance>block will now only appear when a plugin tool actually populates these deprecated fields.Action taken on behalf of David Cramer.
View Session in Sentry