RubyGems - robot_lab - Versions diffs - 0.1.0 → 0.2.1 - Mend

robot_lab 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (242) hide show

checksums.yaml +4 -4
data/.architecture/AGENTS.md +32 -0
data/.architecture/config.yml +8 -0
data/.architecture/members.yml +60 -0
data/.architecture/reviews/feature-free-will.md +490 -0
data/.architecture/reviews/overall-codebase.md +427 -0
data/.claude/settings.local.json +57 -0
data/.codex/config.toml +2 -0
data/.irbrc +2 -2
data/.rubocop.yml +172 -0
data/CHANGELOG.md +72 -0
data/CLAUDE.md +139 -0
data/README.md +91 -95
data/Rakefile +109 -3
data/agent2agent_review.md +192 -0
data/agentf_improvements.md +253 -0
data/agents.md +14 -0
data/docs/examples/index.md +37 -2
data/docs/getting-started/configuration.md +20 -7
data/docs/guides/index.md +16 -16
data/docs/guides/knowledge.md +7 -1
data/docs/guides/observability.md +132 -0
data/docs/index.md +30 -3
data/docs/superpowers/plans/2026-05-06-agentskills.md +1303 -0
data/docs/superpowers/specs/2026-05-06-agentskills-design.md +247 -0
data/examples/.envrc +1 -0
data/examples/01_simple_robot.rb +5 -9
data/examples/02_tools.rb +5 -9
data/examples/03_network.rb +8 -9
data/examples/04_mcp.rb +21 -29
data/examples/05_streaming.rb +12 -18
data/examples/06_prompt_templates.rb +11 -19
data/examples/07_network_memory.rb +16 -31
data/examples/08_llm_config.rb +10 -22
data/examples/09_chaining.rb +16 -27
data/examples/10_memory.rb +12 -28
data/examples/11_network_introspection.rb +15 -29
data/examples/12_message_bus.rb +5 -12
data/examples/13_spawn.rb +5 -10
data/examples/14_rusty_circuit/.envrc +1 -0
data/examples/14_rusty_circuit/comic.rb +2 -0
data/examples/14_rusty_circuit/heckler.rb +1 -1
data/examples/14_rusty_circuit/open_mic.rb +1 -3
data/examples/14_rusty_circuit/scout.rb +2 -0
data/examples/15_memory_network_and_bus/.envrc +1 -0
data/examples/15_memory_network_and_bus/editorial_pipeline.rb +6 -3
data/examples/15_memory_network_and_bus/linux_writer.rb +1 -1
data/examples/15_memory_network_and_bus/output/combined_article.md +6 -6
data/examples/15_memory_network_and_bus/output/final_article.md +6 -8
data/examples/15_memory_network_and_bus/output/linux_draft.md +4 -2
data/examples/15_memory_network_and_bus/output/mac_draft.md +3 -3
data/examples/15_memory_network_and_bus/output/memory.json +6 -6
data/examples/15_memory_network_and_bus/output/revision_1.md +10 -11
data/examples/15_memory_network_and_bus/output/revision_2.md +6 -8
data/examples/15_memory_network_and_bus/output/windows_draft.md +3 -3
data/examples/16_writers_room/.envrc +1 -0
data/examples/16_writers_room/writers_room.rb +2 -4
data/examples/17_skills.rb +8 -17
data/examples/18_rails/Gemfile +1 -0
data/examples/19_token_tracking.rb +9 -15
data/examples/20_circuit_breaker.rb +10 -19
data/examples/21_learning_loop.rb +11 -20
data/examples/22_context_compression.rb +6 -13
data/examples/23_convergence.rb +6 -17
data/examples/24_structured_delegation.rb +11 -15
data/examples/25_history_search.rb +5 -12
data/examples/26_document_store.rb +6 -13
data/examples/27_incident_response/incident_response.rb +4 -5
data/examples/28_mcp_discovery.rb +8 -11
data/examples/29_ractor_tools.rb +4 -9
data/examples/30_ractor_network.rb +10 -19
data/examples/31_launch_assessment.rb +10 -23
data/examples/32_newsletter_reader.rb +188 -0
data/examples/33_stock_generator.rb +80 -0
data/examples/33_stock_predictor.rb +306 -0
data/examples/34_agentskills.rb +72 -0
data/examples/README.md +1 -1
data/examples/common.rb +76 -0
data/examples/ruboruby.md +423 -0
data/examples/temp.md +51 -0
data/lib/robot_lab/agent_skill.rb +63 -0
data/lib/robot_lab/agent_skill_catalog.rb +74 -0
data/lib/robot_lab/ask_user.rb +2 -2
data/lib/robot_lab/bus_poller.rb +12 -5
data/lib/robot_lab/config.rb +1 -12
data/lib/robot_lab/delegation_future.rb +1 -1
data/lib/robot_lab/doom_loop_detector.rb +98 -0
data/lib/robot_lab/history_compressor.rb +4 -10
data/lib/robot_lab/mcp/client.rb +1 -2
data/lib/robot_lab/mcp/connection_poller.rb +3 -3
data/lib/robot_lab/mcp/server.rb +1 -1
data/lib/robot_lab/mcp/server_discovery.rb +0 -2
data/lib/robot_lab/memory.rb +32 -27
data/lib/robot_lab/memory_change.rb +2 -2
data/lib/robot_lab/message.rb +4 -4
data/lib/robot_lab/network.rb +11 -6
data/lib/robot_lab/robot/agent_skill_matching.rb +99 -0
data/lib/robot_lab/robot/bus_messaging.rb +9 -27
data/lib/robot_lab/robot/history_search.rb +4 -1
data/lib/robot_lab/robot/mcp_management.rb +5 -11
data/lib/robot_lab/robot/template_rendering.rb +60 -40
data/lib/robot_lab/robot.rb +323 -206
data/lib/robot_lab/robot_result.rb +6 -5
data/lib/robot_lab/run_config.rb +5 -11
data/lib/robot_lab/script_tool.rb +76 -0
data/lib/robot_lab/state_proxy.rb +7 -5
data/lib/robot_lab/tool.rb +3 -3
data/lib/robot_lab/tool_config.rb +1 -1
data/lib/robot_lab/tool_manifest.rb +5 -7
data/lib/robot_lab/user_message.rb +2 -2
data/lib/robot_lab/version.rb +1 -1
data/lib/robot_lab/waiter.rb +1 -1
data/lib/robot_lab.rb +41 -52
data/logfile +8 -0
data/mkdocs.yml +2 -3
data/robot_concurrency.md +38 -0
data/simple_acp_review.md +298 -0
data/site/404.html +2300 -0
data/site/api/core/index.html +2706 -0
data/site/api/core/memory/index.html +3793 -0
data/site/api/core/network/index.html +3500 -0
data/site/api/core/robot/index.html +4566 -0
data/site/api/core/state/index.html +3390 -0
data/site/api/core/tool/index.html +3843 -0
data/site/api/index.html +2635 -0
data/site/api/mcp/client/index.html +3435 -0
data/site/api/mcp/index.html +2783 -0
data/site/api/mcp/server/index.html +3252 -0
data/site/api/mcp/transports/index.html +3352 -0
data/site/api/messages/index.html +2641 -0
data/site/api/messages/text-message/index.html +3087 -0
data/site/api/messages/tool-call-message/index.html +3159 -0
data/site/api/messages/tool-result-message/index.html +3252 -0
data/site/api/messages/user-message/index.html +3212 -0
data/site/api/streaming/context/index.html +3282 -0
data/site/api/streaming/events/index.html +3347 -0
data/site/api/streaming/index.html +2738 -0
data/site/architecture/core-concepts/index.html +3757 -0
data/site/architecture/index.html +2797 -0
data/site/architecture/message-flow/index.html +3238 -0
data/site/architecture/network-orchestration/index.html +3433 -0
data/site/architecture/robot-execution/index.html +3140 -0
data/site/architecture/state-management/index.html +3498 -0
data/site/assets/css/custom.css +56 -0
data/site/assets/images/favicon.png +0 -0
data/site/assets/images/robot_lab.jpg +0 -0
data/site/assets/javascripts/bundle.79ae519e.min.js +16 -0
data/site/assets/javascripts/bundle.79ae519e.min.js.map +7 -0
data/site/assets/javascripts/lunr/min/lunr.ar.min.js +1 -0
data/site/assets/javascripts/lunr/min/lunr.da.min.js +18 -0
data/site/assets/javascripts/lunr/min/lunr.de.min.js +18 -0
data/site/assets/javascripts/lunr/min/lunr.du.min.js +18 -0
data/site/assets/javascripts/lunr/min/lunr.el.min.js +1 -0
data/site/assets/javascripts/lunr/min/lunr.es.min.js +18 -0
data/site/assets/javascripts/lunr/min/lunr.fi.min.js +18 -0
data/site/assets/javascripts/lunr/min/lunr.fr.min.js +18 -0
data/site/assets/javascripts/lunr/min/lunr.he.min.js +1 -0
data/site/assets/javascripts/lunr/min/lunr.hi.min.js +1 -0
data/site/assets/javascripts/lunr/min/lunr.hu.min.js +18 -0
data/site/assets/javascripts/lunr/min/lunr.hy.min.js +1 -0
data/site/assets/javascripts/lunr/min/lunr.it.min.js +18 -0
data/site/assets/javascripts/lunr/min/lunr.ja.min.js +1 -0
data/site/assets/javascripts/lunr/min/lunr.jp.min.js +1 -0
data/site/assets/javascripts/lunr/min/lunr.kn.min.js +1 -0
data/site/assets/javascripts/lunr/min/lunr.ko.min.js +1 -0
data/site/assets/javascripts/lunr/min/lunr.multi.min.js +1 -0
data/site/assets/javascripts/lunr/min/lunr.nl.min.js +18 -0
data/site/assets/javascripts/lunr/min/lunr.no.min.js +18 -0
data/site/assets/javascripts/lunr/min/lunr.pt.min.js +18 -0
data/site/assets/javascripts/lunr/min/lunr.ro.min.js +18 -0
data/site/assets/javascripts/lunr/min/lunr.ru.min.js +18 -0
data/site/assets/javascripts/lunr/min/lunr.sa.min.js +1 -0
data/site/assets/javascripts/lunr/min/lunr.stemmer.support.min.js +1 -0
data/site/assets/javascripts/lunr/min/lunr.sv.min.js +18 -0
data/site/assets/javascripts/lunr/min/lunr.ta.min.js +1 -0
data/site/assets/javascripts/lunr/min/lunr.te.min.js +1 -0
data/site/assets/javascripts/lunr/min/lunr.th.min.js +1 -0
data/site/assets/javascripts/lunr/min/lunr.tr.min.js +18 -0
data/site/assets/javascripts/lunr/min/lunr.vi.min.js +1 -0
data/site/assets/javascripts/lunr/min/lunr.zh.min.js +1 -0
data/site/assets/javascripts/lunr/tinyseg.js +206 -0
data/site/assets/javascripts/lunr/wordcut.js +6708 -0
data/site/assets/javascripts/workers/search.2c215733.min.js +42 -0
data/site/assets/javascripts/workers/search.2c215733.min.js.map +7 -0
data/site/assets/stylesheets/main.484c7ddc.min.css +1 -0
data/site/assets/stylesheets/main.484c7ddc.min.css.map +1 -0
data/site/assets/stylesheets/palette.ab4e12ef.min.css +1 -0
data/site/assets/stylesheets/palette.ab4e12ef.min.css.map +1 -0
data/site/concepts/index.html +3455 -0
data/site/examples/basic-chat/index.html +2880 -0
data/site/examples/index.html +2907 -0
data/site/examples/mcp-server/index.html +3018 -0
data/site/examples/multi-robot-network/index.html +3131 -0
data/site/examples/rails-application/index.html +3329 -0
data/site/examples/tool-usage/index.html +3085 -0
data/site/getting-started/configuration/index.html +3745 -0
data/site/getting-started/index.html +2572 -0
data/site/getting-started/installation/index.html +2981 -0
data/site/getting-started/quick-start/index.html +2942 -0
data/site/guides/building-robots/index.html +4290 -0
data/site/guides/creating-networks/index.html +3858 -0
data/site/guides/index.html +2586 -0
data/site/guides/mcp-integration/index.html +3581 -0
data/site/guides/memory/index.html +3586 -0
data/site/guides/rails-integration/index.html +4019 -0
data/site/guides/streaming/index.html +3157 -0
data/site/guides/using-tools/index.html +3802 -0
data/site/index.html +2671 -0
data/site/search/search_index.json +1 -0
data/site/sitemap.xml +183 -0
data/site/sitemap.xml.gz +0 -0
data/site/tags.json +1 -0
data/temp.md +6 -0
data/tool_manifest_plan.md +155 -0
metadata +154 -92
data/docs/examples/rails-application.md +0 -419
data/docs/guides/ractor-parallelism.md +0 -364
data/docs/guides/rails-integration.md +0 -681
data/docs/superpowers/plans/2026-04-14-ractor-integration.md +0 -1538
data/docs/superpowers/specs/2026-04-14-ractor-integration-design.md +0 -258
data/lib/generators/robot_lab/install_generator.rb +0 -90
data/lib/generators/robot_lab/job_generator.rb +0 -40
data/lib/generators/robot_lab/robot_generator.rb +0 -55
data/lib/generators/robot_lab/templates/initializer.rb.tt +0 -42
data/lib/generators/robot_lab/templates/job.rb.tt +0 -21
data/lib/generators/robot_lab/templates/migration.rb.tt +0 -32
data/lib/generators/robot_lab/templates/result_model.rb.tt +0 -52
data/lib/generators/robot_lab/templates/robot.rb.tt +0 -31
data/lib/generators/robot_lab/templates/robot_job.rb.tt +0 -18
data/lib/generators/robot_lab/templates/robot_test.rb.tt +0 -34
data/lib/generators/robot_lab/templates/routing_robot.rb.tt +0 -59
data/lib/generators/robot_lab/templates/thread_model.rb.tt +0 -40
data/lib/robot_lab/document_store.rb +0 -155
data/lib/robot_lab/ractor_boundary.rb +0 -42
data/lib/robot_lab/ractor_job.rb +0 -37
data/lib/robot_lab/ractor_memory_proxy.rb +0 -85
data/lib/robot_lab/ractor_network_scheduler.rb +0 -154
data/lib/robot_lab/ractor_worker_pool.rb +0 -117
data/lib/robot_lab/rails_integration/engine.rb +0 -29
data/lib/robot_lab/rails_integration/job.rb +0 -158
data/lib/robot_lab/rails_integration/railtie.rb +0 -51
data/lib/robot_lab/rails_integration/turbo_stream_callbacks.rb +0 -72

data/site/guides/using-tools/index.html ADDED Viewed

