refactor(tools): improve description fields to be action-oriented and agent-facing
Rewrite all 13 renamed tool descriptions to follow Copilot tool conventions: - Imperative verb opening - One sentence on what it returns - One sentence on when to use it - No internal jargon or SF-specific acronyms Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Mikael Hugo
parent
ac371926cb
commit
e7bd6a76b9
5 changed files with 30 additions and 40 deletions
|
|
@ -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: [
|
||||
|
|
|
|||
|
|
@ -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/<id>.{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: [
|
||||
|
|
|
|||
|
|
@ -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: [
|
||||
|
|
|
|||
|
|
@ -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.",
|
||||
|
|
|
|||
|
|
@ -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: [
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue