[{"data":1,"prerenderedAt":773},["ShallowReactive",2],{"docs-\u002Fdocs\u002Fv2\u002Fapi\u002Ftools":3},{"id":4,"title":5,"body":6,"description":16,"extension":767,"meta":768,"navigation":544,"path":769,"seo":770,"stem":771,"__hash__":772},"docs\u002Fdocs\u002Fv2\u002Fapi\u002Ftools.md","Tools",{"type":7,"value":8,"toc":759},"minimark",[9,13,17,141,146,149,152,156,163,250,316,330,350,354,360,392,399,403,409,444,447,461,465,479,652,655,661,665,752,755],[10,11,5],"h1",{"id":12},"tools",[14,15,16],"p",{},"Tool exports are globals. Call them directly from scripts, routes, and hooks — no prefix, no namespace wrapper.",[18,19,24],"pre",{"className":20,"code":21,"language":22,"meta":23,"style":23},"language-ts shiki shiki-themes dark-plus","\u002F\u002F src\u002Fscripts\u002Ftriage.ts\nconst tasks = await kanban.list(\"open\")\nconst session = await axon.prompt(\"session\", { tasks })\nconst { stream } = axon.stream({ prompt: session })\n","ts","",[25,26,27,36,76,110],"code",{"__ignoreMap":23},[28,29,32],"span",{"class":30,"line":31},"line",1,[28,33,35],{"class":34},"sOLPB","\u002F\u002F src\u002Fscripts\u002Ftriage.ts\n",[28,37,39,43,47,51,55,59,62,66,69,73],{"class":30,"line":38},2,[28,40,42],{"class":41},"scz_3","const",[28,44,46],{"class":45},"s9McN"," tasks",[28,48,50],{"class":49},"sTNBD"," = ",[28,52,54],{"class":53},"sYbnZ","await",[28,56,58],{"class":57},"s3F5K"," kanban",[28,60,61],{"class":49},".",[28,63,65],{"class":64},"sCudf","list",[28,67,68],{"class":49},"(",[28,70,72],{"class":71},"sKc5r","\"open\"",[28,74,75],{"class":49},")\n",[28,77,79,81,84,86,88,91,93,96,98,101,104,107],{"class":30,"line":78},3,[28,80,42],{"class":41},[28,82,83],{"class":45}," session",[28,85,50],{"class":49},[28,87,54],{"class":53},[28,89,90],{"class":57}," axon",[28,92,61],{"class":49},[28,94,95],{"class":64},"prompt",[28,97,68],{"class":49},[28,99,100],{"class":71},"\"session\"",[28,102,103],{"class":49},", { ",[28,105,106],{"class":57},"tasks",[28,108,109],{"class":49}," })\n",[28,111,113,115,118,121,124,127,129,131,134,137,139],{"class":30,"line":112},4,[28,114,42],{"class":41},[28,116,117],{"class":49}," { ",[28,119,120],{"class":45},"stream",[28,122,123],{"class":49}," } = ",[28,125,126],{"class":57},"axon",[28,128,61],{"class":49},[28,130,120],{"class":64},[28,132,133],{"class":49},"({ ",[28,135,136],{"class":57},"prompt:",[28,138,83],{"class":57},[28,140,109],{"class":49},[142,143,145],"h2",{"id":144},"why-globals","Why globals",[14,147,148],{},"Tools are primarily called by the agent during its cognitive loop. But scripts often need to call tools directly — to load state before constructing a prompt, to act on the agent's output, or to run work without the loop.",[14,150,151],{},"You wrote the function; you should be able to call it. Tools execute in the capsule, a separate subprocess, and the transport is handled for you — a script author never has to know the boundary is there. The same call works from a script, a route handler, a hook, or the agent itself.",[142,153,155],{"id":154},"what-becomes-a-global","What becomes a global",[14,157,158,159,162],{},"Each top-level export from ",[25,160,161],{},"src\u002Ftools\u002F*.ts"," lands on the global scope with its exact name.",[18,164,166],{"className":20,"code":165,"language":22,"meta":23,"style":23},"\u002F\u002F src\u002Ftools\u002Fkanban.ts\nexport const kanban = {\n    list: async (status?: string) => ...,\n    add: async (title: string) => ...,\n}\n",[25,167,168,173,186,219,244],{"__ignoreMap":23},[28,169,170],{"class":30,"line":31},[28,171,172],{"class":34},"\u002F\u002F src\u002Ftools\u002Fkanban.ts\n",[28,174,175,178,181,183],{"class":30,"line":38},[28,176,177],{"class":53},"export",[28,179,180],{"class":41}," const",[28,182,58],{"class":45},[28,184,185],{"class":49}," = {\n",[28,187,188,191,194,197,200,203,206,210,213,216],{"class":30,"line":78},[28,189,190],{"class":64},"    list",[28,192,193],{"class":57},":",[28,195,196],{"class":41}," async",[28,198,199],{"class":49}," (",[28,201,202],{"class":57},"status",[28,204,205],{"class":49},"?: ",[28,207,209],{"class":208},"sNl3T","string",[28,211,212],{"class":49},") ",[28,214,215],{"class":41},"=>",[28,217,218],{"class":49}," ...,\n",[28,220,221,224,226,228,230,233,236,238,240,242],{"class":30,"line":112},[28,222,223],{"class":64},"    add",[28,225,193],{"class":57},[28,227,196],{"class":41},[28,229,199],{"class":49},[28,231,232],{"class":57},"title",[28,234,235],{"class":49},": ",[28,237,209],{"class":208},[28,239,212],{"class":49},[28,241,215],{"class":41},[28,243,218],{"class":49},[28,245,247],{"class":30,"line":246},5,[28,248,249],{"class":49},"}\n",[18,251,253],{"className":20,"code":252,"language":22,"meta":23,"style":23},"\u002F\u002F src\u002Ftools\u002Ftime.ts\nexport async function now() { return new Date().toISOString() }\nexport async function format(date: string) { ... }\n",[25,254,255,260,293],{"__ignoreMap":23},[28,256,257],{"class":30,"line":31},[28,258,259],{"class":34},"\u002F\u002F src\u002Ftools\u002Ftime.ts\n",[28,261,262,264,266,269,272,275,278,281,284,287,290],{"class":30,"line":38},[28,263,177],{"class":53},[28,265,196],{"class":41},[28,267,268],{"class":41}," function",[28,270,271],{"class":64}," now",[28,273,274],{"class":49},"() { ",[28,276,277],{"class":53},"return",[28,279,280],{"class":41}," new",[28,282,283],{"class":64}," Date",[28,285,286],{"class":49},"().",[28,288,289],{"class":64},"toISOString",[28,291,292],{"class":49},"() }\n",[28,294,295,297,299,301,304,306,309,311,313],{"class":30,"line":78},[28,296,177],{"class":53},[28,298,196],{"class":41},[28,300,268],{"class":41},[28,302,303],{"class":64}," format",[28,305,68],{"class":49},[28,307,308],{"class":57},"date",[28,310,235],{"class":49},[28,312,209],{"class":208},[28,314,315],{"class":49},") { ... }\n",[14,317,318,319,322,323,322,326,329],{},"The agent and all scripts see: ",[25,320,321],{},"kanban",", ",[25,324,325],{},"now",[25,327,328],{},"format"," — each directly callable.",[14,331,332,333,336,337,340,341,344,345,61],{},"Installed modules keep their namespace: ",[25,334,335],{},"@axon\u002Fgithub"," contributes ",[25,338,339],{},"github.openPr",", not a bare ",[25,342,343],{},"openPr",". See ",[346,347,349],"a",{"href":348},"\u002Fdocs\u002Fv2\u002Fmodules\u002Foverview","Modules",[142,351,353],{"id":352},"always-awaited","Always awaited",[14,355,356,357,359],{},"Every tool call is ",[25,358,54],{},"ed, whether you wrote the function sync or async:",[18,361,363],{"className":20,"code":362,"language":22,"meta":23,"style":23},"const sum = await add(2, 3)\n",[25,364,365],{"__ignoreMap":23},[28,366,367,369,372,374,376,379,381,385,387,390],{"class":30,"line":31},[28,368,42],{"class":41},[28,370,371],{"class":45}," sum",[28,373,50],{"class":49},[28,375,54],{"class":53},[28,377,378],{"class":64}," add",[28,380,68],{"class":49},[28,382,384],{"class":383},"sDGX8","2",[28,386,322],{"class":49},[28,388,389],{"class":383},"3",[28,391,75],{"class":49},[14,393,394,395,61],{},"Each call is policy-checked before the function body runs, and a rule can escalate to the user for approval — a round trip that cannot be synchronous. See ",[346,396,398],{"href":397},"\u002Fdocs\u002Fv2\u002Fagent\u002Fsrc\u002Ftools#every-tool-is-async-at-the-call-site","tools\u002F",[142,400,402],{"id":401},"axontools-the-explicit-path","axon.tools.* — the explicit path",[14,404,405,406,193],{},"The same functions are always reachable under ",[25,407,408],{},"axon.tools.\u003Cfile>.\u003Cfn>",[18,410,412],{"className":20,"code":411,"language":22,"meta":23,"style":23},"const tasks = await axon.tools.kanban.list(\"open\")\n",[25,413,414],{"__ignoreMap":23},[28,415,416,418,420,422,424,426,428,430,432,434,436,438,440,442],{"class":30,"line":31},[28,417,42],{"class":41},[28,419,46],{"class":45},[28,421,50],{"class":49},[28,423,54],{"class":53},[28,425,90],{"class":57},[28,427,61],{"class":49},[28,429,12],{"class":57},[28,431,61],{"class":49},[28,433,321],{"class":57},[28,435,61],{"class":49},[28,437,65],{"class":64},[28,439,68],{"class":49},[28,441,72],{"class":71},[28,443,75],{"class":49},[14,445,446],{},"Identical behaviour — same capsule, same policy, same tracing. The globals are bindings onto this surface, not a separate route.",[14,448,449,450,453,454,456,457,460],{},"Reach for it when a bare name would be ambiguous or unavailable: a tool whose name collides with a host builtin (a tool called ",[25,451,452],{},"fetch"," will not shadow the real ",[25,455,452],{},", and stays callable as ",[25,458,459],{},"axon.tools.\u003Cfile>.fetch","), or code driving a runtime other than its own.",[142,462,464],{"id":463},"typing","Typing",[14,466,467,470,471,474,475,478],{},[25,468,469],{},"axon prepare"," generates ",[25,472,473],{},".agent\u002Ftool-globals.d.ts"," — a ",[25,476,477],{},"declare global"," block declaring each export, with the types read from your source and any type your signature references carried alongside it. Full autocomplete with no imports required.",[18,480,482],{"className":20,"code":481,"language":22,"meta":23,"style":23},"\u002F\u002F .agent\u002Ftool-globals.d.ts — generated, do not edit\ndeclare global {\n    type Task = { id: string; title: string; done: boolean }\n\n    \u002F** Fetch the next unfinished task. *\u002F\n    function next(): Promise\u003CTask | null>\n\n    namespace github {\n        function openPr(title: string): Promise\u003C{ number: number; url: string }>\n    }\n}\n",[25,483,484,489,500,540,546,551,581,586,597,641,647],{"__ignoreMap":23},[28,485,486],{"class":30,"line":31},[28,487,488],{"class":34},"\u002F\u002F .agent\u002Ftool-globals.d.ts — generated, do not edit\n",[28,490,491,494,497],{"class":30,"line":38},[28,492,493],{"class":41},"declare",[28,495,496],{"class":57}," global",[28,498,499],{"class":49}," {\n",[28,501,502,505,508,511,514,516,518,521,523,525,527,529,532,534,537],{"class":30,"line":78},[28,503,504],{"class":41},"    type",[28,506,507],{"class":208}," Task",[28,509,510],{"class":49}," = { ",[28,512,513],{"class":57},"id",[28,515,235],{"class":49},[28,517,209],{"class":208},[28,519,520],{"class":49},"; ",[28,522,232],{"class":57},[28,524,235],{"class":49},[28,526,209],{"class":208},[28,528,520],{"class":49},[28,530,531],{"class":57},"done",[28,533,235],{"class":49},[28,535,536],{"class":208},"boolean",[28,538,539],{"class":49}," }\n",[28,541,542],{"class":30,"line":112},[28,543,545],{"emptyLinePlaceholder":544},true,"\n",[28,547,548],{"class":30,"line":246},[28,549,550],{"class":34},"    \u002F** Fetch the next unfinished task. *\u002F\n",[28,552,554,557,560,563,566,569,572,575,578],{"class":30,"line":553},6,[28,555,556],{"class":41},"    function",[28,558,559],{"class":64}," next",[28,561,562],{"class":49},"(): ",[28,564,565],{"class":208},"Promise",[28,567,568],{"class":49},"\u003C",[28,570,571],{"class":208},"Task",[28,573,574],{"class":49}," | ",[28,576,577],{"class":208},"null",[28,579,580],{"class":49},">\n",[28,582,584],{"class":30,"line":583},7,[28,585,545],{"emptyLinePlaceholder":544},[28,587,589,592,595],{"class":30,"line":588},8,[28,590,591],{"class":41},"    namespace",[28,593,594],{"class":208}," github",[28,596,499],{"class":49},[28,598,600,603,606,608,610,612,614,617,619,622,625,627,629,631,634,636,638],{"class":30,"line":599},9,[28,601,602],{"class":41},"        function",[28,604,605],{"class":64}," openPr",[28,607,68],{"class":49},[28,609,232],{"class":57},[28,611,235],{"class":49},[28,613,209],{"class":208},[28,615,616],{"class":49},"): ",[28,618,565],{"class":208},[28,620,621],{"class":49},"\u003C{ ",[28,623,624],{"class":57},"number",[28,626,235],{"class":49},[28,628,624],{"class":208},[28,630,520],{"class":49},[28,632,633],{"class":57},"url",[28,635,235],{"class":49},[28,637,209],{"class":208},[28,639,640],{"class":49}," }>\n",[28,642,644],{"class":30,"line":643},10,[28,645,646],{"class":49},"    }\n",[28,648,650],{"class":30,"line":649},11,[28,651,249],{"class":49},[14,653,654],{},"This file mirrors the scope the model receives — same source, same members — so what your editor tells you and what the agent can call never disagree.",[14,656,657,658,660],{},"Run ",[25,659,469],{}," after adding or modifying tool files to refresh types.",[142,662,664],{"id":663},"example-load-state-before-prompting","Example — load state before prompting",[18,666,668],{"className":20,"code":667,"language":22,"meta":23,"style":23},"const issues = await kanban.list({ status: \"open\" })\nconst session = await axon.prompt(\"session\", { issues })\n\nconst { stream } = axon.stream({ prompt: session })\n",[25,669,670,697,724,728],{"__ignoreMap":23},[28,671,672,674,677,679,681,683,685,687,689,692,695],{"class":30,"line":31},[28,673,42],{"class":41},[28,675,676],{"class":45}," issues",[28,678,50],{"class":49},[28,680,54],{"class":53},[28,682,58],{"class":57},[28,684,61],{"class":49},[28,686,65],{"class":64},[28,688,133],{"class":49},[28,690,691],{"class":57},"status:",[28,693,694],{"class":71}," \"open\"",[28,696,109],{"class":49},[28,698,699,701,703,705,707,709,711,713,715,717,719,722],{"class":30,"line":38},[28,700,42],{"class":41},[28,702,83],{"class":45},[28,704,50],{"class":49},[28,706,54],{"class":53},[28,708,90],{"class":57},[28,710,61],{"class":49},[28,712,95],{"class":64},[28,714,68],{"class":49},[28,716,100],{"class":71},[28,718,103],{"class":49},[28,720,721],{"class":57},"issues",[28,723,109],{"class":49},[28,725,726],{"class":30,"line":78},[28,727,545],{"emptyLinePlaceholder":544},[28,729,730,732,734,736,738,740,742,744,746,748,750],{"class":30,"line":112},[28,731,42],{"class":41},[28,733,117],{"class":49},[28,735,120],{"class":45},[28,737,123],{"class":49},[28,739,126],{"class":57},[28,741,61],{"class":49},[28,743,120],{"class":64},[28,745,133],{"class":49},[28,747,136],{"class":57},[28,749,83],{"class":57},[28,751,109],{"class":49},[14,753,754],{},"Loading state explicitly before the prompt is more reliable than letting the agent call the tool itself — you control exactly what data the agent sees.",[756,757,758],"style",{},"html pre.shiki code .sOLPB, html code.shiki .sOLPB{--shiki-default:#6A9955}html pre.shiki code .scz_3, html code.shiki .scz_3{--shiki-default:#569CD6}html pre.shiki code .s9McN, html code.shiki .s9McN{--shiki-default:#4FC1FF}html pre.shiki code .sTNBD, html code.shiki .sTNBD{--shiki-default:#D4D4D4}html pre.shiki code .sYbnZ, html code.shiki .sYbnZ{--shiki-default:#C586C0}html pre.shiki code .s3F5K, html code.shiki .s3F5K{--shiki-default:#9CDCFE}html pre.shiki code .sCudf, html code.shiki .sCudf{--shiki-default:#DCDCAA}html pre.shiki code .sKc5r, html code.shiki .sKc5r{--shiki-default:#CE9178}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html pre.shiki code .sNl3T, html code.shiki .sNl3T{--shiki-default:#4EC9B0}html pre.shiki code .sDGX8, html code.shiki .sDGX8{--shiki-default:#B5CEA8}",{"title":23,"searchDepth":38,"depth":38,"links":760},[761,762,763,764,765,766],{"id":144,"depth":38,"text":145},{"id":154,"depth":38,"text":155},{"id":352,"depth":38,"text":353},{"id":401,"depth":38,"text":402},{"id":463,"depth":38,"text":464},{"id":663,"depth":38,"text":664},"md",{},"\u002Fdocs\u002Fv2\u002Fapi\u002Ftools",{"title":5,"description":16},"docs\u002Fv2\u002Fapi\u002Ftools","3Oua8Bn8Mp570VFpN6qqKAmDBFbsxkRGF7oiN6TCpwQ",1785671808444]