@@ -0,0 +1,3802 @@
+<!doctype html>
+<html lang="en" class="no-js">
+  <head>
+      <meta charset="utf-8">
+      <meta name="viewport" content="width=device-width,initial-scale=1">
+        <meta name="description" content="Multi-robot LLM workflow orchestration for Ruby">
+        <meta name="author" content="Dewayne VanHoozer">
+        <link rel="canonical" href="https://madbomber.github.io/robot_lab/guides/using-tools/">
+        <link rel="prev" href="../creating-networks/">
+        <link rel="next" href="../mcp-integration/">
+      <link rel="icon" href="../../assets/images/favicon.png">
+      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.1">
+        <title>Using Tools - RobotLab</title>
+      <link rel="stylesheet" href="../../assets/stylesheets/main.484c7ddc.min.css">
+        <link rel="stylesheet" href="../../assets/stylesheets/palette.ab4e12ef.min.css">
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+        <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
+        <style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
+      <link rel="stylesheet" href="../../assets/css/custom.css">
+    <script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
+  </head>
+    <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="deep-purple" data-md-color-accent="amber">
+    <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
+    <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
+    <label class="md-overlay" for="__drawer"></label>
+    <div data-md-component="skip">
+        <a href="#using-tools" class="md-skip">
+          Skip to content
+        </a>
+    </div>
+    <div data-md-component="announce">
+    </div>
+<header class="md-header md-header--shadow md-header--lifted" data-md-component="header">
+  <nav class="md-header__inner md-grid" aria-label="Header">
+    <a href="../.." title="RobotLab" class="md-header__button md-logo" aria-label="RobotLab" data-md-component="logo">
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2a2 2 0 0 1 2 2c0 .74-.4 1.39-1 1.73V7h1a7 7 0 0 1 7 7h1a1 1 0 0 1 1 1v3a1 1 0 0 1-1 1h-1v1a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-1H2a1 1 0 0 1-1-1v-3a1 1 0 0 1 1-1h1a7 7 0 0 1 7-7h1V5.73c-.6-.34-1-.99-1-1.73a2 2 0 0 1 2-2M7.5 13A2.5 2.5 0 0 0 5 15.5 2.5 2.5 0 0 0 7.5 18a2.5 2.5 0 0 0 2.5-2.5A2.5 2.5 0 0 0 7.5 13m9 0a2.5 2.5 0 0 0-2.5 2.5 2.5 2.5 0 0 0 2.5 2.5 2.5 2.5 0 0 0 2.5-2.5 2.5 2.5 0 0 0-2.5-2.5"/></svg>
+    </a>
+    <label class="md-header__button md-icon" for="__drawer">
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>
+    </label>
+    <div class="md-header__title" data-md-component="header-title">
+      <div class="md-header__ellipsis">
+        <div class="md-header__topic">
+          <span class="md-ellipsis">
+            RobotLab
+          </span>
+        </div>
+        <div class="md-header__topic" data-md-component="header-topic">
+          <span class="md-ellipsis">
+              Using Tools
+          </span>
+        </div>
+      </div>
+    </div>
+        <form class="md-header__option" data-md-component="palette">
+    <input class="md-option" data-md-color-media="" data-md-color-scheme="default" data-md-color-primary="deep-purple" data-md-color-accent="amber"  aria-label="Switch to dark mode"  type="radio" name="__palette" id="__palette_0">
+      <label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_1" hidden>
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg>
+      </label>
+    <input class="md-option" data-md-color-media="" data-md-color-scheme="slate" data-md-color-primary="deep-purple" data-md-color-accent="amber"  aria-label="Switch to light mode"  type="radio" name="__palette" id="__palette_1">
+      <label class="md-header__button md-icon" title="Switch to light mode" for="__palette_0" hidden>
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg>
+      </label>
+</form>
+      <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
+        <label class="md-header__button md-icon" for="__search">
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
+        </label>
+        <div class="md-search" data-md-component="search" role="dialog">
+  <label class="md-search__overlay" for="__search"></label>
+  <div class="md-search__inner" role="search">
+    <form class="md-search__form" name="search">
+      <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
+      <label class="md-search__icon md-icon" for="__search">
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
+      </label>
+      <nav class="md-search__options" aria-label="Search">
+          <a href="javascript:void(0)" class="md-search__icon md-icon" title="Share" aria-label="Share" data-clipboard data-clipboard-text="" data-md-component="search-share" tabindex="-1">
+            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18 16.08c-.76 0-1.44.3-1.96.77L8.91 12.7c.05-.23.09-.46.09-.7s-.04-.47-.09-.7l7.05-4.11c.54.5 1.25.81 2.04.81a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3c0 .24.04.47.09.7L8.04 9.81C7.5 9.31 6.79 9 6 9a3 3 0 0 0-3 3 3 3 0 0 0 3 3c.79 0 1.5-.31 2.04-.81l7.12 4.15c-.05.21-.08.43-.08.66 0 1.61 1.31 2.91 2.92 2.91s2.92-1.3 2.92-2.91A2.92 2.92 0 0 0 18 16.08"/></svg>
+          </a>
+        <button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>
+        </button>
+      </nav>
+        <div class="md-search__suggest" data-md-component="search-suggest"></div>
+    </form>
+    <div class="md-search__output">
+      <div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
+        <div class="md-search-result" data-md-component="search-result">
+          <div class="md-search-result__meta">
+            Initializing search
+          </div>
+          <ol class="md-search-result__list" role="presentation"></ol>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+      <div class="md-header__source">
+        <a href="https://github.com/madbomber/robot_lab" title="Go to repository" class="md-source" data-md-component="source">
+  <div class="md-source__icon md-icon">
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg>
+  </div>
+  <div class="md-source__repository">
+    madbomber/robot_lab
+  </div>
+</a>
+      </div>
+  </nav>
+<nav class="md-tabs" aria-label="Tabs" data-md-component="tabs">
+  <div class="md-grid">
+    <ul class="md-tabs__list">
+      <li class="md-tabs__item">
+        <a href="../.." class="md-tabs__link">
+  Home
+        </a>
+      </li>
+      <li class="md-tabs__item">
+        <a href="../../getting-started/" class="md-tabs__link">
+  Getting Started
+        </a>
+      </li>
+      <li class="md-tabs__item">
+        <a href="../../architecture/" class="md-tabs__link">
+  Architecture
+        </a>
+      </li>
+      <li class="md-tabs__item md-tabs__item--active">
+        <a href="../" class="md-tabs__link">
+  Guides
+        </a>
+      </li>
+      <li class="md-tabs__item">
+        <a href="../../api/" class="md-tabs__link">
+  API Reference
+        </a>
+      </li>
+      <li class="md-tabs__item">
+        <a href="../../examples/" class="md-tabs__link">
+  Examples
+        </a>
+      </li>
+    </ul>
+  </div>
+</nav>
+</header>
+    <div class="md-container" data-md-component="container">
+      <main class="md-main" data-md-component="main">
+        <div class="md-main__inner md-grid">
+              <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
+                <div class="md-sidebar__scrollwrap">
+                  <div class="md-sidebar__inner">
+<nav class="md-nav md-nav--primary md-nav--lifted" aria-label="Navigation" data-md-level="0">
+  <label class="md-nav__title" for="__drawer">
+    <a href="../.." title="RobotLab" class="md-nav__button md-logo" aria-label="RobotLab" data-md-component="logo">
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2a2 2 0 0 1 2 2c0 .74-.4 1.39-1 1.73V7h1a7 7 0 0 1 7 7h1a1 1 0 0 1 1 1v3a1 1 0 0 1-1 1h-1v1a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-1H2a1 1 0 0 1-1-1v-3a1 1 0 0 1 1-1h1a7 7 0 0 1 7-7h1V5.73c-.6-.34-1-.99-1-1.73a2 2 0 0 1 2-2M7.5 13A2.5 2.5 0 0 0 5 15.5 2.5 2.5 0 0 0 7.5 18a2.5 2.5 0 0 0 2.5-2.5A2.5 2.5 0 0 0 7.5 13m9 0a2.5 2.5 0 0 0-2.5 2.5 2.5 2.5 0 0 0 2.5 2.5 2.5 2.5 0 0 0 2.5-2.5 2.5 2.5 0 0 0-2.5-2.5"/></svg>
+    </a>
+    RobotLab
+  </label>
+    <div class="md-nav__source">
+      <a href="https://github.com/madbomber/robot_lab" title="Go to repository" class="md-source" data-md-component="source">
+  <div class="md-source__icon md-icon">
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg>
+  </div>
+  <div class="md-source__repository">
+    madbomber/robot_lab
+  </div>
+</a>
+    </div>
+  <ul class="md-nav__list" data-md-scrollfix>
+    <li class="md-nav__item md-nav__item--nested">
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_1" >
+          <div class="md-nav__link md-nav__container">
+            <a href="../.." class="md-nav__link ">
+  <span class="md-ellipsis">
+    Home
+  </span>
+            </a>
+              <label class="md-nav__link " for="__nav_1" id="__nav_1_label" tabindex="0">
+                <span class="md-nav__icon md-icon"></span>
+              </label>
+          </div>
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_1_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_1">
+            <span class="md-nav__icon md-icon"></span>
+    Home
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+    <li class="md-nav__item">
+      <a href="../../concepts/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Concepts
+  </span>
+      </a>
+    </li>
+          </ul>
+        </nav>
+    </li>
+    <li class="md-nav__item md-nav__item--nested">
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2" >
+          <div class="md-nav__link md-nav__container">
+            <a href="../../getting-started/" class="md-nav__link ">
+  <span class="md-ellipsis">
+    Getting Started
+  </span>
+            </a>
+              <label class="md-nav__link " for="__nav_2" id="__nav_2_label" tabindex="0">
+                <span class="md-nav__icon md-icon"></span>
+              </label>
+          </div>
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_2">
+            <span class="md-nav__icon md-icon"></span>
+    Getting Started
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+    <li class="md-nav__item">
+      <a href="../../getting-started/installation/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Installation
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../getting-started/quick-start/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Quick Start
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../getting-started/configuration/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Configuration
+  </span>
+      </a>
+    </li>
+          </ul>
+        </nav>
+    </li>
+    <li class="md-nav__item md-nav__item--nested">
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" >
+          <div class="md-nav__link md-nav__container">
+            <a href="../../architecture/" class="md-nav__link ">
+  <span class="md-ellipsis">
+    Architecture
+  </span>
+            </a>
+              <label class="md-nav__link " for="__nav_3" id="__nav_3_label" tabindex="0">
+                <span class="md-nav__icon md-icon"></span>
+              </label>
+          </div>
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_3">
+            <span class="md-nav__icon md-icon"></span>
+    Architecture
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+    <li class="md-nav__item">
+      <a href="../../architecture/core-concepts/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Core Concepts
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../architecture/robot-execution/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Robot Execution
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../architecture/network-orchestration/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Network Orchestration
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../architecture/state-management/" class="md-nav__link">
+  <span class="md-ellipsis">
+    State Management
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../architecture/message-flow/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Message Flow
+  </span>
+      </a>
+    </li>
+          </ul>
+        </nav>
+    </li>
+    <li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" checked>
+          <div class="md-nav__link md-nav__container">
+            <a href="../" class="md-nav__link ">
+  <span class="md-ellipsis">
+    Guides
+  </span>
+            </a>
+              <label class="md-nav__link " for="__nav_4" id="__nav_4_label" tabindex="">
+                <span class="md-nav__icon md-icon"></span>
+              </label>
+          </div>
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="true">
+          <label class="md-nav__title" for="__nav_4">
+            <span class="md-nav__icon md-icon"></span>
+    Guides
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+    <li class="md-nav__item">
+      <a href="../building-robots/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Building Robots
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../creating-networks/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Creating Networks
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item md-nav__item--active">
+      <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
+        <label class="md-nav__link md-nav__link--active" for="__toc">
+  <span class="md-ellipsis">
+    Using Tools
+  </span>
+          <span class="md-nav__icon md-icon"></span>
+        </label>
+      <a href="./" class="md-nav__link md-nav__link--active">
+  <span class="md-ellipsis">
+    Using Tools
+  </span>
+      </a>
+<nav class="md-nav md-nav--secondary" aria-label="On this page">
+    <label class="md-nav__title" for="__toc">
+      <span class="md-nav__icon md-icon"></span>
+      On this page
+    </label>
+    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
+        <li class="md-nav__item">
+  <a href="#defining-tools" class="md-nav__link">
+    <span class="md-ellipsis">
+        Defining Tools
+    </span>
+  </a>
+    <nav class="md-nav" aria-label="Defining Tools">
+      <ul class="md-nav__list">
+          <li class="md-nav__item">
+  <a href="#rubyllmtool-subclass" class="md-nav__link">
+    <span class="md-ellipsis">
+        RubyLLM::Tool Subclass
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#robotlabtool-subclass" class="md-nav__link">
+    <span class="md-ellipsis">
+        RobotLab::Tool Subclass
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#robotlabtoolcreate-dynamic-tools" class="md-nav__link">
+    <span class="md-ellipsis">
+        RobotLab::Tool.create (Dynamic Tools)
+    </span>
+  </a>
+</li>
+      </ul>
+    </nav>
+</li>
+        <li class="md-nav__item">
+  <a href="#built-in-tools" class="md-nav__link">
+    <span class="md-ellipsis">
+        Built-in Tools
+    </span>
+  </a>
+    <nav class="md-nav" aria-label="Built-in Tools">
+      <ul class="md-nav__list">
+          <li class="md-nav__item">
+  <a href="#askuser" class="md-nav__link">
+    <span class="md-ellipsis">
+        AskUser
+    </span>
+  </a>
+</li>
+      </ul>
+    </nav>
+</li>
+        <li class="md-nav__item">
+  <a href="#attaching-tools-to-robots" class="md-nav__link">
+    <span class="md-ellipsis">
+        Attaching Tools to Robots
+    </span>
+  </a>
+    <nav class="md-nav" aria-label="Attaching Tools to Robots">
+      <ul class="md-nav__list">
+          <li class="md-nav__item">
+  <a href="#via-constructor" class="md-nav__link">
+    <span class="md-ellipsis">
+        Via Constructor
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#via-template-front-matter" class="md-nav__link">
+    <span class="md-ellipsis">
+        Via Template Front Matter
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#via-chaining" class="md-nav__link">
+    <span class="md-ellipsis">
+        Via Chaining
+    </span>
+  </a>
+</li>
+      </ul>
+    </nav>
+</li>
+        <li class="md-nav__item">
+  <a href="#parameter-types" class="md-nav__link">
+    <span class="md-ellipsis">
+        Parameter Types
+    </span>
+  </a>
+    <nav class="md-nav" aria-label="Parameter Types">
+      <ul class="md-nav__list">
+          <li class="md-nav__item">
+  <a href="#string" class="md-nav__link">
+    <span class="md-ellipsis">
+        String
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#integer" class="md-nav__link">
+    <span class="md-ellipsis">
+        Integer
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#number-float" class="md-nav__link">
+    <span class="md-ellipsis">
+        Number (Float)
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#boolean" class="md-nav__link">
+    <span class="md-ellipsis">
+        Boolean
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#array" class="md-nav__link">
+    <span class="md-ellipsis">
+        Array
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#enum" class="md-nav__link">
+    <span class="md-ellipsis">
+        Enum
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#required-vs-optional" class="md-nav__link">
+    <span class="md-ellipsis">
+        Required vs Optional
+    </span>
+  </a>
+</li>
+      </ul>
+    </nav>
+</li>
+        <li class="md-nav__item">
+  <a href="#tool-patterns" class="md-nav__link">
+    <span class="md-ellipsis">
+        Tool Patterns
+    </span>
+  </a>
+    <nav class="md-nav" aria-label="Tool Patterns">
+      <ul class="md-nav__list">
+          <li class="md-nav__item">
+  <a href="#database-lookup" class="md-nav__link">
+    <span class="md-ellipsis">
+        Database Lookup
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#api-integration" class="md-nav__link">
+    <span class="md-ellipsis">
+        API Integration
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#file-operations" class="md-nav__link">
+    <span class="md-ellipsis">
+        File Operations
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#multi-step-operations" class="md-nav__link">
+    <span class="md-ellipsis">
+        Multi-Step Operations
+    </span>
+  </a>
+</li>
+      </ul>
+    </nav>
+</li>
+        <li class="md-nav__item">
+  <a href="#tool-return-values" class="md-nav__link">
+    <span class="md-ellipsis">
+        Tool Return Values
+    </span>
+  </a>
+    <nav class="md-nav" aria-label="Tool Return Values">
+      <ul class="md-nav__list">
+          <li class="md-nav__item">
+  <a href="#structured-data" class="md-nav__link">
+    <span class="md-ellipsis">
+        Structured Data
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#simple-values" class="md-nav__link">
+    <span class="md-ellipsis">
+        Simple Values
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#lists" class="md-nav__link">
+    <span class="md-ellipsis">
+        Lists
+    </span>
+  </a>
+</li>
+      </ul>
+    </nav>
+</li>
+        <li class="md-nav__item">
+  <a href="#error-handling" class="md-nav__link">
+    <span class="md-ellipsis">
+        Error Handling
+    </span>
+  </a>
+    <nav class="md-nav" aria-label="Error Handling">
+      <ul class="md-nav__list">
+          <li class="md-nav__item">
+  <a href="#automatic-error-handling" class="md-nav__link">
+    <span class="md-ellipsis">
+        Automatic Error Handling
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#critical-tools-opt-out" class="md-nav__link">
+    <span class="md-ellipsis">
+        Critical Tools (Opt-Out)
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#manual-error-handling" class="md-nav__link">
+    <span class="md-ellipsis">
+        Manual Error Handling
+    </span>
+  </a>
+</li>
+      </ul>
+    </nav>
+</li>
+        <li class="md-nav__item">
+  <a href="#tool-callbacks" class="md-nav__link">
+    <span class="md-ellipsis">
+        Tool Callbacks
+    </span>
+  </a>
+</li>
+        <li class="md-nav__item">
+  <a href="#robotlabtoolcreate-with-schema" class="md-nav__link">
+    <span class="md-ellipsis">
+        RobotLab::Tool.create with Schema
+    </span>
+  </a>
+</li>
+        <li class="md-nav__item">
+  <a href="#best-practices" class="md-nav__link">
+    <span class="md-ellipsis">
+        Best Practices
+    </span>
+  </a>
+    <nav class="md-nav" aria-label="Best Practices">
+      <ul class="md-nav__list">
+          <li class="md-nav__item">
+  <a href="#1-clear-descriptions" class="md-nav__link">
+    <span class="md-ellipsis">
+        1. Clear Descriptions
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#2-validate-inputs" class="md-nav__link">
+    <span class="md-ellipsis">
+        2. Validate Inputs
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#3-return-structured-data" class="md-nav__link">
+    <span class="md-ellipsis">
+        3. Return Structured Data
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#4-keep-tools-focused" class="md-nav__link">
+    <span class="md-ellipsis">
+        4. Keep Tools Focused
+    </span>
+  </a>
+</li>
+      </ul>
+    </nav>
+</li>
+        <li class="md-nav__item">
+  <a href="#next-steps" class="md-nav__link">
+    <span class="md-ellipsis">
+        Next Steps
+    </span>
+  </a>
+</li>
+    </ul>
+</nav>
+    </li>
+    <li class="md-nav__item">
+      <a href="../mcp-integration/" class="md-nav__link">
+  <span class="md-ellipsis">
+    MCP Integration
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../streaming/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Streaming Responses
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../memory/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Memory System
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../rails-integration/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Rails Integration
+  </span>
+      </a>
+    </li>
+          </ul>
+        </nav>
+    </li>
+    <li class="md-nav__item md-nav__item--nested">
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5" >
+          <div class="md-nav__link md-nav__container">
+            <a href="../../api/" class="md-nav__link ">
+  <span class="md-ellipsis">
+    API Reference
+  </span>
+            </a>
+              <label class="md-nav__link " for="__nav_5" id="__nav_5_label" tabindex="0">
+                <span class="md-nav__icon md-icon"></span>
+              </label>
+          </div>
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_5">
+            <span class="md-nav__icon md-icon"></span>
+    API Reference
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+    <li class="md-nav__item md-nav__item--nested">
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5_2" >
+          <div class="md-nav__link md-nav__container">
+            <a href="../../api/core/" class="md-nav__link ">
+  <span class="md-ellipsis">
+    Core Classes
+  </span>
+            </a>
+              <label class="md-nav__link " for="__nav_5_2" id="__nav_5_2_label" tabindex="0">
+                <span class="md-nav__icon md-icon"></span>
+              </label>
+          </div>
+        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_5_2_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_5_2">
+            <span class="md-nav__icon md-icon"></span>
+    Core Classes
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+    <li class="md-nav__item">
+      <a href="../../api/core/robot/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Robot
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../api/core/network/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Network
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../api/core/state/" class="md-nav__link">
+  <span class="md-ellipsis">
+    State
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../api/core/tool/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Tool
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../api/core/memory/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Memory
+  </span>
+      </a>
+    </li>
+          </ul>
+        </nav>
+    </li>
+    <li class="md-nav__item md-nav__item--nested">
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5_3" >
+          <div class="md-nav__link md-nav__container">
+            <a href="../../api/messages/" class="md-nav__link ">
+  <span class="md-ellipsis">
+    Messages
+  </span>
+            </a>
+              <label class="md-nav__link " for="__nav_5_3" id="__nav_5_3_label" tabindex="0">
+                <span class="md-nav__icon md-icon"></span>
+              </label>
+          </div>
+        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_5_3_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_5_3">
+            <span class="md-nav__icon md-icon"></span>
+    Messages
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+    <li class="md-nav__item">
+      <a href="../../api/messages/user-message/" class="md-nav__link">
+  <span class="md-ellipsis">
+    UserMessage
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../api/messages/text-message/" class="md-nav__link">
+  <span class="md-ellipsis">
+    TextMessage
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../api/messages/tool-call-message/" class="md-nav__link">
+  <span class="md-ellipsis">
+    ToolCallMessage
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../api/messages/tool-result-message/" class="md-nav__link">
+  <span class="md-ellipsis">
+    ToolResultMessage
+  </span>
+      </a>
+    </li>
+          </ul>
+        </nav>
+    </li>
+    <li class="md-nav__item md-nav__item--nested">
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5_4" >
+          <div class="md-nav__link md-nav__container">
+            <a href="../../api/mcp/" class="md-nav__link ">
+  <span class="md-ellipsis">
+    MCP
+  </span>
+            </a>
+              <label class="md-nav__link " for="__nav_5_4" id="__nav_5_4_label" tabindex="0">
+                <span class="md-nav__icon md-icon"></span>
+              </label>
+          </div>
+        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_5_4_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_5_4">
+            <span class="md-nav__icon md-icon"></span>
+    MCP
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+    <li class="md-nav__item">
+      <a href="../../api/mcp/client/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Client
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../api/mcp/server/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Server
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../api/mcp/transports/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Transports
+  </span>
+      </a>
+    </li>
+          </ul>
+        </nav>
+    </li>
+    <li class="md-nav__item md-nav__item--nested">
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5_5" >
+          <div class="md-nav__link md-nav__container">
+            <a href="../../api/streaming/" class="md-nav__link ">
+  <span class="md-ellipsis">
+    Streaming
+  </span>
+            </a>
+              <label class="md-nav__link " for="__nav_5_5" id="__nav_5_5_label" tabindex="0">
+                <span class="md-nav__icon md-icon"></span>
+              </label>
+          </div>
+        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_5_5_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_5_5">
+            <span class="md-nav__icon md-icon"></span>
+    Streaming
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+    <li class="md-nav__item">
+      <a href="../../api/streaming/context/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Context
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../api/streaming/events/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Events
+  </span>
+      </a>
+    </li>
+          </ul>
+        </nav>
+    </li>
+          </ul>
+        </nav>
+    </li>
+    <li class="md-nav__item md-nav__item--nested">
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_6" >
+          <div class="md-nav__link md-nav__container">
+            <a href="../../examples/" class="md-nav__link ">
+  <span class="md-ellipsis">
+    Examples
+  </span>
+            </a>
+              <label class="md-nav__link " for="__nav_6" id="__nav_6_label" tabindex="0">
+                <span class="md-nav__icon md-icon"></span>
+              </label>
+          </div>
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_6">
+            <span class="md-nav__icon md-icon"></span>
+    Examples
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+    <li class="md-nav__item">
+      <a href="../../examples/basic-chat/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Basic Chat
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../examples/multi-robot-network/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Multi-Robot Network
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../examples/tool-usage/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Tool Usage
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../examples/mcp-server/" class="md-nav__link">
+  <span class="md-ellipsis">
+    MCP Server
+  </span>
+      </a>
+    </li>
+    <li class="md-nav__item">
+      <a href="../../examples/rails-application/" class="md-nav__link">
+  <span class="md-ellipsis">
+    Rails Application
+  </span>
+      </a>
+    </li>
+          </ul>
+        </nav>
+    </li>
+  </ul>
+</nav>
+                  </div>
+                </div>
+              </div>
+              <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
+                <div class="md-sidebar__scrollwrap">
+                  <div class="md-sidebar__inner">
+<nav class="md-nav md-nav--secondary" aria-label="On this page">
+    <label class="md-nav__title" for="__toc">
+      <span class="md-nav__icon md-icon"></span>
+      On this page
+    </label>
+    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
+        <li class="md-nav__item">
+  <a href="#defining-tools" class="md-nav__link">
+    <span class="md-ellipsis">
+        Defining Tools
+    </span>
+  </a>
+    <nav class="md-nav" aria-label="Defining Tools">
+      <ul class="md-nav__list">
+          <li class="md-nav__item">
+  <a href="#rubyllmtool-subclass" class="md-nav__link">
+    <span class="md-ellipsis">
+        RubyLLM::Tool Subclass
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#robotlabtool-subclass" class="md-nav__link">
+    <span class="md-ellipsis">
+        RobotLab::Tool Subclass
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#robotlabtoolcreate-dynamic-tools" class="md-nav__link">
+    <span class="md-ellipsis">
+        RobotLab::Tool.create (Dynamic Tools)
+    </span>
+  </a>
+</li>
+      </ul>
+    </nav>
+</li>
+        <li class="md-nav__item">
+  <a href="#built-in-tools" class="md-nav__link">
+    <span class="md-ellipsis">
+        Built-in Tools
+    </span>
+  </a>
+    <nav class="md-nav" aria-label="Built-in Tools">
+      <ul class="md-nav__list">
+          <li class="md-nav__item">
+  <a href="#askuser" class="md-nav__link">
+    <span class="md-ellipsis">
+        AskUser
+    </span>
+  </a>
+</li>
+      </ul>
+    </nav>
+</li>
+        <li class="md-nav__item">
+  <a href="#attaching-tools-to-robots" class="md-nav__link">
+    <span class="md-ellipsis">
+        Attaching Tools to Robots
+    </span>
+  </a>
+    <nav class="md-nav" aria-label="Attaching Tools to Robots">
+      <ul class="md-nav__list">
+          <li class="md-nav__item">
+  <a href="#via-constructor" class="md-nav__link">
+    <span class="md-ellipsis">
+        Via Constructor
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#via-template-front-matter" class="md-nav__link">
+    <span class="md-ellipsis">
+        Via Template Front Matter
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#via-chaining" class="md-nav__link">
+    <span class="md-ellipsis">
+        Via Chaining
+    </span>
+  </a>
+</li>
+      </ul>
+    </nav>
+</li>
+        <li class="md-nav__item">
+  <a href="#parameter-types" class="md-nav__link">
+    <span class="md-ellipsis">
+        Parameter Types
+    </span>
+  </a>
+    <nav class="md-nav" aria-label="Parameter Types">
+      <ul class="md-nav__list">
+          <li class="md-nav__item">
+  <a href="#string" class="md-nav__link">
+    <span class="md-ellipsis">
+        String
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#integer" class="md-nav__link">
+    <span class="md-ellipsis">
+        Integer
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#number-float" class="md-nav__link">
+    <span class="md-ellipsis">
+        Number (Float)
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#boolean" class="md-nav__link">
+    <span class="md-ellipsis">
+        Boolean
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#array" class="md-nav__link">
+    <span class="md-ellipsis">
+        Array
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#enum" class="md-nav__link">
+    <span class="md-ellipsis">
+        Enum
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#required-vs-optional" class="md-nav__link">
+    <span class="md-ellipsis">
+        Required vs Optional
+    </span>
+  </a>
+</li>
+      </ul>
+    </nav>
+</li>
+        <li class="md-nav__item">
+  <a href="#tool-patterns" class="md-nav__link">
+    <span class="md-ellipsis">
+        Tool Patterns
+    </span>
+  </a>
+    <nav class="md-nav" aria-label="Tool Patterns">
+      <ul class="md-nav__list">
+          <li class="md-nav__item">
+  <a href="#database-lookup" class="md-nav__link">
+    <span class="md-ellipsis">
+        Database Lookup
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#api-integration" class="md-nav__link">
+    <span class="md-ellipsis">
+        API Integration
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#file-operations" class="md-nav__link">
+    <span class="md-ellipsis">
+        File Operations
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#multi-step-operations" class="md-nav__link">
+    <span class="md-ellipsis">
+        Multi-Step Operations
+    </span>
+  </a>
+</li>
+      </ul>
+    </nav>
+</li>
+        <li class="md-nav__item">
+  <a href="#tool-return-values" class="md-nav__link">
+    <span class="md-ellipsis">
+        Tool Return Values
+    </span>
+  </a>
+    <nav class="md-nav" aria-label="Tool Return Values">
+      <ul class="md-nav__list">
+          <li class="md-nav__item">
+  <a href="#structured-data" class="md-nav__link">
+    <span class="md-ellipsis">
+        Structured Data
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#simple-values" class="md-nav__link">
+    <span class="md-ellipsis">
+        Simple Values
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#lists" class="md-nav__link">
+    <span class="md-ellipsis">
+        Lists
+    </span>
+  </a>
+</li>
+      </ul>
+    </nav>
+</li>
+        <li class="md-nav__item">
+  <a href="#error-handling" class="md-nav__link">
+    <span class="md-ellipsis">
+        Error Handling
+    </span>
+  </a>
+    <nav class="md-nav" aria-label="Error Handling">
+      <ul class="md-nav__list">
+          <li class="md-nav__item">
+  <a href="#automatic-error-handling" class="md-nav__link">
+    <span class="md-ellipsis">
+        Automatic Error Handling
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#critical-tools-opt-out" class="md-nav__link">
+    <span class="md-ellipsis">
+        Critical Tools (Opt-Out)
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#manual-error-handling" class="md-nav__link">
+    <span class="md-ellipsis">
+        Manual Error Handling
+    </span>
+  </a>
+</li>
+      </ul>
+    </nav>
+</li>
+        <li class="md-nav__item">
+  <a href="#tool-callbacks" class="md-nav__link">
+    <span class="md-ellipsis">
+        Tool Callbacks
+    </span>
+  </a>
+</li>
+        <li class="md-nav__item">
+  <a href="#robotlabtoolcreate-with-schema" class="md-nav__link">
+    <span class="md-ellipsis">
+        RobotLab::Tool.create with Schema
+    </span>
+  </a>
+</li>
+        <li class="md-nav__item">
+  <a href="#best-practices" class="md-nav__link">
+    <span class="md-ellipsis">
+        Best Practices
+    </span>
+  </a>
+    <nav class="md-nav" aria-label="Best Practices">
+      <ul class="md-nav__list">
+          <li class="md-nav__item">
+  <a href="#1-clear-descriptions" class="md-nav__link">
+    <span class="md-ellipsis">
+        1. Clear Descriptions
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#2-validate-inputs" class="md-nav__link">
+    <span class="md-ellipsis">
+        2. Validate Inputs
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#3-return-structured-data" class="md-nav__link">
+    <span class="md-ellipsis">
+        3. Return Structured Data
+    </span>
+  </a>
+</li>
+          <li class="md-nav__item">
+  <a href="#4-keep-tools-focused" class="md-nav__link">
+    <span class="md-ellipsis">
+        4. Keep Tools Focused
+    </span>
+  </a>
+</li>
+      </ul>
+    </nav>
+</li>
+        <li class="md-nav__item">
+  <a href="#next-steps" class="md-nav__link">
+    <span class="md-ellipsis">
+        Next Steps
+    </span>
+  </a>
+</li>
+    </ul>
+</nav>
+                  </div>
+                </div>
+              </div>
+            <div class="md-content" data-md-component="content">
+              <article class="md-content__inner md-typeset">
+    <a href="https://github.com/madbomber/robot_lab/edit/main/docs/guides/using-tools.md" title="Edit this page" class="md-content__button md-icon" rel="edit">
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M10 20H6V4h7v5h5v3.1l2-2V8l-6-6H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h4zm10.2-7c.1 0 .3.1.4.2l1.3 1.3c.2.2.2.6 0 .8l-1 1-2.1-2.1 1-1c.1-.1.2-.2.4-.2m0 3.9L14.1 23H12v-2.1l6.1-6.1z"/></svg>
+    </a>
+    <a href="https://github.com/madbomber/robot_lab/raw/main/docs/guides/using-tools.md" title="View source of this page" class="md-content__button md-icon">
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M17 18c.56 0 1 .44 1 1s-.44 1-1 1-1-.44-1-1 .44-1 1-1m0-3c-2.73 0-5.06 1.66-6 4 .94 2.34 3.27 4 6 4s5.06-1.66 6-4c-.94-2.34-3.27-4-6-4m0 6.5a2.5 2.5 0 0 1-2.5-2.5 2.5 2.5 0 0 1 2.5-2.5 2.5 2.5 0 0 1 2.5 2.5 2.5 2.5 0 0 1-2.5 2.5M9.27 20H6V4h7v5h5v4.07c.7.08 1.36.25 2 .49V8l-6-6H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h4.5a8.2 8.2 0 0 1-1.23-2"/></svg>
+    </a>
+<h1 id="using-tools">Using Tools<a class="headerlink" href="#using-tools" title="Permanent link">&para;</a></h1>
+<p>Tools give robots the ability to interact with external systems. RobotLab supports three approaches: <code>RubyLLM::Tool</code> subclasses, <code>RobotLab::Tool</code> subclasses (with robot access), and <code>RobotLab::Tool.create</code> for dynamic tools.</p>
+<h2 id="defining-tools">Defining Tools<a class="headerlink" href="#defining-tools" title="Permanent link">&para;</a></h2>
+<h3 id="rubyllmtool-subclass">RubyLLM::Tool Subclass<a class="headerlink" href="#rubyllmtool-subclass" title="Permanent link">&para;</a></h3>
+<p>For reusable tools that don't need robot access:</p>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="k">class</span><span class="w"> </span><span class="nc">GetWeather</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="no">RubyLLM</span><span class="o">::</span><span class="no">Tool</span>
+</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="w">  </span><span class="n">description</span><span class="w"> </span><span class="s2">&quot;Get current weather for a location&quot;</span>
+</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>
+</span><span id="__span-0-4"><a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="w">  </span><span class="n">param</span><span class="w"> </span><span class="ss">:location</span><span class="p">,</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="ss">:string</span><span class="p">,</span><span class="w"> </span><span class="ss">desc</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;City name or zip code&quot;</span>
+</span><span id="__span-0-5"><a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="w">  </span><span class="n">param</span><span class="w"> </span><span class="ss">:unit</span><span class="p">,</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="ss">:string</span><span class="p">,</span><span class="w"> </span><span class="ss">desc</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Temperature unit&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">required</span><span class="p">:</span><span class="w"> </span><span class="kp">false</span>
+</span><span id="__span-0-6"><a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>
+</span><span id="__span-0-7"><a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="w">  </span><span class="k">def</span><span class="w"> </span><span class="nf">execute</span><span class="p">(</span><span class="ss">location</span><span class="p">:,</span><span class="w"> </span><span class="ss">unit</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;celsius&quot;</span><span class="p">)</span>
+</span><span id="__span-0-8"><a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a><span class="w">    </span><span class="no">WeatherService</span><span class="o">.</span><span class="n">current</span><span class="p">(</span><span class="n">location</span><span class="p">,</span><span class="w"> </span><span class="ss">unit</span><span class="p">:</span><span class="w"> </span><span class="n">unit</span><span class="p">)</span>
+</span><span id="__span-0-9"><a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a><span class="w">  </span><span class="k">end</span>
+</span><span id="__span-0-10"><a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a><span class="k">end</span>
+</span></code></pre></div>
+<h3 id="robotlabtool-subclass">RobotLab::Tool Subclass<a class="headerlink" href="#robotlabtool-subclass" title="Permanent link">&para;</a></h3>
+<p>For tools that need access to their owning robot (self-modification, spawning, etc.):</p>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="k">class</span><span class="w"> </span><span class="nc">AdjustEnergy</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="no">RobotLab</span><span class="o">::</span><span class="no">Tool</span>
+</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="w">  </span><span class="n">description</span><span class="w"> </span><span class="s2">&quot;Adjust the robot&#39;s creativity level&quot;</span>
+</span><span id="__span-1-3"><a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a>
+</span><span id="__span-1-4"><a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a><span class="w">  </span><span class="n">param</span><span class="w"> </span><span class="ss">:level</span><span class="p">,</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;number&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">desc</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Temperature from 0.0 to 1.0&quot;</span>
+</span><span id="__span-1-5"><a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a>
+</span><span id="__span-1-6"><a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a><span class="w">  </span><span class="k">def</span><span class="w"> </span><span class="nf">execute</span><span class="p">(</span><span class="ss">level</span><span class="p">:)</span>
+</span><span id="__span-1-7"><a id="__codelineno-1-7" name="__codelineno-1-7" href="#__codelineno-1-7"></a><span class="w">    </span><span class="n">robot</span><span class="o">.</span><span class="n">with_temperature</span><span class="p">(</span><span class="n">level</span><span class="p">)</span>
+</span><span id="__span-1-8"><a id="__codelineno-1-8" name="__codelineno-1-8" href="#__codelineno-1-8"></a><span class="w">    </span><span class="s2">&quot;Temperature adjusted to </span><span class="si">#{</span><span class="n">level</span><span class="si">}</span><span class="s2">&quot;</span>
+</span><span id="__span-1-9"><a id="__codelineno-1-9" name="__codelineno-1-9" href="#__codelineno-1-9"></a><span class="w">  </span><span class="k">end</span>
+</span><span id="__span-1-10"><a id="__codelineno-1-10" name="__codelineno-1-10" href="#__codelineno-1-10"></a><span class="k">end</span>
+</span></code></pre></div>
+<p>Pass <code>robot: self</code> when constructing:</p>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="k">class</span><span class="w"> </span><span class="nc">MyRobot</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="no">RobotLab</span><span class="o">::</span><span class="no">Robot</span>
+</span><span id="__span-2-2"><a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a><span class="w">  </span><span class="k">def</span><span class="w"> </span><span class="nf">initialize</span>
+</span><span id="__span-2-3"><a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a><span class="w">    </span><span class="k">super</span><span class="p">(</span>
+</span><span id="__span-2-4"><a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a><span class="w">      </span><span class="nb">name</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;creative_bot&quot;</span><span class="p">,</span>
+</span><span id="__span-2-5"><a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a><span class="w">      </span><span class="ss">system_prompt</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;You are creative.&quot;</span><span class="p">,</span>
+</span><span id="__span-2-6"><a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a><span class="w">      </span><span class="ss">local_tools</span><span class="p">:</span><span class="w"> </span><span class="o">[</span><span class="no">AdjustEnergy</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="ss">robot</span><span class="p">:</span><span class="w"> </span><span class="nb">self</span><span class="p">)</span><span class="o">]</span>
+</span><span id="__span-2-7"><a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a><span class="w">    </span><span class="p">)</span>
+</span><span id="__span-2-8"><a id="__codelineno-2-8" name="__codelineno-2-8" href="#__codelineno-2-8"></a><span class="w">  </span><span class="k">end</span>
+</span><span id="__span-2-9"><a id="__codelineno-2-9" name="__codelineno-2-9" href="#__codelineno-2-9"></a><span class="k">end</span>
+</span></code></pre></div>
+<h3 id="robotlabtoolcreate-dynamic-tools">RobotLab::Tool.create (Dynamic Tools)<a class="headerlink" href="#robotlabtoolcreate-dynamic-tools" title="Permanent link">&para;</a></h3>
+<p>For quick, inline tools use the <code>Tool.create</code> factory:</p>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="n">get_time</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">RobotLab</span><span class="o">::</span><span class="no">Tool</span><span class="o">.</span><span class="n">create</span><span class="p">(</span>
+</span><span id="__span-3-2"><a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a><span class="w">  </span><span class="nb">name</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;get_time&quot;</span><span class="p">,</span>
+</span><span id="__span-3-3"><a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a><span class="w">  </span><span class="ss">description</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Get the current time&quot;</span>
+</span><span id="__span-3-4"><a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">|</span><span class="n">_args</span><span class="o">|</span><span class="w"> </span><span class="no">Time</span><span class="o">.</span><span class="n">now</span><span class="o">.</span><span class="n">to_s</span><span class="w"> </span><span class="p">}</span>
+</span></code></pre></div>
+<p>With parameters:</p>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-4-1"><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="n">weather_tool</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">RobotLab</span><span class="o">::</span><span class="no">Tool</span><span class="o">.</span><span class="n">create</span><span class="p">(</span>
+</span><span id="__span-4-2"><a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a><span class="w">  </span><span class="nb">name</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;get_weather&quot;</span><span class="p">,</span>
+</span><span id="__span-4-3"><a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="w">  </span><span class="ss">description</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Get current weather for a location&quot;</span><span class="p">,</span>
+</span><span id="__span-4-4"><a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a><span class="w">  </span><span class="ss">parameters</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
+</span><span id="__span-4-5"><a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a><span class="w">    </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;object&quot;</span><span class="p">,</span>
+</span><span id="__span-4-6"><a id="__codelineno-4-6" name="__codelineno-4-6" href="#__codelineno-4-6"></a><span class="w">    </span><span class="ss">properties</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
+</span><span id="__span-4-7"><a id="__codelineno-4-7" name="__codelineno-4-7" href="#__codelineno-4-7"></a><span class="w">      </span><span class="ss">location</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;string&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">description</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;City name&quot;</span><span class="w"> </span><span class="p">}</span>
+</span><span id="__span-4-8"><a id="__codelineno-4-8" name="__codelineno-4-8" href="#__codelineno-4-8"></a><span class="w">    </span><span class="p">},</span>
+</span><span id="__span-4-9"><a id="__codelineno-4-9" name="__codelineno-4-9" href="#__codelineno-4-9"></a><span class="w">    </span><span class="ss">required</span><span class="p">:</span><span class="w"> </span><span class="o">[</span><span class="s2">&quot;location&quot;</span><span class="o">]</span>
+</span><span id="__span-4-10"><a id="__codelineno-4-10" name="__codelineno-4-10" href="#__codelineno-4-10"></a><span class="w">  </span><span class="p">}</span>
+</span><span id="__span-4-11"><a id="__codelineno-4-11" name="__codelineno-4-11" href="#__codelineno-4-11"></a><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">|</span><span class="n">args</span><span class="o">|</span><span class="w"> </span><span class="no">WeatherService</span><span class="o">.</span><span class="n">current</span><span class="p">(</span><span class="n">args</span><span class="o">[</span><span class="ss">:location</span><span class="o">]</span><span class="p">)</span><span class="w"> </span><span class="p">}</span>
+</span></code></pre></div>
+<h2 id="built-in-tools">Built-in Tools<a class="headerlink" href="#built-in-tools" title="Permanent link">&para;</a></h2>
+<h3 id="askuser">AskUser<a class="headerlink" href="#askuser" title="Permanent link">&para;</a></h3>
+<p><code>RobotLab::AskUser</code> lets a robot ask the user a question via the terminal. The LLM decides when it needs human input and calls the tool with a question, optional choices, and an optional default.</p>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-5-1"><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="n">robot</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">RobotLab</span><span class="o">.</span><span class="n">build</span><span class="p">(</span>
+</span><span id="__span-5-2"><a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="w">  </span><span class="nb">name</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;onboarding&quot;</span><span class="p">,</span>
+</span><span id="__span-5-3"><a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a><span class="w">  </span><span class="ss">system_prompt</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Walk the user through project setup. Ask questions to understand their needs.&quot;</span><span class="p">,</span>
+</span><span id="__span-5-4"><a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a><span class="w">  </span><span class="ss">local_tools</span><span class="p">:</span><span class="w"> </span><span class="o">[</span><span class="no">RobotLab</span><span class="o">::</span><span class="no">AskUser</span><span class="o">]</span>
+</span><span id="__span-5-5"><a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a><span class="p">)</span>
+</span><span id="__span-5-6"><a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a><span class="n">robot</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="s2">&quot;Help the user set up a new project&quot;</span><span class="p">)</span>
+</span></code></pre></div>
+<p>The tool displays the robot's name and question, then waits for terminal input:</p>
+<div class="language-text highlight"><pre><span></span><code><span id="__span-6-1"><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a>[onboarding] What programming language will you use?
+</span><span id="__span-6-2"><a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a>  1. Ruby
+</span><span id="__span-6-3"><a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a>  2. Python
+</span><span id="__span-6-4"><a id="__codelineno-6-4" name="__codelineno-6-4" href="#__codelineno-6-4"></a>  3. Go
+</span><span id="__span-6-5"><a id="__codelineno-6-5" name="__codelineno-6-5" href="#__codelineno-6-5"></a>&gt;
+</span></code></pre></div>
+<p>Features:</p>
+<ul>
+<li><strong>Open-ended</strong>: just a question, free-text response</li>
+<li><strong>Multiple choice</strong>: numbered options, user types the number or text</li>
+<li><strong>Default value</strong>: shown in the prompt, used when user presses Enter</li>
+</ul>
+<p>IO is sourced from <code>robot.input</code> / <code>robot.output</code> (defaulting to <code>$stdin</code> / <code>$stdout</code>), making it easy to test with <code>StringIO</code>:</p>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-7-1"><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a><span class="n">robot</span><span class="o">.</span><span class="n">input</span><span class="w">  </span><span class="o">=</span><span class="w"> </span><span class="no">StringIO</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="s2">&quot;2</span><span class="se">\n</span><span class="s2">&quot;</span><span class="p">)</span>
+</span><span id="__span-7-2"><a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a><span class="n">robot</span><span class="o">.</span><span class="n">output</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">StringIO</span><span class="o">.</span><span class="n">new</span>
+</span></code></pre></div>
+<p>See the <a href="../../api/core/tool/#built-in-askuser">AskUser API reference</a> for full details.</p>
+<h2 id="attaching-tools-to-robots">Attaching Tools to Robots<a class="headerlink" href="#attaching-tools-to-robots" title="Permanent link">&para;</a></h2>
+<h3 id="via-constructor">Via Constructor<a class="headerlink" href="#via-constructor" title="Permanent link">&para;</a></h3>
+<p>Pass tools via the <code>local_tools:</code> parameter when building a robot:</p>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-8-1"><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a><span class="n">robot</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">RobotLab</span><span class="o">.</span><span class="n">build</span><span class="p">(</span>
+</span><span id="__span-8-2"><a id="__codelineno-8-2" name="__codelineno-8-2" href="#__codelineno-8-2"></a><span class="w">  </span><span class="nb">name</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;assistant&quot;</span><span class="p">,</span>
+</span><span id="__span-8-3"><a id="__codelineno-8-3" name="__codelineno-8-3" href="#__codelineno-8-3"></a><span class="w">  </span><span class="ss">system_prompt</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;You are a helpful assistant with tool access.&quot;</span><span class="p">,</span>
+</span><span id="__span-8-4"><a id="__codelineno-8-4" name="__codelineno-8-4" href="#__codelineno-8-4"></a><span class="w">  </span><span class="ss">local_tools</span><span class="p">:</span><span class="w"> </span><span class="o">[</span><span class="no">GetWeather</span><span class="p">,</span><span class="w"> </span><span class="no">CalculatorTool</span><span class="o">]</span>
+</span><span id="__span-8-5"><a id="__codelineno-8-5" name="__codelineno-8-5" href="#__codelineno-8-5"></a><span class="p">)</span>
+</span></code></pre></div>
+<h3 id="via-template-front-matter">Via Template Front Matter<a class="headerlink" href="#via-template-front-matter" title="Permanent link">&para;</a></h3>
+<p>Declare tool class names in the template's YAML front matter. RobotLab resolves each string to a Ruby constant via <code>Object.const_get</code> and instantiates it:</p>
+<div class="language-markdown highlight"><span class="filename">prompts/weather_bot.md</span><pre><span></span><code><span id="__span-9-1"><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a>---
+</span><span id="__span-9-2"><a id="__codelineno-9-2" name="__codelineno-9-2" href="#__codelineno-9-2"></a>description: Weather assistant with forecast tools
+</span><span id="__span-9-3"><a id="__codelineno-9-3" name="__codelineno-9-3" href="#__codelineno-9-3"></a>tools:
+</span><span id="__span-9-4"><a id="__codelineno-9-4" name="__codelineno-9-4" href="#__codelineno-9-4"></a><span class="w">  </span><span class="k">-</span><span class="w"> </span>GetWeather
+</span><span id="__span-9-5"><a id="__codelineno-9-5" name="__codelineno-9-5" href="#__codelineno-9-5"></a><span class="gu">  - GetForecast</span>
+</span><span id="__span-9-6"><a id="__codelineno-9-6" name="__codelineno-9-6" href="#__codelineno-9-6"></a><span class="gu">---</span>
+</span><span id="__span-9-7"><a id="__codelineno-9-7" name="__codelineno-9-7" href="#__codelineno-9-7"></a>You are a weather assistant. Use your tools to look up weather information.
+</span></code></pre></div>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-10-1"><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="c1"># Tools are resolved from frontmatter — no local_tools: needed</span>
+</span><span id="__span-10-2"><a id="__codelineno-10-2" name="__codelineno-10-2" href="#__codelineno-10-2"></a><span class="n">robot</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">RobotLab</span><span class="o">.</span><span class="n">build</span><span class="p">(</span><span class="ss">template</span><span class="p">:</span><span class="w"> </span><span class="ss">:weather_bot</span><span class="p">)</span>
+</span></code></pre></div>
+<p>Tool classes must be defined and loaded before building the robot. Unresolvable names are skipped with a warning. Constructor <code>local_tools:</code> overrides frontmatter <code>tools:</code> when provided.</p>
+<h3 id="via-chaining">Via Chaining<a class="headerlink" href="#via-chaining" title="Permanent link">&para;</a></h3>
+<p>You can also add tools dynamically with chaining:</p>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-11-1"><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a><span class="n">robot</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">RobotLab</span><span class="o">.</span><span class="n">build</span><span class="p">(</span><span class="nb">name</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;assistant&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">system_prompt</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;...&quot;</span><span class="p">)</span>
+</span><span id="__span-11-2"><a id="__codelineno-11-2" name="__codelineno-11-2" href="#__codelineno-11-2"></a><span class="n">robot</span><span class="o">.</span><span class="n">with_tools</span><span class="p">(</span><span class="no">GetWeather</span><span class="p">,</span><span class="w"> </span><span class="no">CalculatorTool</span><span class="p">)</span>
+</span></code></pre></div>
+<h2 id="parameter-types">Parameter Types<a class="headerlink" href="#parameter-types" title="Permanent link">&para;</a></h2>
+<p>Define parameters on <code>RubyLLM::Tool</code> subclasses using <code>param</code>:</p>
+<h3 id="string">String<a class="headerlink" href="#string" title="Permanent link">&para;</a></h3>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-12-1"><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a><span class="n">param</span><span class="w"> </span><span class="ss">:name</span><span class="p">,</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="ss">:string</span><span class="p">,</span><span class="w"> </span><span class="ss">desc</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;User&#39;s full name&quot;</span>
+</span></code></pre></div>
+<h3 id="integer">Integer<a class="headerlink" href="#integer" title="Permanent link">&para;</a></h3>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-13-1"><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a><span class="n">param</span><span class="w"> </span><span class="ss">:count</span><span class="p">,</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="ss">:integer</span><span class="p">,</span><span class="w"> </span><span class="ss">desc</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Number of results&quot;</span>
+</span></code></pre></div>
+<h3 id="number-float">Number (Float)<a class="headerlink" href="#number-float" title="Permanent link">&para;</a></h3>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-14-1"><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a><span class="n">param</span><span class="w"> </span><span class="ss">:price</span><span class="p">,</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="ss">:number</span><span class="p">,</span><span class="w"> </span><span class="ss">desc</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Price in dollars&quot;</span>
+</span></code></pre></div>
+<h3 id="boolean">Boolean<a class="headerlink" href="#boolean" title="Permanent link">&para;</a></h3>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-15-1"><a id="__codelineno-15-1" name="__codelineno-15-1" href="#__codelineno-15-1"></a><span class="n">param</span><span class="w"> </span><span class="ss">:active</span><span class="p">,</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="ss">:boolean</span><span class="p">,</span><span class="w"> </span><span class="ss">desc</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Whether the user is active&quot;</span>
+</span></code></pre></div>
+<h3 id="array">Array<a class="headerlink" href="#array" title="Permanent link">&para;</a></h3>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-16-1"><a id="__codelineno-16-1" name="__codelineno-16-1" href="#__codelineno-16-1"></a><span class="n">param</span><span class="w"> </span><span class="ss">:tags</span><span class="p">,</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="ss">:array</span><span class="p">,</span><span class="w"> </span><span class="ss">desc</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;List of tags&quot;</span>
+</span></code></pre></div>
+<h3 id="enum">Enum<a class="headerlink" href="#enum" title="Permanent link">&para;</a></h3>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-17-1"><a id="__codelineno-17-1" name="__codelineno-17-1" href="#__codelineno-17-1"></a><span class="n">param</span><span class="w"> </span><span class="ss">:status</span><span class="p">,</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="ss">:string</span><span class="p">,</span><span class="w"> </span><span class="ss">desc</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Order status&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">enum</span><span class="p">:</span><span class="w"> </span><span class="sx">%w[pending active completed]</span>
+</span></code></pre></div>
+<h3 id="required-vs-optional">Required vs Optional<a class="headerlink" href="#required-vs-optional" title="Permanent link">&para;</a></h3>
+<p>Parameters are required by default. Mark optional with <code>required: false</code>:</p>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-18-1"><a id="__codelineno-18-1" name="__codelineno-18-1" href="#__codelineno-18-1"></a><span class="n">param</span><span class="w"> </span><span class="ss">:query</span><span class="p">,</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="ss">:string</span><span class="p">,</span><span class="w"> </span><span class="ss">desc</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Search query&quot;</span><span class="w">                    </span><span class="c1"># required</span>
+</span><span id="__span-18-2"><a id="__codelineno-18-2" name="__codelineno-18-2" href="#__codelineno-18-2"></a><span class="n">param</span><span class="w"> </span><span class="ss">:limit</span><span class="p">,</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="ss">:integer</span><span class="p">,</span><span class="w"> </span><span class="ss">desc</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Max results&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">required</span><span class="p">:</span><span class="w"> </span><span class="kp">false</span><span class="w">   </span><span class="c1"># optional</span>
+</span></code></pre></div>
+<h2 id="tool-patterns">Tool Patterns<a class="headerlink" href="#tool-patterns" title="Permanent link">&para;</a></h2>
+<h3 id="database-lookup">Database Lookup<a class="headerlink" href="#database-lookup" title="Permanent link">&para;</a></h3>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-19-1"><a id="__codelineno-19-1" name="__codelineno-19-1" href="#__codelineno-19-1"></a><span class="k">class</span><span class="w"> </span><span class="nc">FindUser</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="no">RubyLLM</span><span class="o">::</span><span class="no">Tool</span>
+</span><span id="__span-19-2"><a id="__codelineno-19-2" name="__codelineno-19-2" href="#__codelineno-19-2"></a><span class="w">  </span><span class="n">description</span><span class="w"> </span><span class="s2">&quot;Find user by email or ID&quot;</span>
+</span><span id="__span-19-3"><a id="__codelineno-19-3" name="__codelineno-19-3" href="#__codelineno-19-3"></a>
+</span><span id="__span-19-4"><a id="__codelineno-19-4" name="__codelineno-19-4" href="#__codelineno-19-4"></a><span class="w">  </span><span class="n">param</span><span class="w"> </span><span class="ss">:identifier</span><span class="p">,</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="ss">:string</span><span class="p">,</span><span class="w"> </span><span class="ss">desc</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Email address or user ID&quot;</span>
+</span><span id="__span-19-5"><a id="__codelineno-19-5" name="__codelineno-19-5" href="#__codelineno-19-5"></a>
+</span><span id="__span-19-6"><a id="__codelineno-19-6" name="__codelineno-19-6" href="#__codelineno-19-6"></a><span class="w">  </span><span class="k">def</span><span class="w"> </span><span class="nf">execute</span><span class="p">(</span><span class="ss">identifier</span><span class="p">:)</span>
+</span><span id="__span-19-7"><a id="__codelineno-19-7" name="__codelineno-19-7" href="#__codelineno-19-7"></a><span class="w">    </span><span class="n">user</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">User</span><span class="o">.</span><span class="n">find_by</span><span class="p">(</span><span class="nb">id</span><span class="p">:</span><span class="w"> </span><span class="n">identifier</span><span class="p">)</span><span class="w"> </span><span class="o">||</span><span class="w"> </span><span class="no">User</span><span class="o">.</span><span class="n">find_by</span><span class="p">(</span><span class="ss">email</span><span class="p">:</span><span class="w"> </span><span class="n">identifier</span><span class="p">)</span>
+</span><span id="__span-19-8"><a id="__codelineno-19-8" name="__codelineno-19-8" href="#__codelineno-19-8"></a><span class="w">    </span><span class="n">user</span><span class="w"> </span><span class="p">?</span><span class="w"> </span><span class="n">user</span><span class="o">.</span><span class="n">to_h</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="ss">error</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;User not found&quot;</span><span class="w"> </span><span class="p">}</span>
+</span><span id="__span-19-9"><a id="__codelineno-19-9" name="__codelineno-19-9" href="#__codelineno-19-9"></a><span class="w">  </span><span class="k">end</span>
+</span><span id="__span-19-10"><a id="__codelineno-19-10" name="__codelineno-19-10" href="#__codelineno-19-10"></a><span class="k">end</span>
+</span></code></pre></div>
+<h3 id="api-integration">API Integration<a class="headerlink" href="#api-integration" title="Permanent link">&para;</a></h3>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-20-1"><a id="__codelineno-20-1" name="__codelineno-20-1" href="#__codelineno-20-1"></a><span class="k">class</span><span class="w"> </span><span class="nc">GetStockPrice</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="no">RubyLLM</span><span class="o">::</span><span class="no">Tool</span>
+</span><span id="__span-20-2"><a id="__codelineno-20-2" name="__codelineno-20-2" href="#__codelineno-20-2"></a><span class="w">  </span><span class="n">description</span><span class="w"> </span><span class="s2">&quot;Get current stock price for a ticker symbol&quot;</span>
+</span><span id="__span-20-3"><a id="__codelineno-20-3" name="__codelineno-20-3" href="#__codelineno-20-3"></a>
+</span><span id="__span-20-4"><a id="__codelineno-20-4" name="__codelineno-20-4" href="#__codelineno-20-4"></a><span class="w">  </span><span class="n">param</span><span class="w"> </span><span class="ss">:symbol</span><span class="p">,</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="ss">:string</span><span class="p">,</span><span class="w"> </span><span class="ss">desc</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Stock ticker symbol (e.g. AAPL)&quot;</span>
+</span><span id="__span-20-5"><a id="__codelineno-20-5" name="__codelineno-20-5" href="#__codelineno-20-5"></a>
+</span><span id="__span-20-6"><a id="__codelineno-20-6" name="__codelineno-20-6" href="#__codelineno-20-6"></a><span class="w">  </span><span class="k">def</span><span class="w"> </span><span class="nf">execute</span><span class="p">(</span><span class="ss">symbol</span><span class="p">:)</span>
+</span><span id="__span-20-7"><a id="__codelineno-20-7" name="__codelineno-20-7" href="#__codelineno-20-7"></a><span class="w">    </span><span class="n">response</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">HTTP</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;https://api.stocks.example/quote/</span><span class="si">#{</span><span class="n">symbol</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+</span><span id="__span-20-8"><a id="__codelineno-20-8" name="__codelineno-20-8" href="#__codelineno-20-8"></a><span class="w">    </span><span class="no">JSON</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="n">response</span><span class="o">.</span><span class="n">body</span><span class="p">)</span>
+</span><span id="__span-20-9"><a id="__codelineno-20-9" name="__codelineno-20-9" href="#__codelineno-20-9"></a><span class="w">  </span><span class="k">rescue</span><span class="w"> </span><span class="no">HTTP</span><span class="o">::</span><span class="no">Error</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="n">e</span>
+</span><span id="__span-20-10"><a id="__codelineno-20-10" name="__codelineno-20-10" href="#__codelineno-20-10"></a><span class="w">    </span><span class="p">{</span><span class="w"> </span><span class="ss">error</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Failed to fetch stock price: </span><span class="si">#{</span><span class="n">e</span><span class="o">.</span><span class="n">message</span><span class="si">}</span><span class="s2">&quot;</span><span class="w"> </span><span class="p">}</span>
+</span><span id="__span-20-11"><a id="__codelineno-20-11" name="__codelineno-20-11" href="#__codelineno-20-11"></a><span class="w">  </span><span class="k">end</span>
+</span><span id="__span-20-12"><a id="__codelineno-20-12" name="__codelineno-20-12" href="#__codelineno-20-12"></a><span class="k">end</span>
+</span></code></pre></div>
+<h3 id="file-operations">File Operations<a class="headerlink" href="#file-operations" title="Permanent link">&para;</a></h3>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-21-1"><a id="__codelineno-21-1" name="__codelineno-21-1" href="#__codelineno-21-1"></a><span class="k">class</span><span class="w"> </span><span class="nc">ReadFile</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="no">RubyLLM</span><span class="o">::</span><span class="no">Tool</span>
+</span><span id="__span-21-2"><a id="__codelineno-21-2" name="__codelineno-21-2" href="#__codelineno-21-2"></a><span class="w">  </span><span class="n">description</span><span class="w"> </span><span class="s2">&quot;Read contents of a file&quot;</span>
+</span><span id="__span-21-3"><a id="__codelineno-21-3" name="__codelineno-21-3" href="#__codelineno-21-3"></a>
+</span><span id="__span-21-4"><a id="__codelineno-21-4" name="__codelineno-21-4" href="#__codelineno-21-4"></a><span class="w">  </span><span class="n">param</span><span class="w"> </span><span class="ss">:path</span><span class="p">,</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="ss">:string</span><span class="p">,</span><span class="w"> </span><span class="ss">desc</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Absolute path to the file&quot;</span>
+</span><span id="__span-21-5"><a id="__codelineno-21-5" name="__codelineno-21-5" href="#__codelineno-21-5"></a>
+</span><span id="__span-21-6"><a id="__codelineno-21-6" name="__codelineno-21-6" href="#__codelineno-21-6"></a><span class="w">  </span><span class="k">def</span><span class="w"> </span><span class="nf">execute</span><span class="p">(</span><span class="ss">path</span><span class="p">:)</span>
+</span><span id="__span-21-7"><a id="__codelineno-21-7" name="__codelineno-21-7" href="#__codelineno-21-7"></a><span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="no">File</span><span class="o">.</span><span class="n">exist?</span><span class="p">(</span><span class="n">path</span><span class="p">)</span><span class="w"> </span><span class="o">&amp;&amp;</span><span class="w"> </span><span class="no">File</span><span class="o">.</span><span class="n">readable?</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
+</span><span id="__span-21-8"><a id="__codelineno-21-8" name="__codelineno-21-8" href="#__codelineno-21-8"></a><span class="w">      </span><span class="p">{</span><span class="w"> </span><span class="ss">content</span><span class="p">:</span><span class="w"> </span><span class="no">File</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="n">path</span><span class="p">),</span><span class="w"> </span><span class="ss">size</span><span class="p">:</span><span class="w"> </span><span class="no">File</span><span class="o">.</span><span class="n">size</span><span class="p">(</span><span class="n">path</span><span class="p">)</span><span class="w"> </span><span class="p">}</span>
+</span><span id="__span-21-9"><a id="__codelineno-21-9" name="__codelineno-21-9" href="#__codelineno-21-9"></a><span class="w">    </span><span class="k">else</span>
+</span><span id="__span-21-10"><a id="__codelineno-21-10" name="__codelineno-21-10" href="#__codelineno-21-10"></a><span class="w">      </span><span class="p">{</span><span class="w"> </span><span class="ss">error</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;File not found or not readable&quot;</span><span class="w"> </span><span class="p">}</span>
+</span><span id="__span-21-11"><a id="__codelineno-21-11" name="__codelineno-21-11" href="#__codelineno-21-11"></a><span class="w">    </span><span class="k">end</span>
+</span><span id="__span-21-12"><a id="__codelineno-21-12" name="__codelineno-21-12" href="#__codelineno-21-12"></a><span class="w">  </span><span class="k">end</span>
+</span><span id="__span-21-13"><a id="__codelineno-21-13" name="__codelineno-21-13" href="#__codelineno-21-13"></a><span class="k">end</span>
+</span></code></pre></div>
+<h3 id="multi-step-operations">Multi-Step Operations<a class="headerlink" href="#multi-step-operations" title="Permanent link">&para;</a></h3>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-22-1"><a id="__codelineno-22-1" name="__codelineno-22-1" href="#__codelineno-22-1"></a><span class="k">class</span><span class="w"> </span><span class="nc">ProcessOrder</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="no">RubyLLM</span><span class="o">::</span><span class="no">Tool</span>
+</span><span id="__span-22-2"><a id="__codelineno-22-2" name="__codelineno-22-2" href="#__codelineno-22-2"></a><span class="w">  </span><span class="n">description</span><span class="w"> </span><span class="s2">&quot;Validate and process a customer order&quot;</span>
+</span><span id="__span-22-3"><a id="__codelineno-22-3" name="__codelineno-22-3" href="#__codelineno-22-3"></a>
+</span><span id="__span-22-4"><a id="__codelineno-22-4" name="__codelineno-22-4" href="#__codelineno-22-4"></a><span class="w">  </span><span class="n">param</span><span class="w"> </span><span class="ss">:order_id</span><span class="p">,</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="ss">:string</span><span class="p">,</span><span class="w"> </span><span class="ss">desc</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;The order ID to process&quot;</span>
+</span><span id="__span-22-5"><a id="__codelineno-22-5" name="__codelineno-22-5" href="#__codelineno-22-5"></a>
+</span><span id="__span-22-6"><a id="__codelineno-22-6" name="__codelineno-22-6" href="#__codelineno-22-6"></a><span class="w">  </span><span class="k">def</span><span class="w"> </span><span class="nf">execute</span><span class="p">(</span><span class="ss">order_id</span><span class="p">:)</span>
+</span><span id="__span-22-7"><a id="__codelineno-22-7" name="__codelineno-22-7" href="#__codelineno-22-7"></a><span class="w">    </span><span class="n">order</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">Order</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">order_id</span><span class="p">)</span>
+</span><span id="__span-22-8"><a id="__codelineno-22-8" name="__codelineno-22-8" href="#__codelineno-22-8"></a>
+</span><span id="__span-22-9"><a id="__codelineno-22-9" name="__codelineno-22-9" href="#__codelineno-22-9"></a><span class="w">    </span><span class="c1"># Validate</span>
+</span><span id="__span-22-10"><a id="__codelineno-22-10" name="__codelineno-22-10" href="#__codelineno-22-10"></a><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="ss">error</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Invalid order&quot;</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="k">unless</span><span class="w"> </span><span class="n">order</span><span class="o">.</span><span class="n">valid?</span>
+</span><span id="__span-22-11"><a id="__codelineno-22-11" name="__codelineno-22-11" href="#__codelineno-22-11"></a>
+</span><span id="__span-22-12"><a id="__codelineno-22-12" name="__codelineno-22-12" href="#__codelineno-22-12"></a><span class="w">    </span><span class="c1"># Process payment</span>
+</span><span id="__span-22-13"><a id="__codelineno-22-13" name="__codelineno-22-13" href="#__codelineno-22-13"></a><span class="w">    </span><span class="n">result</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">PaymentProcessor</span><span class="o">.</span><span class="n">charge</span><span class="p">(</span><span class="n">order</span><span class="p">)</span>
+</span><span id="__span-22-14"><a id="__codelineno-22-14" name="__codelineno-22-14" href="#__codelineno-22-14"></a><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="ss">error</span><span class="p">:</span><span class="w"> </span><span class="n">result</span><span class="o">[</span><span class="ss">:error</span><span class="o">]</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="k">unless</span><span class="w"> </span><span class="n">result</span><span class="o">[</span><span class="ss">:success</span><span class="o">]</span>
+</span><span id="__span-22-15"><a id="__codelineno-22-15" name="__codelineno-22-15" href="#__codelineno-22-15"></a>
+</span><span id="__span-22-16"><a id="__codelineno-22-16" name="__codelineno-22-16" href="#__codelineno-22-16"></a><span class="w">    </span><span class="c1"># Update status</span>
+</span><span id="__span-22-17"><a id="__codelineno-22-17" name="__codelineno-22-17" href="#__codelineno-22-17"></a><span class="w">    </span><span class="n">order</span><span class="o">.</span><span class="n">update!</span><span class="p">(</span><span class="ss">status</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;paid&quot;</span><span class="p">)</span>
+</span><span id="__span-22-18"><a id="__codelineno-22-18" name="__codelineno-22-18" href="#__codelineno-22-18"></a>
+</span><span id="__span-22-19"><a id="__codelineno-22-19" name="__codelineno-22-19" href="#__codelineno-22-19"></a><span class="w">    </span><span class="p">{</span><span class="w"> </span><span class="ss">success</span><span class="p">:</span><span class="w"> </span><span class="kp">true</span><span class="p">,</span><span class="w"> </span><span class="ss">order_id</span><span class="p">:</span><span class="w"> </span><span class="n">order</span><span class="o">.</span><span class="n">id</span><span class="p">,</span><span class="w"> </span><span class="ss">amount</span><span class="p">:</span><span class="w"> </span><span class="n">order</span><span class="o">.</span><span class="n">total</span><span class="w"> </span><span class="p">}</span>
+</span><span id="__span-22-20"><a id="__codelineno-22-20" name="__codelineno-22-20" href="#__codelineno-22-20"></a><span class="w">  </span><span class="k">end</span>
+</span><span id="__span-22-21"><a id="__codelineno-22-21" name="__codelineno-22-21" href="#__codelineno-22-21"></a><span class="k">end</span>
+</span></code></pre></div>
+<h2 id="tool-return-values">Tool Return Values<a class="headerlink" href="#tool-return-values" title="Permanent link">&para;</a></h2>
+<h3 id="structured-data">Structured Data<a class="headerlink" href="#structured-data" title="Permanent link">&para;</a></h3>
+<p>Return hashes with consistent structure:</p>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-23-1"><a id="__codelineno-23-1" name="__codelineno-23-1" href="#__codelineno-23-1"></a><span class="k">def</span><span class="w"> </span><span class="nf">execute</span><span class="p">(</span><span class="ss">user_id</span><span class="p">:)</span>
+</span><span id="__span-23-2"><a id="__codelineno-23-2" name="__codelineno-23-2" href="#__codelineno-23-2"></a><span class="w">  </span><span class="n">user</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">User</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">user_id</span><span class="p">)</span>
+</span><span id="__span-23-3"><a id="__codelineno-23-3" name="__codelineno-23-3" href="#__codelineno-23-3"></a><span class="w">  </span><span class="p">{</span>
+</span><span id="__span-23-4"><a id="__codelineno-23-4" name="__codelineno-23-4" href="#__codelineno-23-4"></a><span class="w">    </span><span class="nb">id</span><span class="p">:</span><span class="w"> </span><span class="n">user</span><span class="o">.</span><span class="n">id</span><span class="p">,</span>
+</span><span id="__span-23-5"><a id="__codelineno-23-5" name="__codelineno-23-5" href="#__codelineno-23-5"></a><span class="w">    </span><span class="nb">name</span><span class="p">:</span><span class="w"> </span><span class="n">user</span><span class="o">.</span><span class="n">name</span><span class="p">,</span>
+</span><span id="__span-23-6"><a id="__codelineno-23-6" name="__codelineno-23-6" href="#__codelineno-23-6"></a><span class="w">    </span><span class="ss">email</span><span class="p">:</span><span class="w"> </span><span class="n">user</span><span class="o">.</span><span class="n">email</span><span class="p">,</span>
+</span><span id="__span-23-7"><a id="__codelineno-23-7" name="__codelineno-23-7" href="#__codelineno-23-7"></a><span class="w">    </span><span class="ss">created_at</span><span class="p">:</span><span class="w"> </span><span class="n">user</span><span class="o">.</span><span class="n">created_at</span><span class="o">.</span><span class="n">iso8601</span>
+</span><span id="__span-23-8"><a id="__codelineno-23-8" name="__codelineno-23-8" href="#__codelineno-23-8"></a><span class="w">  </span><span class="p">}</span>
+</span><span id="__span-23-9"><a id="__codelineno-23-9" name="__codelineno-23-9" href="#__codelineno-23-9"></a><span class="k">end</span>
+</span></code></pre></div>
+<h3 id="simple-values">Simple Values<a class="headerlink" href="#simple-values" title="Permanent link">&para;</a></h3>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-24-1"><a id="__codelineno-24-1" name="__codelineno-24-1" href="#__codelineno-24-1"></a><span class="k">def</span><span class="w"> </span><span class="nf">execute</span><span class="p">(</span><span class="o">**</span><span class="n">_</span><span class="p">)</span>
+</span><span id="__span-24-2"><a id="__codelineno-24-2" name="__codelineno-24-2" href="#__codelineno-24-2"></a><span class="w">  </span><span class="no">Time</span><span class="o">.</span><span class="n">now</span><span class="o">.</span><span class="n">to_s</span>
+</span><span id="__span-24-3"><a id="__codelineno-24-3" name="__codelineno-24-3" href="#__codelineno-24-3"></a><span class="k">end</span>
+</span></code></pre></div>
+<h3 id="lists">Lists<a class="headerlink" href="#lists" title="Permanent link">&para;</a></h3>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-25-1"><a id="__codelineno-25-1" name="__codelineno-25-1" href="#__codelineno-25-1"></a><span class="k">def</span><span class="w"> </span><span class="nf">execute</span><span class="p">(</span><span class="ss">query</span><span class="p">:)</span>
+</span><span id="__span-25-2"><a id="__codelineno-25-2" name="__codelineno-25-2" href="#__codelineno-25-2"></a><span class="w">  </span><span class="n">results</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">Search</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">query</span><span class="p">)</span>
+</span><span id="__span-25-3"><a id="__codelineno-25-3" name="__codelineno-25-3" href="#__codelineno-25-3"></a><span class="w">  </span><span class="n">results</span><span class="o">.</span><span class="n">map</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">|</span><span class="n">r</span><span class="o">|</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nb">id</span><span class="p">:</span><span class="w"> </span><span class="n">r</span><span class="o">.</span><span class="n">id</span><span class="p">,</span><span class="w"> </span><span class="ss">title</span><span class="p">:</span><span class="w"> </span><span class="n">r</span><span class="o">.</span><span class="n">title</span><span class="p">,</span><span class="w"> </span><span class="ss">score</span><span class="p">:</span><span class="w"> </span><span class="n">r</span><span class="o">.</span><span class="n">score</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span>
+</span><span id="__span-25-4"><a id="__codelineno-25-4" name="__codelineno-25-4" href="#__codelineno-25-4"></a><span class="k">end</span>
+</span></code></pre></div>
+<h2 id="error-handling">Error Handling<a class="headerlink" href="#error-handling" title="Permanent link">&para;</a></h2>
+<h3 id="automatic-error-handling">Automatic Error Handling<a class="headerlink" href="#automatic-error-handling" title="Permanent link">&para;</a></h3>
+<p><code>RobotLab::Tool</code> automatically catches <code>StandardError</code> exceptions from <code>execute</code> and returns a plain-text error string to the LLM. The LLM can then reason about the failure and try an alternative approach — without crashing the run.</p>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-26-1"><a id="__codelineno-26-1" name="__codelineno-26-1" href="#__codelineno-26-1"></a><span class="k">class</span><span class="w"> </span><span class="nc">FetchResource</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="no">RobotLab</span><span class="o">::</span><span class="no">Tool</span>
+</span><span id="__span-26-2"><a id="__codelineno-26-2" name="__codelineno-26-2" href="#__codelineno-26-2"></a><span class="w">  </span><span class="n">description</span><span class="w"> </span><span class="s2">&quot;Fetch a resource from an external API&quot;</span>
+</span><span id="__span-26-3"><a id="__codelineno-26-3" name="__codelineno-26-3" href="#__codelineno-26-3"></a><span class="w">  </span><span class="n">param</span><span class="w"> </span><span class="ss">:id</span><span class="p">,</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="ss">:string</span><span class="p">,</span><span class="w"> </span><span class="ss">desc</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Resource ID&quot;</span>
+</span><span id="__span-26-4"><a id="__codelineno-26-4" name="__codelineno-26-4" href="#__codelineno-26-4"></a>
+</span><span id="__span-26-5"><a id="__codelineno-26-5" name="__codelineno-26-5" href="#__codelineno-26-5"></a><span class="w">  </span><span class="k">def</span><span class="w"> </span><span class="nf">execute</span><span class="p">(</span><span class="nb">id</span><span class="p">:)</span>
+</span><span id="__span-26-6"><a id="__codelineno-26-6" name="__codelineno-26-6" href="#__codelineno-26-6"></a><span class="w">    </span><span class="no">ExternalAPI</span><span class="o">.</span><span class="n">fetch</span><span class="p">(</span><span class="nb">id</span><span class="p">)</span>
+</span><span id="__span-26-7"><a id="__codelineno-26-7" name="__codelineno-26-7" href="#__codelineno-26-7"></a><span class="w">  </span><span class="k">end</span>
+</span><span id="__span-26-8"><a id="__codelineno-26-8" name="__codelineno-26-8" href="#__codelineno-26-8"></a><span class="k">end</span>
+</span><span id="__span-26-9"><a id="__codelineno-26-9" name="__codelineno-26-9" href="#__codelineno-26-9"></a>
+</span><span id="__span-26-10"><a id="__codelineno-26-10" name="__codelineno-26-10" href="#__codelineno-26-10"></a><span class="n">tool</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">FetchResource</span><span class="o">.</span><span class="n">new</span>
+</span><span id="__span-26-11"><a id="__codelineno-26-11" name="__codelineno-26-11" href="#__codelineno-26-11"></a><span class="n">result</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">tool</span><span class="o">.</span><span class="n">call</span><span class="p">({</span><span class="w"> </span><span class="s2">&quot;id&quot;</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="s2">&quot;missing&quot;</span><span class="w"> </span><span class="p">})</span>
+</span><span id="__span-26-12"><a id="__codelineno-26-12" name="__codelineno-26-12" href="#__codelineno-26-12"></a><span class="c1"># If ExternalAPI.fetch raises, result is:</span>
+</span><span id="__span-26-13"><a id="__codelineno-26-13" name="__codelineno-26-13" href="#__codelineno-26-13"></a><span class="c1"># =&gt; &quot;Error (fetch_resource): connection refused&quot;</span>
+</span></code></pre></div>
+<p>This applies to all <code>RobotLab::Tool</code> variants — subclasses, <code>Tool.create</code> factory tools, and MCP tools. Errors are also logged via <code>RobotLab.config.logger</code> at <code>:warn</code> level.</p>
+<h3 id="critical-tools-opt-out">Critical Tools (Opt-Out)<a class="headerlink" href="#critical-tools-opt-out" title="Permanent link">&para;</a></h3>
+<p>For tools where you want exceptions to propagate (e.g., a tool whose failure should abort the run), set <code>raise_on_error</code> on the class:</p>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-27-1"><a id="__codelineno-27-1" name="__codelineno-27-1" href="#__codelineno-27-1"></a><span class="k">class</span><span class="w"> </span><span class="nc">CriticalPayment</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="no">RobotLab</span><span class="o">::</span><span class="no">Tool</span>
+</span><span id="__span-27-2"><a id="__codelineno-27-2" name="__codelineno-27-2" href="#__codelineno-27-2"></a><span class="w">  </span><span class="nb">self</span><span class="o">.</span><span class="n">raise_on_error</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kp">true</span>
+</span><span id="__span-27-3"><a id="__codelineno-27-3" name="__codelineno-27-3" href="#__codelineno-27-3"></a>
+</span><span id="__span-27-4"><a id="__codelineno-27-4" name="__codelineno-27-4" href="#__codelineno-27-4"></a><span class="w">  </span><span class="n">description</span><span class="w"> </span><span class="s2">&quot;Process a payment&quot;</span>
+</span><span id="__span-27-5"><a id="__codelineno-27-5" name="__codelineno-27-5" href="#__codelineno-27-5"></a><span class="w">  </span><span class="n">param</span><span class="w"> </span><span class="ss">:amount</span><span class="p">,</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="ss">:number</span><span class="p">,</span><span class="w"> </span><span class="ss">desc</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Payment amount&quot;</span>
+</span><span id="__span-27-6"><a id="__codelineno-27-6" name="__codelineno-27-6" href="#__codelineno-27-6"></a>
+</span><span id="__span-27-7"><a id="__codelineno-27-7" name="__codelineno-27-7" href="#__codelineno-27-7"></a><span class="w">  </span><span class="k">def</span><span class="w"> </span><span class="nf">execute</span><span class="p">(</span><span class="ss">amount</span><span class="p">:)</span>
+</span><span id="__span-27-8"><a id="__codelineno-27-8" name="__codelineno-27-8" href="#__codelineno-27-8"></a><span class="w">    </span><span class="no">PaymentGateway</span><span class="o">.</span><span class="n">charge</span><span class="p">(</span><span class="n">amount</span><span class="p">)</span>
+</span><span id="__span-27-9"><a id="__codelineno-27-9" name="__codelineno-27-9" href="#__codelineno-27-9"></a><span class="w">  </span><span class="k">end</span>
+</span><span id="__span-27-10"><a id="__codelineno-27-10" name="__codelineno-27-10" href="#__codelineno-27-10"></a><span class="k">end</span>
+</span></code></pre></div>
+<p><code>raise_on_error</code> is per-class and defaults to <code>false</code>. Setting it on one class does not affect others.</p>
+<h3 id="manual-error-handling">Manual Error Handling<a class="headerlink" href="#manual-error-handling" title="Permanent link">&para;</a></h3>
+<p>You can still handle specific errors inside <code>execute</code> for domain-specific responses:</p>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-28-1"><a id="__codelineno-28-1" name="__codelineno-28-1" href="#__codelineno-28-1"></a><span class="k">class</span><span class="w"> </span><span class="nc">FetchResource</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="no">RobotLab</span><span class="o">::</span><span class="no">Tool</span>
+</span><span id="__span-28-2"><a id="__codelineno-28-2" name="__codelineno-28-2" href="#__codelineno-28-2"></a><span class="w">  </span><span class="n">description</span><span class="w"> </span><span class="s2">&quot;Fetch a resource from an external API&quot;</span>
+</span><span id="__span-28-3"><a id="__codelineno-28-3" name="__codelineno-28-3" href="#__codelineno-28-3"></a><span class="w">  </span><span class="n">param</span><span class="w"> </span><span class="ss">:id</span><span class="p">,</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="ss">:string</span><span class="p">,</span><span class="w"> </span><span class="ss">desc</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Resource ID&quot;</span>
+</span><span id="__span-28-4"><a id="__codelineno-28-4" name="__codelineno-28-4" href="#__codelineno-28-4"></a>
+</span><span id="__span-28-5"><a id="__codelineno-28-5" name="__codelineno-28-5" href="#__codelineno-28-5"></a><span class="w">  </span><span class="k">def</span><span class="w"> </span><span class="nf">execute</span><span class="p">(</span><span class="nb">id</span><span class="p">:)</span>
+</span><span id="__span-28-6"><a id="__codelineno-28-6" name="__codelineno-28-6" href="#__codelineno-28-6"></a><span class="w">    </span><span class="n">result</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">ExternalAPI</span><span class="o">.</span><span class="n">fetch</span><span class="p">(</span><span class="nb">id</span><span class="p">)</span>
+</span><span id="__span-28-7"><a id="__codelineno-28-7" name="__codelineno-28-7" href="#__codelineno-28-7"></a><span class="w">    </span><span class="p">{</span><span class="w"> </span><span class="ss">success</span><span class="p">:</span><span class="w"> </span><span class="kp">true</span><span class="p">,</span><span class="w"> </span><span class="ss">data</span><span class="p">:</span><span class="w"> </span><span class="n">result</span><span class="w"> </span><span class="p">}</span>
+</span><span id="__span-28-8"><a id="__codelineno-28-8" name="__codelineno-28-8" href="#__codelineno-28-8"></a><span class="w">  </span><span class="k">rescue</span><span class="w"> </span><span class="no">ExternalAPI</span><span class="o">::</span><span class="no">NotFound</span>
+</span><span id="__span-28-9"><a id="__codelineno-28-9" name="__codelineno-28-9" href="#__codelineno-28-9"></a><span class="w">    </span><span class="p">{</span><span class="w"> </span><span class="ss">success</span><span class="p">:</span><span class="w"> </span><span class="kp">false</span><span class="p">,</span><span class="w"> </span><span class="ss">error</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Resource not found&quot;</span><span class="p">,</span><span class="w"> </span><span class="nb">id</span><span class="p">:</span><span class="w"> </span><span class="nb">id</span><span class="w"> </span><span class="p">}</span>
+</span><span id="__span-28-10"><a id="__codelineno-28-10" name="__codelineno-28-10" href="#__codelineno-28-10"></a><span class="w">  </span><span class="k">rescue</span><span class="w"> </span><span class="no">ExternalAPI</span><span class="o">::</span><span class="no">RateLimited</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="n">e</span>
+</span><span id="__span-28-11"><a id="__codelineno-28-11" name="__codelineno-28-11" href="#__codelineno-28-11"></a><span class="w">    </span><span class="p">{</span><span class="w"> </span><span class="ss">success</span><span class="p">:</span><span class="w"> </span><span class="kp">false</span><span class="p">,</span><span class="w"> </span><span class="ss">error</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Rate limited&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">retry_after</span><span class="p">:</span><span class="w"> </span><span class="n">e</span><span class="o">.</span><span class="n">retry_after</span><span class="w"> </span><span class="p">}</span>
+</span><span id="__span-28-12"><a id="__codelineno-28-12" name="__codelineno-28-12" href="#__codelineno-28-12"></a><span class="w">  </span><span class="k">end</span>
+</span><span id="__span-28-13"><a id="__codelineno-28-13" name="__codelineno-28-13" href="#__codelineno-28-13"></a><span class="w">  </span><span class="c1"># Any other StandardError is still caught by the automatic handler</span>
+</span><span id="__span-28-14"><a id="__codelineno-28-14" name="__codelineno-28-14" href="#__codelineno-28-14"></a><span class="k">end</span>
+</span></code></pre></div>
+<h2 id="tool-callbacks">Tool Callbacks<a class="headerlink" href="#tool-callbacks" title="Permanent link">&para;</a></h2>
+<p>Robots support <code>on_tool_call</code> and <code>on_tool_result</code> callbacks for monitoring tool usage:</p>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-29-1"><a id="__codelineno-29-1" name="__codelineno-29-1" href="#__codelineno-29-1"></a><span class="n">robot</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">RobotLab</span><span class="o">.</span><span class="n">build</span><span class="p">(</span>
+</span><span id="__span-29-2"><a id="__codelineno-29-2" name="__codelineno-29-2" href="#__codelineno-29-2"></a><span class="w">  </span><span class="nb">name</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;assistant&quot;</span><span class="p">,</span>
+</span><span id="__span-29-3"><a id="__codelineno-29-3" name="__codelineno-29-3" href="#__codelineno-29-3"></a><span class="w">  </span><span class="ss">system_prompt</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;...&quot;</span><span class="p">,</span>
+</span><span id="__span-29-4"><a id="__codelineno-29-4" name="__codelineno-29-4" href="#__codelineno-29-4"></a><span class="w">  </span><span class="ss">local_tools</span><span class="p">:</span><span class="w"> </span><span class="o">[</span><span class="no">GetWeather</span><span class="o">]</span><span class="p">,</span>
+</span><span id="__span-29-5"><a id="__codelineno-29-5" name="__codelineno-29-5" href="#__codelineno-29-5"></a><span class="w">  </span><span class="ss">on_tool_call</span><span class="p">:</span><span class="w"> </span><span class="o">-&gt;</span><span class="p">(</span><span class="n">call</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nb">puts</span><span class="w"> </span><span class="s2">&quot;Calling: </span><span class="si">#{</span><span class="n">call</span><span class="si">}</span><span class="s2">&quot;</span><span class="w"> </span><span class="p">},</span>
+</span><span id="__span-29-6"><a id="__codelineno-29-6" name="__codelineno-29-6" href="#__codelineno-29-6"></a><span class="w">  </span><span class="ss">on_tool_result</span><span class="p">:</span><span class="w"> </span><span class="o">-&gt;</span><span class="p">(</span><span class="n">result</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nb">puts</span><span class="w"> </span><span class="s2">&quot;Result: </span><span class="si">#{</span><span class="n">result</span><span class="si">}</span><span class="s2">&quot;</span><span class="w"> </span><span class="p">}</span>
+</span><span id="__span-29-7"><a id="__codelineno-29-7" name="__codelineno-29-7" href="#__codelineno-29-7"></a><span class="p">)</span>
+</span></code></pre></div>
+<h2 id="robotlabtoolcreate-with-schema">RobotLab::Tool.create with Schema<a class="headerlink" href="#robotlabtoolcreate-with-schema" title="Permanent link">&para;</a></h2>
+<p>For dynamic tools via <code>Tool.create</code>, pass parameters as a JSON Schema hash:</p>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-30-1"><a id="__codelineno-30-1" name="__codelineno-30-1" href="#__codelineno-30-1"></a><span class="n">tool</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="no">RobotLab</span><span class="o">::</span><span class="no">Tool</span><span class="o">.</span><span class="n">create</span><span class="p">(</span>
+</span><span id="__span-30-2"><a id="__codelineno-30-2" name="__codelineno-30-2" href="#__codelineno-30-2"></a><span class="w">  </span><span class="nb">name</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;search&quot;</span><span class="p">,</span>
+</span><span id="__span-30-3"><a id="__codelineno-30-3" name="__codelineno-30-3" href="#__codelineno-30-3"></a><span class="w">  </span><span class="ss">description</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Search for items&quot;</span><span class="p">,</span>
+</span><span id="__span-30-4"><a id="__codelineno-30-4" name="__codelineno-30-4" href="#__codelineno-30-4"></a><span class="w">  </span><span class="ss">parameters</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
+</span><span id="__span-30-5"><a id="__codelineno-30-5" name="__codelineno-30-5" href="#__codelineno-30-5"></a><span class="w">    </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;object&quot;</span><span class="p">,</span>
+</span><span id="__span-30-6"><a id="__codelineno-30-6" name="__codelineno-30-6" href="#__codelineno-30-6"></a><span class="w">    </span><span class="ss">properties</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
+</span><span id="__span-30-7"><a id="__codelineno-30-7" name="__codelineno-30-7" href="#__codelineno-30-7"></a><span class="w">      </span><span class="ss">query</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;string&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">description</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Search query&quot;</span><span class="w"> </span><span class="p">},</span>
+</span><span id="__span-30-8"><a id="__codelineno-30-8" name="__codelineno-30-8" href="#__codelineno-30-8"></a><span class="w">      </span><span class="ss">limit</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="ss">type</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;integer&quot;</span><span class="p">,</span><span class="w"> </span><span class="ss">description</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Max results&quot;</span><span class="w"> </span><span class="p">}</span>
+</span><span id="__span-30-9"><a id="__codelineno-30-9" name="__codelineno-30-9" href="#__codelineno-30-9"></a><span class="w">    </span><span class="p">},</span>
+</span><span id="__span-30-10"><a id="__codelineno-30-10" name="__codelineno-30-10" href="#__codelineno-30-10"></a><span class="w">    </span><span class="ss">required</span><span class="p">:</span><span class="w"> </span><span class="o">[</span><span class="s2">&quot;query&quot;</span><span class="o">]</span>
+</span><span id="__span-30-11"><a id="__codelineno-30-11" name="__codelineno-30-11" href="#__codelineno-30-11"></a><span class="w">  </span><span class="p">}</span>
+</span><span id="__span-30-12"><a id="__codelineno-30-12" name="__codelineno-30-12" href="#__codelineno-30-12"></a><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">|</span><span class="n">args</span><span class="o">|</span><span class="w"> </span><span class="no">Search</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">args</span><span class="o">[</span><span class="ss">:query</span><span class="o">]</span><span class="p">,</span><span class="w"> </span><span class="ss">limit</span><span class="p">:</span><span class="w"> </span><span class="n">args</span><span class="o">[</span><span class="ss">:limit</span><span class="o">]</span><span class="w"> </span><span class="o">||</span><span class="w"> </span><span class="mi">10</span><span class="p">)</span><span class="w"> </span><span class="p">}</span>
+</span></code></pre></div>
+<h2 id="best-practices">Best Practices<a class="headerlink" href="#best-practices" title="Permanent link">&para;</a></h2>
+<h3 id="1-clear-descriptions">1. Clear Descriptions<a class="headerlink" href="#1-clear-descriptions" title="Permanent link">&para;</a></h3>
+<p>Write descriptions that help the LLM understand when and how to use the tool:</p>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-31-1"><a id="__codelineno-31-1" name="__codelineno-31-1" href="#__codelineno-31-1"></a><span class="c1"># Good: Specific and actionable</span>
+</span><span id="__span-31-2"><a id="__codelineno-31-2" name="__codelineno-31-2" href="#__codelineno-31-2"></a><span class="k">class</span><span class="w"> </span><span class="nc">SearchOrders</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="no">RubyLLM</span><span class="o">::</span><span class="no">Tool</span>
+</span><span id="__span-31-3"><a id="__codelineno-31-3" name="__codelineno-31-3" href="#__codelineno-31-3"></a><span class="w">  </span><span class="n">description</span><span class="w"> </span><span class="s2">&quot;Search customer orders by date range, status, or customer email. Returns up to 50 matching orders sorted by date.&quot;</span>
+</span><span id="__span-31-4"><a id="__codelineno-31-4" name="__codelineno-31-4" href="#__codelineno-31-4"></a><span class="w">  </span><span class="c1"># ...</span>
+</span><span id="__span-31-5"><a id="__codelineno-31-5" name="__codelineno-31-5" href="#__codelineno-31-5"></a><span class="k">end</span>
+</span><span id="__span-31-6"><a id="__codelineno-31-6" name="__codelineno-31-6" href="#__codelineno-31-6"></a>
+</span><span id="__span-31-7"><a id="__codelineno-31-7" name="__codelineno-31-7" href="#__codelineno-31-7"></a><span class="c1"># Bad: Vague</span>
+</span><span id="__span-31-8"><a id="__codelineno-31-8" name="__codelineno-31-8" href="#__codelineno-31-8"></a><span class="k">class</span><span class="w"> </span><span class="nc">Search</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="no">RubyLLM</span><span class="o">::</span><span class="no">Tool</span>
+</span><span id="__span-31-9"><a id="__codelineno-31-9" name="__codelineno-31-9" href="#__codelineno-31-9"></a><span class="w">  </span><span class="n">description</span><span class="w"> </span><span class="s2">&quot;Searches stuff&quot;</span>
+</span><span id="__span-31-10"><a id="__codelineno-31-10" name="__codelineno-31-10" href="#__codelineno-31-10"></a><span class="w">  </span><span class="c1"># ...</span>
+</span><span id="__span-31-11"><a id="__codelineno-31-11" name="__codelineno-31-11" href="#__codelineno-31-11"></a><span class="k">end</span>
+</span></code></pre></div>
+<h3 id="2-validate-inputs">2. Validate Inputs<a class="headerlink" href="#2-validate-inputs" title="Permanent link">&para;</a></h3>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-32-1"><a id="__codelineno-32-1" name="__codelineno-32-1" href="#__codelineno-32-1"></a><span class="k">def</span><span class="w"> </span><span class="nf">execute</span><span class="p">(</span><span class="ss">email</span><span class="p">:)</span>
+</span><span id="__span-32-2"><a id="__codelineno-32-2" name="__codelineno-32-2" href="#__codelineno-32-2"></a><span class="w">  </span><span class="k">unless</span><span class="w"> </span><span class="n">email</span><span class="o">.</span><span class="n">match?</span><span class="p">(</span><span class="sr">/\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i</span><span class="p">)</span>
+</span><span id="__span-32-3"><a id="__codelineno-32-3" name="__codelineno-32-3" href="#__codelineno-32-3"></a><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="ss">error</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Invalid email format&quot;</span><span class="w"> </span><span class="p">}</span>
+</span><span id="__span-32-4"><a id="__codelineno-32-4" name="__codelineno-32-4" href="#__codelineno-32-4"></a><span class="w">  </span><span class="k">end</span>
+</span><span id="__span-32-5"><a id="__codelineno-32-5" name="__codelineno-32-5" href="#__codelineno-32-5"></a><span class="w">  </span><span class="c1"># ... rest of logic</span>
+</span><span id="__span-32-6"><a id="__codelineno-32-6" name="__codelineno-32-6" href="#__codelineno-32-6"></a><span class="k">end</span>
+</span></code></pre></div>
+<h3 id="3-return-structured-data">3. Return Structured Data<a class="headerlink" href="#3-return-structured-data" title="Permanent link">&para;</a></h3>
+<div class="language-ruby highlight"><pre><span></span><code><span id="__span-33-1"><a id="__codelineno-33-1" name="__codelineno-33-1" href="#__codelineno-33-1"></a><span class="c1"># Good: Structured and consistent</span>
+</span><span id="__span-33-2"><a id="__codelineno-33-2" name="__codelineno-33-2" href="#__codelineno-33-2"></a><span class="k">def</span><span class="w"> </span><span class="nf">execute</span><span class="p">(</span><span class="o">**</span><span class="n">_</span><span class="p">)</span>
+</span><span id="__span-33-3"><a id="__codelineno-33-3" name="__codelineno-33-3" href="#__codelineno-33-3"></a><span class="w">  </span><span class="p">{</span>
+</span><span id="__span-33-4"><a id="__codelineno-33-4" name="__codelineno-33-4" href="#__codelineno-33-4"></a><span class="w">    </span><span class="ss">success</span><span class="p">:</span><span class="w"> </span><span class="kp">true</span><span class="p">,</span>
+</span><span id="__span-33-5"><a id="__codelineno-33-5" name="__codelineno-33-5" href="#__codelineno-33-5"></a><span class="w">    </span><span class="ss">data</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nb">id</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="nb">name</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Item&quot;</span><span class="w"> </span><span class="p">},</span>
+</span><span id="__span-33-6"><a id="__codelineno-33-6" name="__codelineno-33-6" href="#__codelineno-33-6"></a><span class="w">    </span><span class="ss">metadata</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="ss">fetched_at</span><span class="p">:</span><span class="w"> </span><span class="no">Time</span><span class="o">.</span><span class="n">now</span><span class="o">.</span><span class="n">iso8601</span><span class="w"> </span><span class="p">}</span>
+</span><span id="__span-33-7"><a id="__codelineno-33-7" name="__codelineno-33-7" href="#__codelineno-33-7"></a><span class="w">  </span><span class="p">}</span>
+</span><span id="__span-33-8"><a id="__codelineno-33-8" name="__codelineno-33-8" href="#__codelineno-33-8"></a><span class="k">end</span>
+</span><span id="__span-33-9"><a id="__codelineno-33-9" name="__codelineno-33-9" href="#__codelineno-33-9"></a>
+</span><span id="__span-33-10"><a id="__codelineno-33-10" name="__codelineno-33-10" href="#__codelineno-33-10"></a><span class="c1"># Bad: Unstructured</span>
+</span><span id="__span-33-11"><a id="__codelineno-33-11" name="__codelineno-33-11" href="#__codelineno-33-11"></a><span class="k">def</span><span class="w"> </span><span class="nf">execute</span><span class="p">(</span><span class="o">**</span><span class="n">_</span><span class="p">)</span>
+</span><span id="__span-33-12"><a id="__codelineno-33-12" name="__codelineno-33-12" href="#__codelineno-33-12"></a><span class="w">  </span><span class="s2">&quot;Found item with id 1 named Item&quot;</span>
+</span><span id="__span-33-13"><a id="__codelineno-33-13" name="__codelineno-33-13" href="#__codelineno-33-13"></a><span class="k">end</span>
+</span></code></pre></div>
+<h3 id="4-keep-tools-focused">4. Keep Tools Focused<a class="headerlink" href="#4-keep-tools-focused" title="Permanent link">&para;</a></h3>
+<p>Each tool should do one thing well. Prefer multiple focused tools over one tool that does everything.</p>
+<h2 id="next-steps">Next Steps<a class="headerlink" href="#next-steps" title="Permanent link">&para;</a></h2>
+<ul>
+<li><a href="../mcp-integration/">MCP Integration</a> - External tool servers</li>
+<li><a href="../building-robots/">Building Robots</a> - Robot creation patterns</li>
+<li><a href="../../api/core/tool/">API Reference: Tool</a> - Complete API</li>
+</ul>
+  <form class="md-feedback" name="feedback" hidden>
+    <fieldset>
+      <legend class="md-feedback__title">
+        Was this page helpful?
+      </legend>
+      <div class="md-feedback__inner">
+        <div class="md-feedback__list">
+            <button class="md-feedback__icon md-icon" type="submit" title="This page was helpful" data-md-value="1">
+              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 12a8 8 0 0 0-8-8 8 8 0 0 0-8 8 8 8 0 0 0 8 8 8 8 0 0 0 8-8m2 0a10 10 0 0 1-10 10A10 10 0 0 1 2 12 10 10 0 0 1 12 2a10 10 0 0 1 10 10M10 9.5c0 .8-.7 1.5-1.5 1.5S7 10.3 7 9.5 7.7 8 8.5 8s1.5.7 1.5 1.5m7 0c0 .8-.7 1.5-1.5 1.5S14 10.3 14 9.5 14.7 8 15.5 8s1.5.7 1.5 1.5m-5 7.73c-1.75 0-3.29-.73-4.19-1.81L9.23 14c.45.72 1.52 1.23 2.77 1.23s2.32-.51 2.77-1.23l1.42 1.42c-.9 1.08-2.44 1.81-4.19 1.81"/></svg>
+            </button>
+            <button class="md-feedback__icon md-icon" type="submit" title="This page could be improved" data-md-value="0">
+              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 12a8 8 0 0 0-8-8 8 8 0 0 0-8 8 8 8 0 0 0 8 8 8 8 0 0 0 8-8m2 0a10 10 0 0 1-10 10A10 10 0 0 1 2 12 10 10 0 0 1 12 2a10 10 0 0 1 10 10m-6.5-4c.8 0 1.5.7 1.5 1.5s-.7 1.5-1.5 1.5-1.5-.7-1.5-1.5.7-1.5 1.5-1.5M10 9.5c0 .8-.7 1.5-1.5 1.5S7 10.3 7 9.5 7.7 8 8.5 8s1.5.7 1.5 1.5m2 4.5c1.75 0 3.29.72 4.19 1.81l-1.42 1.42C14.32 16.5 13.25 16 12 16s-2.32.5-2.77 1.23l-1.42-1.42C8.71 14.72 10.25 14 12 14"/></svg>
+            </button>
+        </div>
+        <div class="md-feedback__note">
+            <div data-md-value="1" hidden>
+              Thanks for your feedback!
+            </div>
+            <div data-md-value="0" hidden>
+              Thanks for your feedback! Help us improve by creating an issue.
+            </div>
+        </div>
+      </div>
+    </fieldset>
+  </form>
+              </article>
+            </div>
+  <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script>
+<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
+        </div>
+          <button type="button" class="md-top md-icon" data-md-component="top" hidden>
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg>
+  Back to top
+</button>
+      </main>
+        <footer class="md-footer">
+      <nav class="md-footer__inner md-grid" aria-label="Footer" >
+          <a href="../creating-networks/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Creating Networks">
+            <div class="md-footer__button md-icon">
+              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
+            </div>
+            <div class="md-footer__title">
+              <span class="md-footer__direction">
+                Previous
+              </span>
+              <div class="md-ellipsis">
+                Creating Networks
+              </div>
+            </div>
+          </a>
+          <a href="../mcp-integration/" class="md-footer__link md-footer__link--next" aria-label="Next: MCP Integration">
+            <div class="md-footer__title">
+              <span class="md-footer__direction">
+                Next
+              </span>
+              <div class="md-ellipsis">
+                MCP Integration
+              </div>
+            </div>
+            <div class="md-footer__button md-icon">
+              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg>
+            </div>
+          </a>
+      </nav>
+  <div class="md-footer-meta md-typeset">
+    <div class="md-footer-meta__inner md-grid">
+      <div class="md-copyright">
+    <div class="md-copyright__highlight">
+      Copyright &copy; 2025 Dewayne VanHoozer
+    </div>
+    Made with
+    <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
+      Material for MkDocs
+    </a>
+</div>
+<div class="md-social">
+    <a href="https://github.com/madbomber/robot_lab" target="_blank" rel="noopener" title="RobotLab on GitHub" class="md-social__link">
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg>
+    </a>
+    <a href="https://rubygems.org/gems/robot_lab" target="_blank" rel="noopener" title="RobotLab on RubyGems" class="md-social__link">
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M116.7 33.8c4.5-6.1 11.7-9.8 19.3-9.8h240c7.6 0 14.8 3.6 19.3 9.8l112 152c6.8 9.2 6.1 21.9-1.5 30.4l-232 256c-4.5 5-11 7.9-17.8 7.9s-13.2-2.9-17.8-7.9l-232-256c-7.7-8.5-8.3-21.2-1.5-30.4zm38.5 39.8c-3.3 2.5-4.2 7-2.1 10.5l57.4 95.7L63.3 192c-4.1.3-7.3 3.8-7.3 8s3.2 7.6 7.3 8l192 16h1.3l192-16c4.1-.3 7.3-3.8 7.3-8s-3.2-7.6-7.3-8l-147.2-12.3 57.4-95.6c2.1-3.5 1.2-8.1-2.1-10.5s-7.9-2-10.7 1l-90 97.6-90.1-97.6c-2.8-3-7.4-3.4-10.7-1"/></svg>
+    </a>
+</div>
+    </div>
+  </div>
+</footer>
+    </div>
+    <div class="md-dialog" data-md-component="dialog">
+      <div class="md-dialog__inner md-typeset"></div>
+    </div>
+      <script id="__config" type="application/json">{"annotate": null, "base": "../..", "features": ["navigation.instant", "navigation.tracking", "navigation.tabs", "navigation.tabs.sticky", "navigation.path", "navigation.indexes", "navigation.top", "navigation.footer", "toc.follow", "search.suggest", "search.highlight", "search.share", "header.autohide", "content.code.copy", "content.code.annotate", "content.tabs.link", "content.tooltips", "content.action.edit", "content.action.view"], "search": "../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
+      <script src="../../assets/javascripts/bundle.79ae519e.min.js"></script>
+  </body>
+</html>