talon_cli/
agent_contract.rs

1/// Compile-time contract for a named agent tool.
2#[derive(Debug)]
3pub struct AgentToolContract {
4    pub name: &'static str,
5    pub description: &'static str,
6    pub when_to_use: &'static str,
7    pub when_not_to_use: &'static str,
8}
9
10pub const SEARCH: AgentToolContract = AgentToolContract {
11    name: "talon_search",
12    description: "Search the Obsidian vault for notes relevant to a query, with hybrid retrieval and graph-aware refinement. Use for explicit lookup beyond automatic recall. Default search excludes scopes configured with `default = false` such as `raw/`, `archive/`, or `private/`; pass `scopeAll: true` or an explicit `scope` when looking for recall-injected paths from those scopes. Returns compact agent JSON with ranked plain-path results; synthesize answers yourself or call the CLI `talon ask` only when you specifically want Talon's smaller built-in answer model.",
13    when_to_use: "When you need to find notes by topic, keyword, or semantic meaning that auto-recall did not cover, or when you need source snippets before synthesizing an answer.",
14    when_not_to_use: "When you already have the exact path — use talon_read instead.",
15};
16
17pub const READ: AgentToolContract = AgentToolContract {
18    name: "talon_read",
19    description: "Read a vault note by path or Obsidian reference. Use after search when you need source text, exact wording, or a section body.",
20    when_to_use: "When you have a specific vault path or [[Obsidian Ref]] and need its content.",
21    when_not_to_use: "When you are looking for notes by topic — use talon_search instead.",
22};
23
24pub const RELATED: AgentToolContract = AgentToolContract {
25    name: "talon_related",
26    description: "Find ranked related notes from links, backlinks, shared sources, common neighbors, and graph communities. Use for deliberate graph/provenance exploration from a known note.",
27    when_to_use: "When you want to explore graph-ranked context around a specific note.",
28    when_not_to_use: "When you want a broad topic search — use talon_search instead.",
29};
30
31pub const RECALL_HOOK: AgentToolContract = AgentToolContract {
32    name: "talon_hook_recall",
33    description: "Hook-only tool that injects vault recall context before each agent turn. Managed automatically by the session lifecycle — do not call manually.",
34    when_to_use: "Never — this is managed by Claude Code hooks automatically.",
35    when_not_to_use: "Always. Do not call this tool directly.",
36};
talon_cli/agent_contract.rs

talon_cli/
agent_contract.rs
