[{"data":1,"prerenderedAt":884},["ShallowReactive",2],{"\u002Fdocs\u002Fcore-concepts\u002Ftools":3},{"id":4,"title":5,"body":6,"description":877,"extension":878,"meta":879,"navigation":72,"path":880,"seo":881,"stem":882,"__hash__":883},"docs\u002Fdocs\u002F2.core-concepts\u002F2.tools.md","Tools",{"type":7,"value":8,"toc":867},"minimark",[9,13,17,22,25,107,112,223,229,236,635,651,655,661,740,744,747,850,854,863],[10,11,5],"h1",{"id":12},"tools",[14,15,16],"p",{},"Tools are the actions the LLM can take. Every tool call is executed by Mango and the result is fed back to the LLM.",[18,19,21],"h2",{"id":20},"built-in-tools","Built-in tools",[14,23,24],{},"Register all built-in MongoDB tools with one call:",[26,27,32],"pre",{"className":28,"code":29,"language":30,"meta":31,"style":31},"language-python shiki shiki-themes github-dark","from mango.tools import build_mongo_tools\nfrom mango.tools.base import ToolRegistry\n\ntools = ToolRegistry()\nfor tool in build_mongo_tools(db):\n    tools.register(tool)\n","python","",[33,34,35,54,67,74,86,101],"code",{"__ignoreMap":31},[36,37,40,44,48,51],"span",{"class":38,"line":39},"line",1,[36,41,43],{"class":42},"snl16","from",[36,45,47],{"class":46},"s95oV"," mango.tools ",[36,49,50],{"class":42},"import",[36,52,53],{"class":46}," build_mongo_tools\n",[36,55,57,59,62,64],{"class":38,"line":56},2,[36,58,43],{"class":42},[36,60,61],{"class":46}," mango.tools.base ",[36,63,50],{"class":42},[36,65,66],{"class":46}," ToolRegistry\n",[36,68,70],{"class":38,"line":69},3,[36,71,73],{"emptyLinePlaceholder":72},true,"\n",[36,75,77,80,83],{"class":38,"line":76},4,[36,78,79],{"class":46},"tools ",[36,81,82],{"class":42},"=",[36,84,85],{"class":46}," ToolRegistry()\n",[36,87,89,92,95,98],{"class":38,"line":88},5,[36,90,91],{"class":42},"for",[36,93,94],{"class":46}," tool ",[36,96,97],{"class":42},"in",[36,99,100],{"class":46}," build_mongo_tools(db):\n",[36,102,104],{"class":38,"line":103},6,[36,105,106],{"class":46},"    tools.register(tool)\n",[108,109,111],"h3",{"id":110},"available-tools","Available tools",[113,114,115,128],"table",{},[116,117,118],"thead",{},[119,120,121,125],"tr",{},[122,123,124],"th",{},"Tool",[122,126,127],{},"Description",[129,130,131,142,160,170,180,203,213],"tbody",{},[119,132,133,139],{},[134,135,136],"td",{},[33,137,138],{},"list_collections",[134,140,141],{},"List all collections. For databases with 100+ collections, returns a grouped view by name pattern.",[119,143,144,149],{},[134,145,146],{},[33,147,148],{},"search_collections",[134,150,151,152,155,156,159],{},"Search collection names by glob pattern (",[33,153,154],{},"order*",", ",[33,157,158],{},"*_log",").",[119,161,162,167],{},[134,163,164],{},[33,165,166],{},"describe_collection",[134,168,169],{},"Return schema, indexes and sample documents for a single collection.",[119,171,172,177],{},[134,173,174],{},[33,175,176],{},"collection_stats",[134,178,179],{},"Document count and storage size for a collection.",[119,181,182,187],{},[134,183,184],{},[33,185,186],{},"run_mql",[134,188,189,190,155,193,155,196,155,199,202],{},"Execute a read-only query: ",[33,191,192],{},"find",[33,194,195],{},"aggregate",[33,197,198],{},"count",[33,200,201],{},"distinct",".",[119,204,205,210],{},[134,206,207],{},[33,208,209],{},"search_saved_correct_tool_uses",[134,211,212],{},"Search memory for similar past interactions (used automatically).",[119,214,215,220],{},[134,216,217],{},[33,218,219],{},"save_text_memory",[134,221,222],{},"Save free-form knowledge about the database.",[108,224,226,228],{"id":225},"run_mql-in-detail",[33,227,186],{}," in detail",[14,230,231,232,235],{},"This is the main query tool. The LLM constructs a ",[33,233,234],{},"QueryRequest"," and passes it as JSON arguments:",[26,237,239],{"className":28,"code":238,"language":30,"meta":31,"style":31},"# find — filter + projection + sort + limit\nrun_mql(\n    operation=\"find\",\n    collection=\"orders\",\n    filter={\"status\": \"delivered\"},\n    projection={\"_id\": 0, \"order_id\": 1, \"total\": 1},\n    sort={\"created_at\": -1},\n    limit=20,\n)\n\n# aggregate — full pipeline\nrun_mql(\n    operation=\"aggregate\",\n    collection=\"orders\",\n    pipeline=[\n        {\"$match\": {\"created_at\": {\"$gte\": \"2026-01-01\"}}},\n        {\"$group\": {\"_id\": \"$user_id\", \"total\": {\"$sum\": \"$amount\"}}},\n        {\"$sort\": {\"total\": -1}},\n        {\"$limit\": 10},\n    ],\n)\n\n# count\nrun_mql(operation=\"count\", collection=\"users\", filter={\"active\": True})\n\n# distinct\nrun_mql(operation=\"distinct\", collection=\"orders\", distinct_field=\"status\")\n",[33,240,241,247,252,267,279,301,340,362,375,381,386,392,397,409,420,431,458,491,512,527,533,538,543,549,593,598,604],{"__ignoreMap":31},[36,242,243],{"class":38,"line":39},[36,244,246],{"class":245},"sAwPA","# find — filter + projection + sort + limit\n",[36,248,249],{"class":38,"line":56},[36,250,251],{"class":46},"run_mql(\n",[36,253,254,258,260,264],{"class":38,"line":69},[36,255,257],{"class":256},"s9osk","    operation",[36,259,82],{"class":42},[36,261,263],{"class":262},"sU2Wk","\"find\"",[36,265,266],{"class":46},",\n",[36,268,269,272,274,277],{"class":38,"line":76},[36,270,271],{"class":256},"    collection",[36,273,82],{"class":42},[36,275,276],{"class":262},"\"orders\"",[36,278,266],{"class":46},[36,280,281,284,286,289,292,295,298],{"class":38,"line":88},[36,282,283],{"class":256},"    filter",[36,285,82],{"class":42},[36,287,288],{"class":46},"{",[36,290,291],{"class":262},"\"status\"",[36,293,294],{"class":46},": ",[36,296,297],{"class":262},"\"delivered\"",[36,299,300],{"class":46},"},\n",[36,302,303,306,308,310,313,315,319,321,324,326,329,331,334,336,338],{"class":38,"line":103},[36,304,305],{"class":256},"    projection",[36,307,82],{"class":42},[36,309,288],{"class":46},[36,311,312],{"class":262},"\"_id\"",[36,314,294],{"class":46},[36,316,318],{"class":317},"sDLfK","0",[36,320,155],{"class":46},[36,322,323],{"class":262},"\"order_id\"",[36,325,294],{"class":46},[36,327,328],{"class":317},"1",[36,330,155],{"class":46},[36,332,333],{"class":262},"\"total\"",[36,335,294],{"class":46},[36,337,328],{"class":317},[36,339,300],{"class":46},[36,341,343,346,348,350,353,355,358,360],{"class":38,"line":342},7,[36,344,345],{"class":256},"    sort",[36,347,82],{"class":42},[36,349,288],{"class":46},[36,351,352],{"class":262},"\"created_at\"",[36,354,294],{"class":46},[36,356,357],{"class":42},"-",[36,359,328],{"class":317},[36,361,300],{"class":46},[36,363,365,368,370,373],{"class":38,"line":364},8,[36,366,367],{"class":256},"    limit",[36,369,82],{"class":42},[36,371,372],{"class":317},"20",[36,374,266],{"class":46},[36,376,378],{"class":38,"line":377},9,[36,379,380],{"class":46},")\n",[36,382,384],{"class":38,"line":383},10,[36,385,73],{"emptyLinePlaceholder":72},[36,387,389],{"class":38,"line":388},11,[36,390,391],{"class":245},"# aggregate — full pipeline\n",[36,393,395],{"class":38,"line":394},12,[36,396,251],{"class":46},[36,398,400,402,404,407],{"class":38,"line":399},13,[36,401,257],{"class":256},[36,403,82],{"class":42},[36,405,406],{"class":262},"\"aggregate\"",[36,408,266],{"class":46},[36,410,412,414,416,418],{"class":38,"line":411},14,[36,413,271],{"class":256},[36,415,82],{"class":42},[36,417,276],{"class":262},[36,419,266],{"class":46},[36,421,423,426,428],{"class":38,"line":422},15,[36,424,425],{"class":256},"    pipeline",[36,427,82],{"class":42},[36,429,430],{"class":46},"[\n",[36,432,434,437,440,443,445,447,450,452,455],{"class":38,"line":433},16,[36,435,436],{"class":46},"        {",[36,438,439],{"class":262},"\"$match\"",[36,441,442],{"class":46},": {",[36,444,352],{"class":262},[36,446,442],{"class":46},[36,448,449],{"class":262},"\"$gte\"",[36,451,294],{"class":46},[36,453,454],{"class":262},"\"2026-01-01\"",[36,456,457],{"class":46},"}}},\n",[36,459,461,463,466,468,470,472,475,477,479,481,484,486,489],{"class":38,"line":460},17,[36,462,436],{"class":46},[36,464,465],{"class":262},"\"$group\"",[36,467,442],{"class":46},[36,469,312],{"class":262},[36,471,294],{"class":46},[36,473,474],{"class":262},"\"$user_id\"",[36,476,155],{"class":46},[36,478,333],{"class":262},[36,480,442],{"class":46},[36,482,483],{"class":262},"\"$sum\"",[36,485,294],{"class":46},[36,487,488],{"class":262},"\"$amount\"",[36,490,457],{"class":46},[36,492,494,496,499,501,503,505,507,509],{"class":38,"line":493},18,[36,495,436],{"class":46},[36,497,498],{"class":262},"\"$sort\"",[36,500,442],{"class":46},[36,502,333],{"class":262},[36,504,294],{"class":46},[36,506,357],{"class":42},[36,508,328],{"class":317},[36,510,511],{"class":46},"}},\n",[36,513,515,517,520,522,525],{"class":38,"line":514},19,[36,516,436],{"class":46},[36,518,519],{"class":262},"\"$limit\"",[36,521,294],{"class":46},[36,523,524],{"class":317},"10",[36,526,300],{"class":46},[36,528,530],{"class":38,"line":529},20,[36,531,532],{"class":46},"    ],\n",[36,534,536],{"class":38,"line":535},21,[36,537,380],{"class":46},[36,539,541],{"class":38,"line":540},22,[36,542,73],{"emptyLinePlaceholder":72},[36,544,546],{"class":38,"line":545},23,[36,547,548],{"class":245},"# count\n",[36,550,552,555,558,560,563,565,568,570,573,575,578,580,582,585,587,590],{"class":38,"line":551},24,[36,553,554],{"class":46},"run_mql(",[36,556,557],{"class":256},"operation",[36,559,82],{"class":42},[36,561,562],{"class":262},"\"count\"",[36,564,155],{"class":46},[36,566,567],{"class":256},"collection",[36,569,82],{"class":42},[36,571,572],{"class":262},"\"users\"",[36,574,155],{"class":46},[36,576,577],{"class":256},"filter",[36,579,82],{"class":42},[36,581,288],{"class":46},[36,583,584],{"class":262},"\"active\"",[36,586,294],{"class":46},[36,588,589],{"class":317},"True",[36,591,592],{"class":46},"})\n",[36,594,596],{"class":38,"line":595},25,[36,597,73],{"emptyLinePlaceholder":72},[36,599,601],{"class":38,"line":600},26,[36,602,603],{"class":245},"# distinct\n",[36,605,607,609,611,613,616,618,620,622,624,626,629,631,633],{"class":38,"line":606},27,[36,608,554],{"class":46},[36,610,557],{"class":256},[36,612,82],{"class":42},[36,614,615],{"class":262},"\"distinct\"",[36,617,155],{"class":46},[36,619,567],{"class":256},[36,621,82],{"class":42},[36,623,276],{"class":262},[36,625,155],{"class":46},[36,627,628],{"class":256},"distinct_field",[36,630,82],{"class":42},[36,632,291],{"class":262},[36,634,380],{"class":46},[14,636,637,641,642,155,644,155,646,155,648,650],{},[638,639,640],"strong",{},"Allowed operations:"," ",[33,643,192],{},[33,645,195],{},[33,647,198],{},[33,649,201],{},". Everything else is rejected.",[18,652,654],{"id":653},"toolresult","ToolResult",[14,656,657,658,660],{},"Every tool returns a ",[33,659,654],{},":",[26,662,664],{"className":28,"code":663,"language":30,"meta":31,"style":31},"@dataclass\nclass ToolResult:\n    success: bool\n    data: Any           # the actual result data\n    error: str | None   # error message if success=False\n\n    def as_text(self) -> str:\n        \"\"\"Serialize result to text for the LLM.\"\"\"\n",[33,665,666,672,683,691,699,716,720,735],{"__ignoreMap":31},[36,667,668],{"class":38,"line":39},[36,669,671],{"class":670},"svObZ","@dataclass\n",[36,673,674,677,680],{"class":38,"line":56},[36,675,676],{"class":42},"class",[36,678,679],{"class":670}," ToolResult",[36,681,682],{"class":46},":\n",[36,684,685,688],{"class":38,"line":69},[36,686,687],{"class":46},"    success: ",[36,689,690],{"class":317},"bool\n",[36,692,693,696],{"class":38,"line":76},[36,694,695],{"class":46},"    data: Any           ",[36,697,698],{"class":245},"# the actual result data\n",[36,700,701,704,707,710,713],{"class":38,"line":88},[36,702,703],{"class":46},"    error: ",[36,705,706],{"class":317},"str",[36,708,709],{"class":42}," |",[36,711,712],{"class":317}," None",[36,714,715],{"class":245},"   # error message if success=False\n",[36,717,718],{"class":38,"line":103},[36,719,73],{"emptyLinePlaceholder":72},[36,721,722,725,728,731,733],{"class":38,"line":342},[36,723,724],{"class":42},"    def",[36,726,727],{"class":670}," as_text",[36,729,730],{"class":46},"(self) -> ",[36,732,706],{"class":317},[36,734,682],{"class":46},[36,736,737],{"class":38,"line":364},[36,738,739],{"class":262},"        \"\"\"Serialize result to text for the LLM.\"\"\"\n",[18,741,743],{"id":742},"toolregistry","ToolRegistry",[14,745,746],{},"The registry manages tool lookup and execution:",[26,748,750],{"className":28,"code":749,"language":30,"meta":31,"style":31},"from mango.tools.base import ToolRegistry\n\ntools = ToolRegistry()\n\n# Register a tool\ntools.register(my_tool)\n\n# Get all tool definitions (for the LLM)\ndefinitions = tools.get_definitions()\n\n# Execute a tool by name\nresult = await tools.execute(\"run_mql\", operation=\"count\", collection=\"users\")\n",[33,751,752,762,766,774,778,783,788,792,797,807,811,816],{"__ignoreMap":31},[36,753,754,756,758,760],{"class":38,"line":39},[36,755,43],{"class":42},[36,757,61],{"class":46},[36,759,50],{"class":42},[36,761,66],{"class":46},[36,763,764],{"class":38,"line":56},[36,765,73],{"emptyLinePlaceholder":72},[36,767,768,770,772],{"class":38,"line":69},[36,769,79],{"class":46},[36,771,82],{"class":42},[36,773,85],{"class":46},[36,775,776],{"class":38,"line":76},[36,777,73],{"emptyLinePlaceholder":72},[36,779,780],{"class":38,"line":88},[36,781,782],{"class":245},"# Register a tool\n",[36,784,785],{"class":38,"line":103},[36,786,787],{"class":46},"tools.register(my_tool)\n",[36,789,790],{"class":38,"line":342},[36,791,73],{"emptyLinePlaceholder":72},[36,793,794],{"class":38,"line":364},[36,795,796],{"class":245},"# Get all tool definitions (for the LLM)\n",[36,798,799,802,804],{"class":38,"line":377},[36,800,801],{"class":46},"definitions ",[36,803,82],{"class":42},[36,805,806],{"class":46}," tools.get_definitions()\n",[36,808,809],{"class":38,"line":383},[36,810,73],{"emptyLinePlaceholder":72},[36,812,813],{"class":38,"line":388},[36,814,815],{"class":245},"# Execute a tool by name\n",[36,817,818,821,823,826,829,832,834,836,838,840,842,844,846,848],{"class":38,"line":394},[36,819,820],{"class":46},"result ",[36,822,82],{"class":42},[36,824,825],{"class":42}," await",[36,827,828],{"class":46}," tools.execute(",[36,830,831],{"class":262},"\"run_mql\"",[36,833,155],{"class":46},[36,835,557],{"class":256},[36,837,82],{"class":42},[36,839,562],{"class":262},[36,841,155],{"class":46},[36,843,567],{"class":256},[36,845,82],{"class":42},[36,847,572],{"class":262},[36,849,380],{"class":46},[18,851,853],{"id":852},"next-step","Next step",[14,855,856,857,862],{},"→ ",[858,859,861],"a",{"href":860},"\u002Fdocs\u002Fadvanced\u002Fcustom-tools","Custom Tools"," — build your own tools and register them alongside the built-ins.",[864,865,866],"style",{},"html pre.shiki code .snl16, html code.shiki .snl16{--shiki-default:#F97583}html pre.shiki code .s95oV, html code.shiki .s95oV{--shiki-default:#E1E4E8}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 .sAwPA, html code.shiki .sAwPA{--shiki-default:#6A737D}html pre.shiki code .s9osk, html code.shiki .s9osk{--shiki-default:#FFAB70}html pre.shiki code .sU2Wk, html code.shiki .sU2Wk{--shiki-default:#9ECBFF}html pre.shiki code .sDLfK, html code.shiki .sDLfK{--shiki-default:#79B8FF}html pre.shiki code .svObZ, html code.shiki .svObZ{--shiki-default:#B392F0}",{"title":31,"searchDepth":56,"depth":56,"links":868},[869,874,875,876],{"id":20,"depth":56,"text":21,"children":870},[871,872],{"id":110,"depth":69,"text":111},{"id":225,"depth":69,"text":873},"run_mql in detail",{"id":653,"depth":56,"text":654},{"id":742,"depth":56,"text":743},{"id":852,"depth":56,"text":853},"Built-in tools and how to register them.","md",{},"\u002Fdocs\u002Fcore-concepts\u002Ftools",{"title":5,"description":877},"docs\u002F2.core-concepts\u002F2.tools","eu-4OpDeGgdxu_cq9H-oS74HLbaVgEv0fquqaVEeKbI",1776189331965]