diff --git a/src/resources/extensions/sf/bootstrap/db-tools.js b/src/resources/extensions/sf/bootstrap/db-tools.js index e8deda902..942ae14f5 100644 --- a/src/resources/extensions/sf/bootstrap/db-tools.js +++ b/src/resources/extensions/sf/bootstrap/db-tools.js @@ -528,9 +528,8 @@ export function registerDbTools(pi) { name: "new_milestone_id", label: "Generate Milestone ID", description: - "Generate the next milestone ID for a new SF milestone. " + - "Scans existing milestones on disk and respects the unique_milestone_ids preference. " + - "Always use this tool when creating a new milestone — never invent milestone IDs manually.", + "Generate the next sequential milestone ID and return it as a string. " + + "Always call this when creating a new milestone — never invent or hardcode milestone IDs manually.", promptSnippet: "Generate a valid milestone ID (respects unique_milestone_ids preference)", promptGuidelines: [ @@ -639,15 +638,9 @@ export function registerDbTools(pi) { name: "report_issue", label: "Self Report", description: - "Record any thought about sf itself — bugs, missing features, prompt-quality issues, ideas, " + - "design speculations, agent friction — so it can be addressed in a future unit. " + - "Use this for any sf-internal observation: brittle gate predicates, advisory-downgrade " + - "swallowing real failures, but ALSO ambiguous prompts, missing context, friction in agent " + - "workflows, or speculative improvements. Over-reporting is preferred to under-reporting; " + - "dedup happens later. Do NOT use this for bugs in the user's project or for your own task " + - "work — only for sf-the-tool observations. Entries route automatically: when working on " + - "singularity-forge itself they land in .sf/SELF-FEEDBACK.md; otherwise they land in a global " + - "~/.sf/upstream-feedback.jsonl.", + "Record an observation about the agent tooling itself — a bug, missing feature, confusing prompt, friction, or improvement idea — for future review. " + + "Over-reporting is preferred; duplicates are resolved later. " + + "Do not use this for bugs in the user's project — only for observations about the agent tooling itself.", promptSnippet: "Report any sf-internal observation: bug, missing feature, prompt issue, idea, friction", promptGuidelines: [ @@ -823,8 +816,8 @@ export function registerDbTools(pi) { name: "resolve_issue", label: "Resolve Self Feedback", description: - "Mark a repaired SF self-feedback entry resolved with structured agent-fix evidence. " + - "Use this only after verifying the entry no longer applies, landing the fix, and citing the commit or verification evidence.", + "Mark a previously reported agent-system issue as resolved and record the fix evidence (commit SHA, test path, or narrative). " + + "Call this only after the fix is implemented and verified — not speculatively.", promptSnippet: "Resolve a repaired SF self-feedback entry with commit/test evidence", promptGuidelines: [ @@ -930,8 +923,8 @@ export function registerDbTools(pi) { name: "checkpoint", label: "Autonomous Checkpoint", description: - "Record a PDD-shaped autonomous solver checkpoint for the current unit. " + - "Use this before ending every /autonomous unit turn to make progress, blockers, decisions, and remaining work explicit.", + "Save a structured progress checkpoint for the current autonomous task — capturing what was done, what's blocked, and what remains. " + + "Call this before ending every turn in autonomous mode to make progress visible and recoverable.", promptSnippet: "Checkpoint autonomous solver progress with PDD fields and semantic outcome", promptGuidelines: [ @@ -2540,8 +2533,8 @@ export function registerDbTools(pi) { name: "record_gate", label: "Save Gate Result", description: - "Save the result of a quality gate evaluation (Q3-Q8 or MV01-MV04) to the SF database. " + - "Called by gate evaluation sub-agents after analyzing a specific quality question.", + "Save the result of a quality gate evaluation — verdict, rationale, and findings — to the database. " + + "Call this after evaluating a quality gate question; one call per gate per evaluation run.", promptSnippet: "Save quality gate evaluation result (verdict, rationale, findings)", promptGuidelines: [ diff --git a/src/resources/extensions/sf/bootstrap/exec-tools.js b/src/resources/extensions/sf/bootstrap/exec-tools.js index d694f5b16..1ce1220ce 100644 --- a/src/resources/extensions/sf/bootstrap/exec-tools.js +++ b/src/resources/extensions/sf/bootstrap/exec-tools.js @@ -22,11 +22,9 @@ export function registerExecTools(pi) { name: "run_command", label: "Exec (Sandboxed)", description: - "Run a short script (bash/node/python) in a subprocess. Full stdout/stderr persist to " + - ".sf/exec/.{stdout,stderr,meta.json}; only a short digest returns in context. Use " + - "this instead of reading many files or emitting large tool outputs — e.g. have the script " + - "count/grep/summarize and log the finding. Enabled by default; opt out via " + - "preferences.context_mode.enabled=false.", + "Run a shell command (bash, node, or python) in a subprocess and return a short digest of the output. " + + "Full stdout/stderr are saved to disk and retrievable with read_output. " + + "Use this for any shell operation — builds, tests, grep, git — whenever the raw output would be too large to return inline.", promptSnippet: "Run a bash/node/python script in a sandbox; full output is saved to disk and only a digest returns", promptGuidelines: [ @@ -92,8 +90,9 @@ export function registerExecTools(pi) { name: "read_output", label: "Search run_command History", description: - "List prior run_command runs (most recent first) from .sf/exec/*.meta.json. Useful for " + - "rediscovering the stdout_path of an earlier run without re-executing it. Read-only.", + "List recent run_command executions and retrieve their saved stdout/stderr. " + + "Returns run metadata (command, exit code, output paths) ordered most-recent first. " + + "Use this to re-read a prior command's full output without re-running it.", promptSnippet: "Search prior run_command runs by substring, runtime, or failing-only filter", promptGuidelines: [ @@ -141,9 +140,8 @@ export function registerExecTools(pi) { name: "resume_agent", label: "Resume (Read Snapshot)", description: - "Return the contents of .sf/last-snapshot.md — a ≤2 KB digest of top memories, recent " + - "run_command runs, and active context, written automatically on session_before_compact. Use " + - "this after compaction or session resume to re-orient quickly.", + "Read the saved session snapshot and return a compact summary of recent commands, top memories, and active context. " + + "Use this immediately after context compaction or session resume to re-orient before continuing work.", promptSnippet: "Read the pre-compaction snapshot to re-orient after context loss", promptGuidelines: [ diff --git a/src/resources/extensions/sf/bootstrap/judgment-tools.js b/src/resources/extensions/sf/bootstrap/judgment-tools.js index 1ca3b8a2f..3dcb65708 100644 --- a/src/resources/extensions/sf/bootstrap/judgment-tools.js +++ b/src/resources/extensions/sf/bootstrap/judgment-tools.js @@ -11,9 +11,9 @@ export function registerJudgmentTools(pi) { name: "log_decision", label: "Log Judgment", description: - "Record an agent judgment call for user review at milestone close. " + - "Call this when choosing between alternatives at an ambiguous decision point. " + - "Does NOT delay or block work — pure append-only side-effect.", + "Record a judgment call made at an ambiguous decision point for user review at milestone close. " + + "Returns immediately with no blocking effect. " + + "Use this whenever you choose between valid alternatives — approach, scope, trade-off — so the rationale is visible for review.", promptSnippet: "Log a judgment call: decision taken, alternatives considered, reasoning, confidence", promptGuidelines: [ diff --git a/src/resources/extensions/sf/bootstrap/memory-tools.js b/src/resources/extensions/sf/bootstrap/memory-tools.js index 86f79cbda..36a567f91 100644 --- a/src/resources/extensions/sf/bootstrap/memory-tools.js +++ b/src/resources/extensions/sf/bootstrap/memory-tools.js @@ -16,9 +16,8 @@ export function registerMemoryTools(pi) { name: "log_reasoning", label: "Capture Thought", description: - "Record a durable piece of project knowledge (decision, convention, gotcha, pattern, " + - "preference, or environment detail) into the SF memory store. Use sparingly — one memory " + - "per genuinely reusable insight, not per task.", + "Save a reusable project insight — a decision, convention, pattern, gotcha, or environment detail — to persistent memory. " + + "Use this once per genuinely new insight that will remain relevant across future tasks; skip transient or task-specific observations.", promptSnippet: "Capture a durable project insight into the SF memory store (categories: architecture, convention, gotcha, pattern, preference, environment)", promptGuidelines: [ @@ -72,8 +71,8 @@ export function registerMemoryTools(pi) { name: "memory_search", label: "Query Memory", description: - "Search the SF memory store for relevant memories. Uses keyword matching ranked " + - "by confidence and reinforcement.", + "Search persistent memory for stored insights and return matches ranked by relevance and confidence. " + + "Use this before starting research to surface prior decisions, conventions, or environment details that apply to the current task.", promptSnippet: "Search the SF memory store by keyword; returns ranked memories with id, category, and content", promptGuidelines: [ @@ -132,8 +131,8 @@ export function registerMemoryTools(pi) { name: "memory_graph", label: "SF Knowledge Graph", description: - "Inspect the relationship graph between memories. mode=query walks supersedes edges from a " + - "given memoryId; mode=build is a placeholder for future graph edge rebuilds.", + "Inspect the supersession graph between memory entries and return the chain of memories a given entry has replaced. " + + "Use this when you need to understand how a stored insight has evolved or been overridden over time.", promptSnippet: "Query the memory relationship graph or trigger a rebuild", promptGuidelines: [ "Use mode=query with a memoryId when you want to see how a memory relates to others.", diff --git a/src/resources/extensions/sf/bootstrap/query-tools.js b/src/resources/extensions/sf/bootstrap/query-tools.js index feeda1515..436b76617 100644 --- a/src/resources/extensions/sf/bootstrap/query-tools.js +++ b/src/resources/extensions/sf/bootstrap/query-tools.js @@ -41,8 +41,8 @@ export function registerQueryTools(pi) { name: "search_evidence", label: "Retrieval Evidence", description: - "Read recent retrieval provenance from the SF database. Returns source backend, query, scope, freshness, status, and result metadata. " + - "Use this instead of querying .sf/sf.db directly when auditing Sift, codebase_search, Context7, or web-derived context.", + "Search the retrieval evidence log and return metadata about prior information lookups — source backend, query, scope, freshness, and status. " + + "Use this to audit where retrieved context came from or to check whether a search has already been performed.", promptSnippet: "Inspect recent retrieval evidence rows with backend, scope, freshness, and hit counts", promptGuidelines: [