Initial Commit

2026-09-15 15:24:03 -04:00
commit 4dc7086e7e
605 changed files with 101380 additions and 0 deletions
@@ -0,0 +1,88 @@
+# The tools
+
+Twenty-two, in five groups. All are on by default; turn any off in
+[`../configs/tools.toml`](../configs/tools.toml), which removes them from the spec entirely
+rather than hiding them.
+
+The **Setup** column is empty when a tool needs nothing beyond `docker compose up -d`.
+
+## Web and research
+
+| Tool | What it does | Setup |
+|---|---|---|
+| `web_search` | Searches the web through SearXNG and returns titles, URLs and snippets | [searxng](setup/searxng.md) |
+| `fetch_page` | Reads a web page or PDF as text, windowed so a 200-page manual cannot blow the context | |
+| `wikipedia_lookup` | Reads a Wikipedia article | [contact](setup/contact.md) — **403s without it** |
+| `search_stackexchange` | Searches Stack Exchange for an answer, with the accepted one marked | [stackexchange](setup/stackexchange.md) *(optional)* |
+| `search_papers` | Searches academic papers through OpenAlex, with citation lines ready to copy | [contact](setup/contact.md) *(optional)* |
+
+## IT and reference
+
+| Tool | What it does | Setup |
+|---|---|---|
+| `lookup_rfc` | Reads or searches IETF RFCs | |
+| `lookup_cve` | Looks up a CVE or searches vulnerabilities; CIRCL first, NVD for CVSS detail | [nvd](setup/nvd.md) *(optional)* |
+| `read_man_page` | Reads a Linux manual page | |
+| `lookup_package` | Current version of a package across PyPI, npm, crates.io, Docker Hub, GitHub and Debian | [github-token](setup/github-token.md) *(optional)* |
+
+## Networking
+
+`dns_lookup`, `inspect_tls`, `http_headers` and `lookup_ip_or_asn` reach out and touch a
+host the user named, so they share a per-user hourly budget
+(`OWUITOOLS_PROBE_RATE_PER_HOUR`, default 30). The others are offline.
+
+| Tool | What it does |
+|---|---|
+| `subnet_calc` | Subnet arithmetic, IPv4 and IPv6, including splitting a prefix |
+| `dns_lookup` | DNS records over DoH |
+| `inspect_tls` | Reads a certificate: issuer, expiry, SANs, chain |
+| `http_headers` | Response headers, redirect chain, security headers |
+| `lookup_ip_or_asn` | RDAP and RIPEstat: who owns an address, an ASN or a domain |
+| `network_reference` | MAC vendor, port number and HTTP status, from datasets baked in at build time |
+
+## Electronics
+
+All four are deterministic arithmetic with no network access. If you never do electronics,
+these are the cheapest schemas to reclaim.
+
+| Tool | What it does |
+|---|---|
+| `ohms_law_power` | Solves Ohm's law and power from any two of V, I, R, P |
+| `component_calc` | Resistor colour codes, E-series, RC and LC, dividers, series/parallel |
+| `pcb_calc` | Trace width, microstrip impedance, via current |
+| `wiring_calc` | AWG properties, voltage drop, LED resistors, decibels, battery life |
+| `find_datasheet` | Finds a component datasheet — needs [searxng](setup/searxng.md) |
+
+## Code execution
+
+| Tool | What it does | Setup |
+|---|---|---|
+| `matlab_run` | Runs MATLAB/Octave code in a network-less sandbox and reports output, errors and MATLAB compatibility | [octave](setup/octave.md) |
+| `vm_agent` | Hands a task to a second model driving a real throwaway machine | [vm-agent](setup/vm-agent.md) |
+
+---
+
+## Why every tool is a POST with a body
+
+Open WebUI's OpenAPI converter flattens query parameters to `{type, description}` — enums
+become prose and defaults vanish — while a request body is `$ref`-resolved with its enums,
+defaults and nesting intact. So every tool takes a body, and no tool mixes body and query
+parameters.
+
+Two other constraints from the same converter, worth knowing if you add a tool:
+
+- **The tool name the model sees is the `operationId`**, and an operation without one is
+  silently dropped from the spec.
+- **The description the model reads is the docstring.** Keep it terse: it is paid on every
+  turn. The reasoning belongs in the system prompt, not in the tool.
+
+## Why failures come back as HTTP 200
+
+Open WebUI turns any status ≥ 400 into `{"error": "HTTP error 502: ..."}` and marks the call
+failed. For a genuine fault that is right. But "that page is behind a login" and "the search
+returned nothing" are **findings**, not faults — and they are exactly the findings that
+should stop the model inventing an answer.
+
+Handed back as prose in a successful call, they get acted on. Handed back as an error, they
+read as something to retry. `401` and `429` stay real status codes; those are about the
+caller, not the question.