1. 1//! `find_tools`: search the turn's deferred tool catalogue.
2. 2//!
3. 3//! Part of docs/design/68-context-engine.md §5's tool surface: tools not in
4. 4//! the always-visible core set are withheld from the prefix and reachable
5. 5//! only by name-and-description search here (or, on Anthropic, by the
6. 6//! provider's own tool search). No new dependency — matching is plain
7. 7//! case-insensitive substring and token overlap over each candidate's name,
8. 8//! description, and JSON-schema argument names/descriptions.
9. 9
10. 10use std::collections::HashMap;
11. 11use std::sync::{Arc, Mutex};
12. 12
13. 13use async_trait::async_trait;
14. 14use serde_json::{Value, json};
15. 15
16. 16use crate::{Tool, ToolContext, ToolOutput};
17. 17
18. 18pub struct FindToolsTool {
19. 19 catalogue: Vec<vak_llm::ToolDefinition>,
20. 20 /// Search-only vocabulary supplied by the capability registry (currently
21. 21 /// domain labels such as `live-data`). It is deliberately separate from
22. 22 /// the model-visible tool schema so discovery metadata cannot change the
23. 23 /// callable contract.
24. 24 keywords: HashMap<String, Vec<String>>,
25. 25 /// Every match returned this run is also pushed here, so the caller
26. 26 /// (`vak_agent::Agent::tool_definitions`) can keep offering a
27. 27 /// discovered tool's full schema for the rest of the turn without the
28. 28 /// model needing to call `find_tools` again (docs/design/68 §5).
29. 29 discovered: Option<Arc<Mutex<Vec<vak_llm::ToolDefinition>>>>,
30. 30}
31. 31
32. 32impl FindToolsTool {
33. 33 pub fn new(catalogue: Vec<vak_llm::ToolDefinition>) -> Self {
34. 34 FindToolsTool {
35. 35 catalogue,
36. 36 keywords: HashMap::new(),
37. 37 discovered: None,
38. 38 }
39. 39 }
40. 40
41. 41 pub fn with_keywords(mut self, keywords: HashMap<String, Vec<String>>) -> Self {
42. 42 self.keywords = keywords;
43. 43 self
44. 44 }
45. 45
46. 46 pub fn with_discovered_sink(mut self, sink: Arc<Mutex<Vec<vak_llm::ToolDefinition>>>) -> Self {
47. 47 self.discovered = Some(sink);
48. 48 self
49. 49 }
50. 50}
51. 51
52. 52const DEFAULT_LIMIT: usize = 5;
53. 53const MAX_LIMIT: usize = 50;
54. 54
55. 55#[async_trait]
56. 56impl Tool for FindToolsTool {
57. 57 fn name(&self) -> &str {
58. 58 "find_tools"
59. 59 }
60. 60
61. 61 fn always_loaded(&self) -> bool {
62. 62 true
63. 63 }
64. 64
65. 65 fn description(&self) -> &str {
66. 66 "Search all admitted tools, including already-loaded broker tools, by name, capability domain, description, or argument names/descriptions. Returns full schemas for the best matches; deferred matches become usable for the rest of this turn."
67. 67 }
68. 68
69. 69 fn schema(&self) -> Value {
70. 70 json!({
71. 71 "type": "object",
72. 72 "properties": {
73. 73 "query": {
74. 74 "type": "string",
75. 75 "description": "Words to match against tool names, descriptions, and argument names/descriptions."
76. 76 },
77. 77 "limit": {
78. 78 "type": "integer",
79. 79 "description": "Maximum number of matches to return (default 5)."
80. 80 }
81. 81 },
82. 82 "required": ["query"]
83. 83 })
84. 84 }
85. 85
86. 86 async fn execute(&self, args: &Value, _ctx: &ToolContext) -> ToolOutput {
87. 87 let Some(query) = args.get("query").and_then(|v| v.as_str()) else {
88. 88 return ToolOutput::error(
89. 89 r#"{"type":"invalid_arguments","message":"missing required string 'query'"}"#,
90. 90 );
91. 91 };
92. 92 if query.trim().is_empty() {
93. 93 return ToolOutput::error(
94. 94 r#"{"type":"invalid_arguments","message":"'query' must not be empty"}"#,
95. 95 );
96. 96 }
97. 97 let limit = args
98. 98 .get("limit")
99. 99 .and_then(Value::as_u64)
100. 100 .map(|n| (n as usize).clamp(1, MAX_LIMIT))
101. 101 .unwrap_or(DEFAULT_LIMIT);
102. 102 let matches = rank(&self.catalogue, &self.keywords, query, limit);
103. 103 if let Some(sink) = &self.discovered {
104. 104 let mut discovered = sink
105. 105 .lock()
106. 106 .unwrap_or_else(std::sync::PoisonError::into_inner);
107. 107 for def in &matches {
108. 108 if !discovered.iter().any(|existing| existing.name == def.name) {
109. 109 discovered.push((*def).clone());
110. 110 }
111. 111 }
112. 112 }
113. 113 let schemas: Vec<Value> = matches
114. 114 .iter()
115. 115 .map(|def| {
116. 116 json!({
117. 117 "name": def.name,
118. 118 "description": def.description,
119. 119 "input_schema": def.parameters,
120. 120 })
121. 121 })
122. 122 .collect();
123. 123 ToolOutput::ok(json!({"matches": schemas}).to_string())
124. 124 }
125. 125}
126. 126
127. 127fn rank<'a>(
128. 128 catalogue: &'a [vak_llm::ToolDefinition],
129. 129 keywords: &HashMap<String, Vec<String>>,
130. 130 query: &str,
131. 131 limit: usize,
132. 132) -> Vec<&'a vak_llm::ToolDefinition> {
133. 133 let query_lower = query.to_ascii_lowercase();
134. 134 let tokens: Vec<&str> = query_lower.split_whitespace().collect();
135. 135 let mut scored: Vec<(i64, &vak_llm::ToolDefinition)> = catalogue
136. 136 .iter()
137. 137 .filter_map(|def| {
138. 138 let score = score_tool(
139. 139 def,
140. 140 keywords
141. 141 .get(&def.name)
142. 142 .map(Vec::as_slice)
143. 143 .unwrap_or_default(),
144. 144 &query_lower,
145. 145 &tokens,
146. 146 );
147. 147 (score > 0).then_some((score, def))
148. 148 })
149. 149 .collect();
150. 150 scored.sort_by(|a, b| b.0.cmp(&a.0).then_with(|| a.1.name.cmp(&b.1.name)));
151. 151 scored.into_iter().take(limit).map(|(_, def)| def).collect()
152. 152}
153. 153
154. 154fn score_tool(
155. 155 def: &vak_llm::ToolDefinition,
156. 156 keywords: &[String],
157. 157 query_lower: &str,
158. 158 tokens: &[&str],
159. 159) -> i64 {
160. 160 let name_lower = def.name.to_ascii_lowercase();
161. 161 let mut haystack = format!("{} {}", name_lower, def.description.to_ascii_lowercase());
162. 162 collect_schema_text(&def.parameters, &mut haystack);
163. 163 for keyword in keywords {
164. 164 haystack.push(' ');
165. 165 haystack.push_str(&keyword.to_ascii_lowercase());
166. 166 }
167. 167
168. 168 let mut score = 0i64;
169. 169 if name_lower == query_lower {
170. 170 score += 100;
171. 171 }
172. 172 if name_lower.contains(query_lower) {
173. 173 score += 20;
174. 174 }
175. 175 if haystack.contains(query_lower) {
176. 176 score += 10;
177. 177 }
178. 178 for token in tokens {
179. 179 if !token.is_empty() && haystack.contains(token) {
180. 180 score += 5;
181. 181 }
182. 182 }
183. 183 score
184. 184}
185. 185
186. 186fn collect_schema_text(schema: &Value, out: &mut String) {
187. 187 let Some(properties) = schema.get("properties").and_then(Value::as_object) else {
188. 188 return;
189. 189 };
190. 190 for (name, property) in properties {
191. 191 out.push(' ');
192. 192 out.push_str(&name.to_ascii_lowercase());
193. 193 if let Some(description) = property.get("description").and_then(Value::as_str) {
194. 194 out.push(' ');
195. 195 out.push_str(&description.to_ascii_lowercase());
196. 196 }
197. 197 }
198. 198}
199. 199
200. 200#[cfg(test)]
201. 201#[allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
202. 202mod tests {
203. 203 use super::*;
204. 204 use std::path::PathBuf;
205. 205
206. 206 fn def(name: &str, description: &str, schema: Value) -> vak_llm::ToolDefinition {
207. 207 vak_llm::ToolDefinition::new(name, description, schema)
208. 208 }
209. 209
210. 210 fn ctx() -> ToolContext {
211. 211 ToolContext::new(PathBuf::from("."))
212. 212 }
213. 213
214. 214 #[tokio::test]
215. 215 async fn matches_by_name_and_description() {
216. 216 let tool = FindToolsTool::new(vec![
217. 217 def("webfetch", "Fetch a URL over HTTP.", json!({})),
218. 218 def("bash", "Run a shell command.", json!({})),
219. 219 ]);
220. 220 let out = tool.execute(&json!({"query": "http"}), &ctx()).await;
221. 221 assert!(!out.is_error);
222. 222 let parsed: Value = serde_json::from_str(&out.content).unwrap();
223. 223 let matches = parsed["matches"].as_array().unwrap();
224. 224 assert_eq!(matches.len(), 1);
225. 225 assert_eq!(matches[0]["name"], "webfetch");
226. 226 }
227. 227
228. 228 #[tokio::test]
229. 229 async fn matches_by_argument_name_and_description() {
230. 230 let tool = FindToolsTool::new(vec![def(
231. 231 "weather_lookup",
232. 232 "Look something up.",
233. 233 json!({
234. 234 "type": "object",
235. 235 "properties": {
236. 236 "city": {"type": "string", "description": "City to check the forecast for"}
237. 237 }
238. 238 }),
239. 239 )]);
240. 240 let out = tool.execute(&json!({"query": "forecast"}), &ctx()).await;
241. 241 let parsed: Value = serde_json::from_str(&out.content).unwrap();
242. 242 assert_eq!(parsed["matches"].as_array().unwrap().len(), 1);
243. 243 }
244. 244
245. 245 #[tokio::test]
246. 246 async fn matches_loaded_broker_by_capability_domain() {
247. 247 let tool = FindToolsTool::new(vec![def(
248. 248 "mcp",
249. 249 "Call tools exposed by configured servers.",
250. 250 json!({}),
251. 251 )])
252. 252 .with_keywords(HashMap::from([(
253. 253 "mcp".into(),
254. 254 vec!["live-data".into(), "web".into()],
255. 255 )]));
256. 256 let out = tool
257. 257 .execute(&json!({"query": "live-data weather"}), &ctx())
258. 258 .await;
259. 259 let parsed: Value = serde_json::from_str(&out.content).unwrap();
260. 260 assert_eq!(parsed["matches"][0]["name"], "mcp");
261. 261 }
262. 262
263. 263 #[tokio::test]
264. 264 async fn returns_full_schema_for_matches() {
265. 265 let schema = json!({"type": "object", "properties": {"q": {"type": "string"}}});
266. 266 let tool = FindToolsTool::new(vec![def("search", "Search the web.", schema.clone())]);
267. 267 let out = tool.execute(&json!({"query": "search"}), &ctx()).await;
268. 268 let parsed: Value = serde_json::from_str(&out.content).unwrap();
269. 269 assert_eq!(parsed["matches"][0]["input_schema"], schema);
270. 270 }
271. 271
272. 272 #[tokio::test]
273. 273 async fn respects_limit_and_ranks_best_matches_first() {
274. 274 let tool = FindToolsTool::new(vec![
275. 275 def("search_exact", "search", json!({})),
276. 276 def("search_other", "search something else", json!({})),
277. 277 def("unrelated", "does nothing related", json!({})),
278. 278 ]);
279. 279 let out = tool
280. 280 .execute(&json!({"query": "search", "limit": 1}), &ctx())
281. 281 .await;
282. 282 let parsed: Value = serde_json::from_str(&out.content).unwrap();
283. 283 let matches = parsed["matches"].as_array().unwrap();
284. 284 assert_eq!(matches.len(), 1);
285. 285 assert_eq!(matches[0]["name"], "search_exact");
286. 286 }
287. 287
288. 288 #[tokio::test]
289. 289 async fn no_matches_returns_an_empty_list_not_an_error() {
290. 290 let tool = FindToolsTool::new(vec![def("bash", "Run a shell command.", json!({}))]);
291. 291 let out = tool
292. 292 .execute(&json!({"query": "zzz_no_such_thing"}), &ctx())
293. 293 .await;
294. 294 assert!(!out.is_error);
295. 295 let parsed: Value = serde_json::from_str(&out.content).unwrap();
296. 296 assert!(parsed["matches"].as_array().unwrap().is_empty());
297. 297 }
298. 298
299. 299 #[tokio::test]
300. 300 async fn matches_are_pushed_into_the_discovered_sink() {
301. 301 let sink = Arc::new(Mutex::new(Vec::new()));
302. 302 let tool = FindToolsTool::new(vec![def("bash", "Run a shell command.", json!({}))])
303. 303 .with_discovered_sink(sink.clone());
304. 304 tool.execute(&json!({"query": "bash"}), &ctx()).await;
305. 305 let discovered = sink.lock().unwrap();
306. 306 assert_eq!(discovered.len(), 1);
307. 307 assert_eq!(discovered[0].name, "bash");
308. 308 }
309. 309
310. 310 #[tokio::test]
311. 311 async fn missing_query_is_a_correctable_error() {
312. 312 let tool = FindToolsTool::new(vec![]);
313. 313 let out = tool.execute(&json!({}), &ctx()).await;
314. 314 assert!(out.is_error);
315. 315 }
316. 316}
317. 317