Tools Reference¶
Look up each tool's parameters, output format, and setup requirements here. For a practical walkthrough, start with Working with Tools.
Registered means the server loaded the tool at startup. Enabled for a
chat means its schema is sent to that chat's model. Core tools are active in
every chat when registered; optional tools require their group to be enabled in
the composer. The authenticated GET /api/v1/tools endpoint returns the live
schemas and groups registered on your instance.
| Task | Tools |
|---|---|
| Search and read the web | web_search, fetch_web_page |
| Get help using or configuring Numi Chat | numi_docs |
| Work with files, data, and multi-tool scripts | view, code_interpreter, codemode, create_file |
| Generate images | generate_image |
| Follow task instructions (skills) | read_skill |
| Research a topic in depth with sub-agents | research_spawn and research_poll |
| Recall, save, or forget memory | recall_memory, remember_fact, forget_fact |
| Find something from an earlier chat | past_chats |
| Research, recipes, shopping, and groceries | Optional integrations |
| Implement a tool | Tool Schema, Adding Custom Tools |
Built-in Tools¶
numi_docs¶
Search the bundled English manual and read the relevant passage. No web search, API key, or documentation server is needed. The manual describes the installed version's behavior and defaults, not the instance's live settings.
action: "search"takes aqueryof up to 200 characters. Use English keywords or an exact setting name. It returns up to five matching pages with a heading, excerpt, andstart_line; no matches gives an empty list.action: "read"takes a manualpathand an optional one-basedstart_line(default1). It returns up to 40 lines of Markdown and anext_start_linewhen there is more. Only paths in the manual are accepted.
The lookup is a core tool, not a filesystem mount. It does not add documents
to user context or give the model access to server files. If you set a custom
TOOLS_ALLOWLIST, include numi_docs to enable it. For tiers with an explicit
feature list, grant Documentation.
request_tool_activation¶
Description: Show an approval card for an optional tool group that is currently disabled for the chat.
Parameters:
{
"type": "object",
"properties": {
"group": {
"type": "string",
"enum": [
"Scientific Research",
"Grocery",
"Recipes",
"Shopping",
"eBay",
"MyDealz",
"Price Search",
"Weather"
]
},
"reason": {
"type": "string",
"maxLength": 240
}
},
"required": ["group", "reason"],
"additionalProperties": false
}
The tool does not activate anything by itself. It waits for the user to choose Enable, No, or Ignore. The selected tool names are persisted on the chat.
Registered by default: Yes, unless denied. The agent receives this tool when at least one available optional group is disabled for the chat.
research_spawn and research_poll¶
Description: The lead agent's tools in deep research mode. research_spawn
starts sub-agents that each research one self-contained assignment on the web
and returns at once. research_poll waits until every agent has finished and
returns their status plus all reports not delivered yet, so the lead wakes once
per wave instead of once per report. The wait is bounded: each sub-agent stops
at DEEP_RESEARCH_AGENT_MAX_SECONDS, a failed one finishes at once, and a tool
call that hangs past that deadline is abandoned.
Parameters:
{
"research_spawn": {
"tasks": [{ "title": "string, 2-6 words", "objective": "self-contained assignment" }]
},
"research_poll": {}
}
Each report is delivered once. Reports that do not fit one result stay queued
for the next research_poll, which then returns at once. Size accounting
includes
JSON escaping and source metadata. If a single report cannot fit the configured
output budget, it is shortened with truncated: true; only sources still cited
in the delivered text are included. Reports cite their
sources with [src:N]; before the lead reads a poll result, those labels are
rewritten to the chat's [web:N] markers, so the final answer cites the
sub-agents' sources directly. Sub-agent progress streams to the browser as
research_agent events that draw the research board.
An agent that stops or fails before writing its report hands over the sources it read instead, still labelled for citation.
With DEEP_RESEARCH_CACHE_WARMING=true (off by default), the lead's prompt
cache is kept alive while research_poll waits, when that cache expires after
5 minutes: Anthropic models with ANTHROPIC_CACHE_TTL=5m (or
ANTHROPIC_COMPAT_CACHE_TTL=5m) and OpenRouter models with prompt caching
enabled in the catalog. About 4.5 minutes after the lead's last request, Numi
sends that identical request again and closes it at the first streamed token,
which reads and refreshes the cache. Without it, the lead's next request after a
long wave would write its whole prompt to the cache again, at a higher rate than
reading it. Each refresh is billed as a model request with unknown cost, so the
answer's total shows ≥. Caches with a 1-hour lifetime and providers with
automatic caching are not refreshed.
Both control tools execute serially, so a spawn and poll in the same model step run in order. Research work remains parallel. A closed or expired run refuses new workers, and polling stops in time to leave the lead its synthesis reserve.
Registered by default: Yes, unless denied or DEEP_RESEARCH_ENABLED=false.
Like request_tool_activation, they are not subject to TOOLS_ALLOWLIST. The
agent receives them only in a turn the user sent in deep research mode.
The lead's own web_search results carry a reminder that its survey only
informs the plan until the first agents start, so a model that finds the survey
sufficient still delegates. Messages sent in deep research mode stay marked in
later requests, so the model knows which earlier answers came from a research
run.
Workers are instructed to answer every assigned question or identify the gap, and to distinguish sourced findings from their own inferences. The lead preserves that distinction in the final report. For follow-up requests, it reuses earlier findings whose sources still support the current scope and focuses new research on additions, gaps, and evidence that needs rechecking. Missing evidence is researched again; an explicitly requested independent redo starts afresh.
web_search¶
Description: Batched web search through the configured provider chain, tried in priority order with fallback. Accepts keyword queries and a research objective, and returns excerpts with citations.
Parameters:
{
"type": "object",
"properties": {
"query": {
"type": "array",
"items": {"type": "string"},
"minItems": 1,
"maxItems": 5,
"description": "Keyword queries, usually 2-3 diverse queries (max 5)."
},
"objective": {"type": "string"},
"num_results": {"type": "integer", "default": 10, "minimum": 1, "maximum": 20},
"include_domains": {"type": "array", "items": {"type": "string"}, "maxItems": 20},
"start_published_date": {"type": "string"},
"freshness": {"type": "string", "enum": ["default", "live"], "default": "default"}
},
"required": ["query"],
"additionalProperties": false
}
Features:
- Batched queries (up to 5 at once); providers without batched queries run them concurrently and results are interleaved across queries
- Tries Keenable (pro;
keenable:realtimefor the fastest mode), Exa (auto, dynamic highlights;exa:litefor the cheaper lite search), Octen (highlights), Parallel (advanced), You.com (highlights) and DeepSeek (summaries) in the configured order and falls back when a provider fails or finds nothing;providerin the output names the one that answered - Experimental
numi-searchasks several providers at once and returns the best of their merged results, picked by a small model; see Web search and fetch providers - Provider charges appear separately from inference in the answer’s cost tooltip; see Web tool costs
- Duplicate URLs and tracking parameters are removed across queries
- Returns up to 10 results total by default, capped at 20 across all queries
- Excerpts default to up to 4,000 characters per result; Exa instead shares one excerpt budget across all its results
freshness="live"asks Parallel and Exa for freshly crawled content; Keenable, Exa lite, Octen, You.com and DeepSeek search ignore itinclude_domainslimits results to known relevant sites;start_published_datefilters after a date- Search returns excerpts, not full documents; use
fetch_web_pageto read full text - Unsupported legacy
cache_only,text/summary, and end-date options return explicit errors - Validated output with
query,results,provider, and optionalerrors - Each result entry is schema-validated and includes
query,url,title, optionalpublished_date, andsnippet - Result entries include
url,title, andsnippetfields used by web citation UX ([web:n]chips, hover details, and copy-time markdown links) - Multiple sources can share one bracket pair, for example
[web:32, web:36], with or without spaces after the commas. They use the same source chips, previews, and copy-time Markdown links as separate[web:32][web:36]markers, including in saved chats and shared conversations. - Hover over a citation, focus it with the keyboard, or tap it on a touch screen to open its source preview. Press Arrow Down on a focused single-source citation to enter its source card. Hover over or focus an individual source card to highlight the nearby text it likely refers to. This works for single sources and groups. On touch screens, tap a source card once to highlight its text and again to open the source. A paragraph-end citation covers the uncited passage in that paragraph; table cells and list items keep their own boundaries. Strong shared wording in the saved source preview can narrow the range to matching sentences. Translated or incomplete previews fall back to the passage, not just its last sentence; no extra model request or source fetch is made. Older browsers without text highlight support still show the source preview. Very long passages are limited to the nearest 6,000 characters.
- Highlights show a likely citation scope, not a fact check or accuracy score. A preview can be incomplete or use a different language; shared words do not establish that a source supports a claim. Open the full source to verify it. Code, formulas, images, and other media are not checked; file citations use available text previews only. Leaving the source card clears the highlight. Escape or tapping outside closes the preview.
- The agent adds each result's
citationmarker as the first field, ahead of the page text. A marker the model writes without a matching source shows as a muted?chip ("Source not found")
Configuration:
- At least one of
KEENABLE_API_KEY,OCTEN_API_KEY,PARALLEL_API_KEY,EXA_API_KEY,YOU_API_KEYorDEEPSEEK_API_KEY; see Web search and fetch providers
Registered by default: Yes
fetch_web_page¶
Description: Download and return text from known URLs. Ordinary pages use
local SSRF-safe extraction for mode="text" without a query when
DIRECT_WEB_FETCH_ENABLED=true, then fall back to the web providers; focused
highlights use the web providers. URLs a provider cannot read are retried on the
next provider. PDFs, arXiv preprints, and YouTube transcripts use native text
handlers. Scanned PDFs use local OCR. Supports offset pagination and full
reading.
Parameters:
{
"type": "object",
"properties": {
"urls": {
"type": "array",
"items": {"type": "string"},
"minItems": 1,
"maxItems": 10,
"description": "Real user/search URLs (web pages, direct PDF links, arXiv preprints, YouTube videos)."
},
"mode": {
"type": "string",
"enum": ["highlights", "text"],
"default": "text",
"description": "text: sequential content; omit query. highlights: focused web excerpts; offset must be 0 and read_full must be false."
},
"query": {"type": "string", "description": "Optional focus query for mode=highlights only. For mode=text, omit query or use an empty string."},
"offset": {
"type": "integer",
"default": 0,
"minimum": 0,
"description": "Character offset for mode=text (default 0). For highlights, omit or set to 0."
},
"max_characters": {
"type": "integer",
"default": 16000,
"minimum": 500,
"maximum": 90000,
"description": "Max characters per page to return in this chunk (default 16000, max 90000)."
},
"read_full": {
"type": "boolean",
"default": false,
"description": "Text only: true bypasses max_characters and reads from offset within retrieval and total tool output limits. If truncated, follow the returned continuation guidance. For highlights, omit or set to false."
},
"freshness": {"type": "string", "enum": ["default", "live"], "default": "default"}
},
"required": ["urls"],
"additionalProperties": false
}
Features:
- URL-pattern routing: YouTube, arXiv, and direct PDF links are handled natively in Python; ordinary pages use local SSRF-safe extraction when enabled, then fall back to the configured web fetch providers
- Batch URL content fetching (mixed YouTube, arXiv, PDF, and regular URLs in one call)
- Token-efficient offset pagination (
offset+max_characters) with truncation guidance - Full document extraction option (
read_full: true) - Text responses share the executor's output budget across all URLs, including
JSON overhead. Oversized results remain successful, with
truncated: trueand an exact continuation offset in the text;read_fullalso respects this budget. - Web providers return at most the first 90,000 characters; neither offsets nor
read_fullcan retrieve beyond that prefix. Native handlers may read further, subject to their download and extraction limits. - Native PDF/arXiv/YouTube handlers require
mode="text"; focused excerpts are for ordinary webpages - For
mode="text", omitqueryor use"";offsetandread_fullare supported - For
mode="highlights", optionally provide a focusquery; omitoffset/read_fullor use0/false - Direct handlers fetch from the source;
liveasks web providers for freshly crawled pages (Octen: at most 5 minutes old) - Unimplemented legacy crawling, link extraction, summary and cache-only options return explicit errors
- Failed, missing, or empty provider results remain errors and are excluded from citations
- Native handlers and successful local HTML extraction add no web API cost; provider fallbacks use Web tool costs
- Always registered (YouTube, arXiv, and PDF handlers work without a web provider key)
- Enforced output contract (
PageContentResultContractwithurl,title,author,text,offset,total_characters,truncated,fetch_status, anderror)
Configuration:
DIRECT_WEB_FETCH_ENABLED=trueenables local direct HTML extraction before the web providers; it defaults tofalseWEB_FETCH_PROVIDERSsets the provider order; it defaults toWEB_SEARCH_PROVIDERS- A web provider key is required only for ordinary pages when direct fetching is disabled or falls back
Registered by default: Yes
Web tool costs¶
The cost below an answer combines reported inference cost with estimated web API charges. Hover or focus the amount to see inference and each provider's search/fetch subtotal. A free OpenRouter model can therefore show $0 inference and a nonzero total after using web tools. For model providers without cost reporting, the tooltip says inference cost is unavailable.
Web estimates use public USD rates checked 2026-10-03 (DeepSeek: 2026-10-20, Keenable: 2026-11-12):
| Provider | Search used by Numi | Fetch/extract |
|---|---|---|
| Octen | $0.001 per query call, including highlights | $0.001 per successful standard URL or $0.0025 per successful advanced URL; automatic mode uses the returned tier |
| Parallel | $0.005 per advanced request, including 10 results; $0.001 per additional result | $0.001 per URL, using reported extract units when available |
| Exa | $0.007 per auto request or $0.004 per lite request (exa:lite), including 10 results; $0.001 per additional result |
$0.001 per returned page and requested content type; Numi requests text or highlights |
| You.com | $0.005 per call, including highlights | $0.001 per returned page |
| Keenable | $0.004 per credit reported by the response (one per pro or realtime search); $0 while the free monthly allowance covers the call | $0.004 per reported credit (one per page, cached or live); $0 on the free allowance |
| DeepSeek | $0.00075 per successful search request; result count does not affect the price | $0.00075 per successful page; failed or empty requests are free |
Exa's returned costDollars.total takes precedence over the local formula and
is still an estimate. Keenable reports the credits of each call and whether it
drew on purchased credits; organizations with their own rates pay a different
amount per credit. Parallel batches queries into one search request; the
other providers send one request per query. Charges are recorded for every
attempt, including fallback providers and successful searches with no results
(except DeepSeek, which bills only non-empty responses).
Local URL deduplication, result limits, citation formatting and text truncation
do not reduce charges already incurred at the API. A numi-search search adds
the charges of every provider it asked, listed per provider, and a Numi
Search entry with the ranking cost that OpenRouter reported.
The tooltip also shows the share of input tokens read from the provider's prompt cache and, when a cache that should have been used was missed, how many tokens were sent again at full price. A request counts as a miss when it was sent within 5 minutes of the previous one on the same model and read fewer of that request's prompt tokens from cache (more than 1,024 fewer). Misses are counted only once the chat has reported caching at all, and only for providers that report usage (OpenRouter and the ChatGPT subscription). They show when a saved chat is loaded.
≈ marks estimates. Credits, free allowances, contracts, taxes and later price
changes can make your provider's bill differ. ≥ marks an incomplete total:
timeouts, server failures, unrecognized pricing metadata or extract failures
without sufficient billing information remain unknown. Rejected authentication,
validation and rate-limit requests count as zero. Unknown charges are never
silently treated as free. If all costs are unknown, no amount is shown.
YouTube transcripts, native PDF/arXiv handlers and successful direct HTML fetches add no web API charges. Only an actual request to a paid web provider is metered. Research workers use the same accounting; polling or reopening a chat does not charge or count their requests again. A worker request still running at cancellation remains unknown in the saved total, even if it later finishes. Process crashes can lose usage that has not reached persistence.
This applies to new chat requests; older saved messages are not repriced. Admin provider health tests are outside a conversation and are not included in an answer's cost. Public share snapshots omit usage costs.
weather_fetch¶
Description: Get current weather, up to 15 daily forecasts starting tomorrow, and up to 48 hours of weather with precipitation probability.
Parameters:
{
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name (e.g., 'New York', 'London')"},
"forecast_days": {
"type": "integer",
"description": "Daily forecasts starting tomorrow (0=off, maximum 15).",
"default": 0
},
"forecast_hours": {
"type": "integer",
"description": "Hourly forecast from the current local hour.",
"default": 0,
"minimum": 0,
"maximum": 48
},
"latitude": {"type": "number", "description": "Latitude (optional, use with longitude)"},
"longitude": {"type": "number", "description": "Longitude (optional, use with latitude)"}
},
"required": [],
"additionalProperties": false
}
Features:
- Current weather conditions
- Temperature, humidity, wind speed
- Daily forecasts for the next 1–15 days
- Hourly temperature, conditions, wind, precipitation amount and probability
- Local timestamps, timezone and UTC offset; precipitation covers the hour preceding each timestamp
- No API key required (uses Open-Meteo)
Provide a city or both coordinates. When both are supplied, the city lookup
takes precedence. forecast_days is clamped to 0–15; forecast_hours must be
an integer from 0 through 48.
Registered by default: Yes, in the optional Weather group, which starts
disabled in each chat like the other optional groups. Switch it on in the chat's
tools when you want live forecasts; otherwise the model answers weather
questions
with web_search.
codemode¶
Description: Run a Python script that calls other tools as async functions. Only what the script prints returns to the model, so a task such as "compare this product across five shops" or "read these ten pages and list the prices" takes one tool step instead of many, and the raw pages and listings never enter the conversation. That keeps later requests small: everything in the conversation is sent again on every following step and turn.
All other tools stay available as normal tool calls; the model picks
codemode when a task needs many calls or large results it only partly needs.
Parameters:
Inside a script, each enabled tool from this list is an async function that takes the tool's arguments as keywords:
web_search, fetch_web_page, weather_fetch, academic_search,
wiki_lookup, ebay_search, ebay_listing, geizhals_search,
geizhals_product, kleinanzeigen_search, kleinanzeigen_listing,
mydealz_search, mydealz_deal, chefkoch_search, chefkoch_recipe,
grocery_search_stores, grocery_get_offers
import asyncio
shops = ["idealo", "geizhals", "amazon"]
pages = await asyncio.gather(
*[
web_search(
objective=f"price of the Sony WH-1000XM6 at {shop}",
query=[f"WH-1000XM6 {shop}"],
)
for shop in shops
]
)
for page in pages:
for hit in page["data"]["results"][:2]:
print(hit["title"], hit["url"])
- Results are parsed JSON (dicts and lists) or text. A failed call raises an exception the script can catch.
- Tools that are not enabled in the chat, or not in the list, cannot be called. Memory, profile, past chat and file tools are never callable from a script, because script output is not filtered for share links the way their own results are.
- Limits per script: 40 tool calls, 4 at a time, 180 seconds, 256 MB of memory, 20,000 characters of code. Output is cut to 12,000 characters, keeping the start and the end; a cut result tells the model to print only the fields it needs next time.
- Scripts run in Monty with the standard library only: no files, network, imports of other packages or state between calls.
- Sources whose URL the script prints are returned with their title and get
[web:N]citation markers, so answers can cite them as usual. Page text is not returned. - Web charges of nested calls are added to the answer's cost.
Registered by default: Yes, when pydantic-monty is installed. It is
offered only when the chat has at least one tool it can call. An explicit
TOOLS_ALLOWLIST must include codemode.
code_interpreter¶
Generated files appear as compact cards after the complete assistant answer and before its action/cost row, with their name, format and a thumbnail for images, SVG and the first page of PDFs. Clicking a card, or a link to the file in the answer, opens a preview beside the chat (full screen on smaller devices); modified clicks keep normal browser navigation. Previews cover:
- PDF: continuous scrolling with the current page shown in the header; nearby pages render as needed.
- Images (PNG, JPEG, GIF, WebP, AVIF, BMP, ICO) and SVG; click a raster image to view it at full size.
- Markdown (rendered), HTML (rendered in a sandbox without scripts, forms or network access to this app), CSV/TSV (as a table, up to 1,000 rows shown); each can switch to its source code.
- Any other UTF-8 text such as JSON, code or logs, with syntax highlighting.
- Audio and video with the browser's player.
Office files up to 30 MB preview too:
- Word (DOCX): rendered as pages with docx-preview. Only web and mail links stay clickable, and embedded HTML chunks are not rendered.
- Excel (XLSX, XLSM): every visible sheet as a tab, with number formats, merged cells, column widths, bold text and cell fills shown in the app theme. Formulas saved without a computed value show their source. Up to 1,000 rows and 60 columns are shown; charts and images stay in the downloaded file.
- PowerPoint (PPTX): a simplified rendering of each slide with its theme, layout, text, pictures, tables, and native bar, column, line, area, pie and doughnut charts. Fonts and complex shapes can differ from PowerPoint.
Text previews load at most 2 MB; larger or non-UTF-8 files show a download fallback. The bundled PDF.js, JSZip and docx-preview libraries load only when a preview needs them and are reused for later previews. Legacy Office formats (DOC, XLS, PPT), archives and other binary formats download for opening in a suitable app. The same cards work in saved chats and shared chat snapshots. If a preview cannot load, its download control remains available.
Description: Run stateless Python with Monty for supported standard-library code and a fresh Deno/Pyodide sandbox for third-party libraries. Supports calculations, analysis, charts, Excel, Word, PDF, and downloadable files.
Parameters:
{
"type": "object",
"properties": {
"code": {
"type": "string",
"maxLength": 100000,
"description": "Self-contained Python; re-import libs each call. Standard-library-only code runs fast (no network, subprocess or threads). Third-party packages (...) load automatically on import."
}
},
"required": ["code"],
"additionalProperties": false
}
Features:
- Fresh execution state for every call
- Monty first for scripts that import only modules the installed Monty
provides (probed on first use); Deno/Pyodide for third-party packages, plot
capture, and Monty gaps. Monty's parser rejects syntax it lacks (such as class
inheritance or generators) before anything runs, and runs that fail on a
missing API (
AttributeError,ImportError,NameError,NotImplementedError,TypeError) rerun in Deno/Pyodide; other script errors return directly - AST-validated imports plus dependency/import allowlists; a rejected script gets an error naming the blocked call or import, its line and source, and what to do instead, so the model can fix and resubmit it
- Current-chat uploads and reusable generated files mounted in the virtual filesystem
- Execution timeout protection (90 seconds)
- Bounded output and file sizes
- Matplotlib plot capture through
plt.show()orplt.savefig() - Downloadable artifacts through
save_file(filename, str_or_bytes) - XLSX creation/reading/editing with openpyxl/xlsxwriter, DOCX with python-docx, PPTX with python-pptx, PDF with reportlab/pypdf/pdfminer.six, image editing with Pillow
- Imports automatically resolve package names, including
docx→python-docx,pptx→python-pptx,pdfminer→pdfminer.six,sklearn→scikit-learn,PIL→pillow, andzoneinfo→tzdatafor IANA time zones - Skill folders are mounted read-only at
/mnt/skills/<name>when the code names that path; theirscripts/helpers import after adding the folder tosys.path, and the packages those helpers import load automatically. See Manage Skills - Pyodide packages are cached under
state/code-sandboxafter the first download, so later runs work without CDN access - Each Pyodide run is capped at
TOOLS_CODE_INTERPRETER_MAX_MEMORY_MB, and at mostTOOLS_CODE_INTERPRETER_MAX_CONCURRENTrun at once - Package installation finishes before Deno network permission is revoked; user code and files are sent only after successful revocation when networking is disabled
Configuration:
TOOLS_CODE_INTERPRETER_DEPS_ALLOWLIST: Allowed packages; the schema above shows defaults. Existing overrides must include the office packages to enable them.TOOLS_CODE_INTERPRETER_IMPORT_ALLOWLIST: Allowed Python modulesTOOLS_CODE_INTERPRETER_IMPORT_DENYLIST: Denied Python modules (includes networking)TOOLS_CODE_INTERPRETER_TIMEOUT: Execution timeout in seconds (default: 90)TOOLS_CODE_INTERPRETER_ALLOW_NETWORKING: Enable outbound networking in sandbox (default: false)TOOLS_CODE_INTERPRETER_MAX_MEMORY_MB: Memory cap per Pyodide run (default: 1024)TOOLS_CODE_INTERPRETER_MAX_CONCURRENT: Pyodide runs allowed at once (default: 2)TOOLS_CODE_INTERPRETER_UNSANDBOXED: Disable sandboxing (dangerous, default: false)
The parameter schema above lists allowlisted third-party packages in the code
description, and imports resolve and load those packages automatically.
Unsandboxed mode also exposes only code.
Dependencies:
pydantic-monty1.5 or newer (required) for scripts without third-party dependenciesmcp-run-pythonand Deno for third-party libraries and fallback execution- Optional:
DENO_PATHif Deno not in PATH (legacyD_AI_DENO_PATHstill works)
Generated Files: Plots and files registered with save_file() return
chat-owned /generated-files/<chat-uuid>/... URLs. The authenticated Web UI
renders supported images inline and downloads other files.
Do not expose virtual paths such as /mnt/data/... as links.
For office files, serialize to io.BytesIO and call
save_file("report.xlsx", buffer.getvalue()). Returned files can be reopened in
later calls through their code_interpreter_file_map paths. Excel libraries
preserve/write formulas but do not calculate them.
Run the real package/file/network-boundary check with:
Security Note: Sandboxed execution has no host write, environment, or subprocess permission, and networking defaults off. The timeout is not a memory quota; apply OS/container resource limits for hostile multi-tenant deployments. Only enable unsandboxed mode on trusted personal instances.
Registered by default: Yes, including when a runtime dependency is missing. Eligible scripts can run with Monty alone. Scripts requiring the Deno/Pyodide path return a setup error if that runtime is unavailable.
forget_fact¶
Description: Remove a stored user fact by content match. Use only when the user explicitly asks to forget something.
Parameters:
{
"type": "object",
"properties": {
"match": {
"type": "string",
"description": "Substring used to locate the fact to remove; be specific enough to match exactly one fact"
}
},
"required": ["match"],
"additionalProperties": false
}
Features:
- Searches stored facts by substring match
- Returns candidates if multiple facts match, asking for clarification; a match equal to one fact's full text (ignoring case) removes that fact, even when it is part of a longer one
- Confirms deletion of the specific fact
Usage Note: Only call when the user explicitly requests to forget a specific fact (e.g., 'forget my old address', 'don't remember I use Windows'). If the match is ambiguous, the tool returns candidates so you can ask the user which one to remove.
Registered by default: Yes
past_chats¶
Description: Find the user's earlier chats by keywords or by recency, then read one. Use when the user refers to something from another chat.
Parameters:
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"search",
"recent",
"read"
],
"description": "search: chats containing the query words; recent: latest chats, for questions like 'what did we discuss last time'; read: open one hit."
},
"query": {
"type": "string",
"description": "For search: 1-6 distinctive content words that were said in that chat, such as names or topics."
},
"chat_ref": {
"type": "string",
"description": "For read: chat_ref from a search or recent result."
},
"message_id": {
"type": "integer",
"description": "For read: message_id from a result, or earlier/later from a read result. Omit to open the latest turns."
}
},
"required": [
"action"
],
"additionalProperties": false
}
Features:
searchranks the user's other chats by how many query words they contain and returns up to 5 hits with a title, date and short snippetrecentlists the 8 most recently active chats, each pointing at its latest user messagereadreturns up to 3 turns from the hit onward, or the latest 3 without amessage_id, at most about 9,000 characters, withearlierandlatermessage ids for paging- Each turn holds only the user's typed words and the assistant's final answer; long texts keep their beginning and end
- While the tool is available, the memory note also lists the titles of the
user's 10 newest other chats with their
chat_ref, so the model can notice a related chat andreadit without being asked
Privacy: Reasoning, tool calls and results, attachments, stored context and memory are never read. Temporary chats, the current chat, deleted messages, and messages before the account's memory boundary are out of reach, and every query is limited to the chat owner's own chats. The tool refuses when memory is turned off for the account, is removed from temporary chats when memory is off, is never given to deep research sub-agents, and is left out of share snapshots.
Registered by default: Yes. Tiers grant it with the Memory feature.
remember_fact¶
Description: Persist a single durable user fact for future sessions (preference, hardware, recurring context, long-term goal). Write-only agent surface; use for storing important information the user wants remembered across sessions.
Parameters:
{
"type": "object",
"properties": {
"fact": {
"type": "string",
"description": "The fact to remember in third person (e.g. 'User prefers TypeScript', 'User's GPU is RX 9070 XT')"
}
},
"required": ["fact"],
"additionalProperties": false
}
Features:
- Store durable user facts that persist across all sessions
- Automatically included in user context for future conversations
- Facts are written only when explicitly requested by the user
- Searchable by content when checking for duplicates
Usage Note: Already stored facts appear in <user_context> above; do not
call this tool to recall or verify stored facts. Only call when the user
explicitly asks you to remember something new.
Registered by default: Yes
recall_memory¶
Description: Look up the stored details of up to 5 subjects from the
user's memory in one call. Call recall_memory with exact subject names or
natural-language searches when missing details would help the current question. Optional semantic
search can match questions in another language to English memories; unavailable
or incomplete indexes use the existing name/summary word search.
Parameters:
{
"type": "object",
"properties": {
"subjects": {
"type": "array",
"items": { "type": "string" },
"minItems": 1,
"maxItems": 5,
"description": "Entry names from <user_context> or search terms."
}
},
"required": ["subjects"],
"additionalProperties": false
}
Features:
- Exact subject-name lookup (case-insensitive) returning all current active details under that entry
- Optional semantic search over current names, summaries and details, with keyword fallback returning up to 3 matching entries per search term
- Several subjects in one call return each entry once; subjects with nothing
current are listed under
not_found - Respects the account's
memory_enabledswitch and user ownership - Excluded from public share snapshots and deep research sub-agents
Registered by default: Yes. Tiers grant it with the Memory feature.
view¶
Description: Read and inspect a file uploaded to the current chat, or an
image generated in it, without using the code interpreter. The server resolves
the chat directory internally; the model supplies only the displayed filename,
the generated image path a tool returned, or the name it passed to save_file.
Parameters:
{
"type": "object",
"properties": {
"filename": {"type": "string", "description": "Uploaded filename shown in the chat context (e.g., 'data.csv'), a generated image path returned by a tool, or the name given to save_file"},
"max_chars": {"type": "integer", "description": "Maximum characters to return (default 10000)", "default": 10000},
"head_lines": {"type": "integer", "description": "First N lines."},
"tail_lines": {"type": "integer", "description": "Last N lines."},
"csv_preview_rows": {"type": "integer", "description": "Sample rows for CSV/TSV.", "default": 10},
"raw_text": {
"type": "boolean",
"description": "Read CSV/TSV as raw text.",
"default": false
}
},
"required": ["filename"],
"additionalProperties": false
}
Features:
- Current-chat ownership enforced by server-injected context
- Read text-based files (txt, md, csv, json, code files, etc.)
- CSV/TSV structured preview with inferred types
- Head/tail line selection
- Size and line count metadata
- XLSX, DOCX and PDF return metadata, a file citation, and
code_interpreter_path; use the interpreter to read their contents - PNG, JPEG, WebP and GIF images, uploaded or generated (for example by
image_generatororcode_interpreter), are attached to the result as image input when the chat's model supports it, so the model can check its own output. Other models get an error saying they cannot view images. - A generated image can also be named by the filename passed to
save_file(for exampledraft.png); the newest copy saved under that name is used. For a generated document, the error names itscode_interpreterpath.
Ordinary text reads clamp max_chars to 100–30,000. Head/tail line selection
and CSV previews use their own requested line/row counts rather than that
character limit. Tail selection takes precedence over head selection; either
disables the structured CSV preview.
Supported Extensions: .txt, .md, .csv, .tsv, .json, .jsonl, .xml, .html, .htm, .yaml, .yml, .toml, .ini, .cfg, .conf, .log, .py, .js, .ts, .sh, .bash, .sql, .r, .rs, .go, .java, .c, .cpp, .h, .hpp, .css, .scss, plus images: .png, .jpg, .jpeg, .webp, .gif
Security: Only reads files from the chat's upload directory, and images from its generated-files directory
Registered by default: Yes
create_file¶
Description: Create a downloadable file from directly authored text,
including
HTML pages, CSS, JavaScript, SVG, source code, configuration files, or CSV data.
For files produced by Python, or binary formats such as XLSX, PDF, and PNG,
use code_interpreter.
Parameters:
{
"type": "object",
"properties": {
"filename": {"type": "string", "description": "Plain filename (no paths), e.g. 'page.html', 'data.csv', 'diagram.svg'."},
"content": {"type": "string", "description": "UTF-8 text content (<=500k chars). Use code_interpreter for binary formats."}
},
"required": ["filename", "content"],
"additionalProperties": false
}
Features:
- Create downloadable files from text or structured data
- UTF-8 text with any filename extension, or no extension
- CSV generation with headers and rows
- Returns download URL
File Types: There is no extension allowlist. The tool writes content as
UTF-8
without interpreting or executing it. Names such as page.html, diagram.svg,
app.tsx, event.ics, and Dockerfile are supported. An extension does not
convert the content: naming text report.pdf does not produce a valid PDF, and
base64 text is written literally rather than decoded.
For a standalone interactive page, include its CSS and JavaScript in one HTML
file and pass it as content; no Python execution is needed. HTML and SVG files
are downloaded as attachments, including through share links. The chat preview
shows HTML in a sandbox without running its scripts; download the file and open
it in your browser to use it interactively. Numi does not host it as a website.
Supply a nonempty plain filename without path separators, colons, or control
characters, and either content or, for .csv, csv_headers and optional
csv_rows. content is limited to 500,000
characters; that limit does not apply to the structured CSV-writing branch.
Storage: Files are stored as chat-owned generated artifacts. The result
includes download_url under /generated-files/<chat-uuid>/... and a
code_interpreter_path for reopening the file in later interpreter calls.
The chat displays a file card with the filename, format, size, and a download
button, using the same presentation as Code Interpreter outputs.
Registered by default: Yes
read_skill¶
Description: Read a skill's instructions (SKILL.md) or one of its
reference files before a task the skill covers. The chat's first message lists
the available skills; see Manage Skills.
Parameters:
{
"type": "object",
"properties": {
"name": {
"type": "string",
"enum": ["data-analysis", "docx", "..."],
"description": "Skill name from the available skills list."
},
"file": {
"type": "string",
"default": "SKILL.md",
"description": "File inside the skill folder."
}
},
"required": ["name"],
"additionalProperties": false
}
Output: content of the requested file, the skill's files list, and its
mount path (/mnt/skills/<name>) for code_interpreter. Paths cannot leave
the skill folder; only text files up to 200,000 bytes are returned. Skills an
admin switched off answer as unknown.
Available by default: Yes, while SKILLS_ENABLED is true and at least one
enabled skill has its required tools and Python packages available. Admin
switches refresh names and schemas without a restart. Tier feature: Skills,
also required for Python helper mounts. New public shares omit read_skill
calls and output.
generate_image¶
Description: Generate images from a text prompt via OpenRouter-backed image
generation models (configured default: google/gemini-3.1-flash-lite-image).
Images are persisted as chat-owned artifacts and rendered inline in the
authenticated chat.
Parameters:
{
"type": "object",
"properties": {
"prompt": {
"type": "string",
"description": "Detailed image prompt (subject, scene, composition, lighting, style, constraints; quote exact text to render)"
},
"aspect_ratio": {
"type": "string",
"enum": [
"16:9",
"1:1",
"21:9",
"2:3",
"3:2",
"3:4",
"4:3",
"9:16"
],
"description": "Aspect ratio. Default 1:1. 16:9 for banners, 9:16 for stories."
},
"quality": {
"type": "string",
"enum": ["low", "medium", "high", "xhigh"],
"description": "Render quality. Default high. Higher costs more."
},
"background": {
"type": "string",
"enum": ["transparent", "opaque"],
"description": "Only set when asked, e.g. transparent for logos or stickers."
},
"reference_image_urls": {
"type": "array",
"items": {"type": "string"},
"maxItems": 8,
"description": "Images to edit or compose: an uploaded filename from this chat, a file URL from this chat, or a public http(s) link"
}
},
"required": ["prompt"],
"additionalProperties": false
}
Features:
- Text-to-image plus reference-based editing/composition, with up to 8 images per call:
- images uploaded to the chat, by filename or download link
- images generated in the chat, by the returned URL
- public
http(s)image links, which the provider fetches itself - A reference that cannot be found stops the call with an error, before anything is billed. Files from other chats never resolve.
- Referenced chat files are sent to OpenRouter and the image provider. Reference images also leave public share links.
- Defaults to
1:1athighquality - Optional transparent or opaque background
- Returns chat-owned image URLs (
/generated-files/<chat-uuid>/<uuid>.<ext>) - The enums list values accepted by the tool; a model other than the default may ignore or reject some of them
Configuration (env vars, all optional):
IMAGE_GEN_MODEL(defaultopenai/gpt-image-2.6-sunburst)IMAGE_GEN_ASPECT_RATIO(default1:1)IMAGE_GEN_QUALITY(defaulthigh)IMAGE_GEN_MAX_PROMPT_CHARS(default4000)IMAGE_GEN_TIMEOUT_CONNECT(default10.0)IMAGE_GEN_TIMEOUT_READ(default240.0)- Requires
OPENROUTER_API_KEY(shared with other OpenRouter-backed tools)
Prompts longer than IMAGE_GEN_MAX_PROMPT_CHARS are truncated. The tool
persists at most four returned images per call.
Cost guardrails: The tool's system hint instructs the agent to only call it
when the user explicitly asks for a visual, and to keep the default quality
unless the user asks for a draft or maximum detail. The max quality level is
not offered because it costs about four times as much as high.
Registered by default: Yes
Optional integrations¶
Most of these tools are in the packaged allowlist, but they are disabled for each chat until its group is enabled. Provider credentials, availability checks, and operator allowlist overrides can further restrict them. Geizhals requires explicit operator setup.
academic_search¶
Description: Search scholarly literature through OpenAlex, Semantic Scholar, arXiv, Crossref, and PubMed APIs. Public endpoints can rate-limit requests.
Parameters:
{
"type": "object",
"properties": {
"query": {"type": "string"},
"source": {
"type": "string",
"enum": ["arxiv", "auto", "crossref", "openalex", "pubmed", "semantic_scholar"],
"default": "auto"
},
"limit": {"type": "integer", "default": 5, "minimum": 1, "maximum": 10},
"year": {"type": "string", "description": "2025, inclusive 2022-2026, or >2020 (2021 onward)."},
"sort": {"type": "string", "enum": ["citations", "date", "newest", "relevance"], "default": "relevance"}
},
"required": ["query"],
"additionalProperties": false
}
With source="auto", the tool chooses an order based on the query and stops
at the first provider with results. Year filters apply across providers; arXiv
uses submission dates. Citation sorting is unavailable for arXiv/PubMed;
explicit requests return an error, while automatic selection skips them.
Semantic Scholar date/citation sorting uses bulk search, which matches all
query terms, and returns at most the requested limit.
SEMANTIC_SCHOLAR_API_KEY is optional. Set it in the server process environment
(or Compose's env_file); this tool reads it directly and a local .env entry
alone does not load it.
Registered by default: Yes. Enable the Scientific Research group for the chat.
wiki_lookup¶
Description: Look up concise Wikipedia summaries or structured Wikidata entity information. No API key is required.
Parameters:
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Entity name, concept, scientific topic, or Wikidata Q-ID (e.g. 'CRISPR', 'Q937')."
},
"source": {
"type": "string",
"enum": ["wikipedia", "wikidata", "auto"],
"description": "Wikipedia summaries or Wikidata entities. auto selects Wikidata for a Q-ID, otherwise Wikipedia.",
"default": "wikipedia"
},
"language": {
"type": "string",
"description": "2-letter Wikipedia language code (default 'en', 'de', 'fr', 'es', etc.).",
"default": "en"
},
"limit": {
"type": "integer",
"description": "Number of entities or pages to return (1-5, default 3).",
"default": 3,
"minimum": 1,
"maximum": 5
}
},
"required": ["query"],
"additionalProperties": false
}
language accepts letters and hyphens only (for example en or de);
anything else returns an error without a request.
Registered by default: Yes. Enable the Scientific Research group for the chat.
grocery_search_stores¶
Description: Search for nearby supermarket stores across chains. Returns
store IDs, names, and addresses. Supports REWE (PLZ only), Lidl, Kaufland,
PENNY, ALDI Nord, and EDEKA. Use the store IDs with grocery_profile to save
preferred stores, then grocery_get_offers to fetch their weekly deals.
The schema below shows all six providers. Its chain enum contains only
providers whose local availability check passes, plus all. Missing REWE
certificates or Kaufland/EDEKA credentials remove those choices.
Parameters:
{
"type": "object",
"properties": {
"chain": {
"type": "string",
"enum": ["rewe", "lidl", "kaufland", "penny", "aldi_nord", "edeka", "all"],
"description": "Which supermarket chain to search. Use 'all' to search all available chains."
},
"query": {
"type": "string",
"description": "Search query: city name, postal code (PLZ), or street. REWE only supports postal codes."
},
"country": {"type": "string", "description": "Country code, default 'DE'."},
"latitude": {"type": "number", "description": "Optional latitude for distance-based ranking."},
"longitude": {"type": "number", "description": "Optional longitude for distance-based ranking."},
"limit": {"type": "integer", "description": "Max results per chain. Default 10."}
},
"required": ["chain", "query"],
"additionalProperties": false
}
Features:
- Distance-based store ranking with coordinate inputs
- Multi-chain unified results
- Auto-validation against configured provider availability
Registered by default: Yes. Enable the Grocery group for the chat; available chains depend on their provider configuration.
REWE setup: REWE uses the grocery tools above, not the old standalone
rewe_search_markets or rewe_get_offers names. Extract its client
certificate on the host:
This downloads the REWE app bundle and writes private_rewe.pem and
private_rewe.key to that directory. They are gitignored and excluded from
the image; Compose mounts them read-only. Treat both as credentials.
If REWE starts rejecting the certificate, repeat the extraction with the
current app bundle.
Retain grocery_search_stores, grocery_profile, and
grocery_get_offers in any custom allowlist, restart Numi, and enable the
Grocery group. Ask for stores using a German postal code, save the chosen
store through grocery_profile, then request its offers. REWE is unavailable
without the certificate files; other configured grocery chains still work.
See the REWE utility documentation for standalone market lookup and offer exports.
Other chains: Kaufland requires KAUFLAND_APP_BASIC_USER and
KAUFLAND_APP_BASIC_PASSWORD. Lidl, PENNY, and ALDI Nord have no
user-credential
requirement in their provider implementations. Lidl settings use the LIDL_
prefix; see Configuration.
EDEKA setup: Configure EDEKA_CLIENT_ID and EDEKA_CLIENT_SECRET. The
first
store search creates and privately saves an anonymous app session; no personal
login or EDEKA_VP_USER_HASH / EDEKA_VP_PASS_HASH settings are needed.
Search by
German city or postal code, then save the returned store_id with
grocery_profile. The ID is the market's 13-digit GLN; website IDs and numeric
Valuephone shop IDs cannot be substituted. Results can include EDEKA-group
banners such as E center or Marktkauf. Stores without an offer GLN are omitted.
The upstream search returns at most 100 candidates; local filtering removes
substring-only place matches, and coordinate inputs rank the matching results.
EDEKA returns the currently published market and national offers. App prices
are separate loyalty_price values; no coupon activation is performed.
Duplicate
promotions are removed, individual validity dates are preserved, and a
historical
lowest price is not presented as the regular price. If the API omits a positive
selling price, an explicitly labelled Normalpreis in its description is used
when available. PAYBACK points are included in the description; an app-only
price stays conditional and does not become the regular price.
week="next" returns an explicit unsupported error for EDEKA.
See EDEKA configuration
for session persistence and recovery.
grocery_profile¶
Description: Manage the user's grocery profile: view, add, remove,
enable/disable preferred supermarket stores, and set a home location. Saved
stores are used automatically by grocery_get_offers.
Parameters:
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": ["get", "add_store", "remove_store", "enable_store", "disable_store", "set_location"],
"description": "What to do."
},
"chain": {
"type": "string",
"description": "Chain name: 'rewe', 'lidl', 'kaufland', 'penny', 'aldi_nord', or 'edeka'. Required for store actions."
},
"store_id": {"type": "string", "description": "Store ID from grocery_search_stores. Required for store actions."},
"label": {"type": "string", "description": "Human-readable store name. Required for add_store."},
"address": {"type": "string", "description": "Store address. Optional for add_store."},
"latitude": {"type": "number", "description": "Latitude for set_location."},
"longitude": {"type": "number", "description": "Longitude for set_location."},
"location_label": {"type": "string", "description": "Location description for set_location (e.g. 'Lübeck Innenstadt')."}
},
"required": ["action"],
"additionalProperties": false
}
Features:
- Persistent, user-specific profile storage in SQL database
- Convenient toggling (enable/disable) of saved stores without full removal
- Stores home coordinates to support proximity store searches
Registered by default: Yes. Enable the Grocery group for the chat; available chains depend on their provider configuration.
grocery_get_offers¶
Description: Fetch current (or next week's) weekly offers from saved supermarket stores. Returns all deals in a unified format across REWE, Lidl, Kaufland, PENNY, ALDI Nord, and EDEKA.
Parameters:
{
"type": "object",
"properties": {
"chains": {
"type": "array",
"items": {"type": "string", "enum": ["rewe", "lidl", "kaufland", "penny", "aldi_nord", "edeka"]},
"description": "Limit to specific chains. Default: all enabled stores in profile."
},
"week": {
"type": "string",
"enum": ["current", "next"],
"description": "Which week's offers. Default: 'current'."
},
"query": {"type": "string", "description": "Optional keyword filter across offer titles, brands, and descriptions."},
"limit_per_store": {"type": "integer", "description": "Offers per store per page, 1–100; default 40."},
"offset": {"type": "integer", "description": "Offers to skip per store; use the previous next_offset."}
},
"required": [],
"additionalProperties": false
}
Features:
- Aggregates offers from saved stores across chains
- Returns
total_availableandnext_offsetfor paging without repeating offers - Sorts and normalizes raw store offers into a cohesive schema
- Distinguishes between standard price, regular discount, and loyalty app/card
price (
loyalty_price)
Across all grocery providers, missing, zero, and negative numeric prices are
unknown rather than free. The tool returns "-" for a missing selling price,
omits unusable old/app prices, and sorts unknown selling prices after known
prices. Offers remain visible so valid app prices and other promotion details
are still available. A numeric zero alone never confirms a free product.
The web UI displays unknown prices as a dash, including zero prices in saved chats and share snapshots. Existing stored tool output is preserved; fetch offers again to get recovered prices and updated details in the model's tool results.
Registered by default: Yes. Enable the Grocery group for the chat; available chains depend on their provider configuration.
kleinanzeigen_search¶
Description: Search listings on Kleinanzeigen (German classifieds). Uses the Kleinanzeigen app API.
Parameters:
{
"type": "object",
"properties": {
"query": {"type": "string", "description": "Search keyword(s)."},
"location": {"type": "string", "description": "Optional city name or location ID; numeric strings are treated as IDs."},
"radius_km": {"type": "integer", "description": "Distance/radius in km.", "minimum": 1, "maximum": 500},
"min_price": {"type": "integer", "description": "Minimum EUR price.", "minimum": 0},
"max_price": {"type": "integer", "description": "Maximum EUR price.", "minimum": 0},
"sort_by": {"type": "string", "description": "Sort order.", "enum": ["date", "price_asc", "price_desc"]},
"limit": {"type": "integer", "minimum": 1, "maximum": 25, "default": 12},
"page_count": {"type": "integer", "minimum": 1, "maximum": 10, "default": 1},
"start_page": {"type": "integer", "minimum": 1, "maximum": 200, "default": 1},
"category": {"type": "string", "description": "Category name or numeric ID."},
"shipping_only": {"type": "boolean", "description": "Only shippable listings."},
"max_age_days": {"type": "integer", "description": "Only return listings created in the last N days.", "minimum": 0}
},
"required": [],
"additionalProperties": false
}
Registered by default: Yes. Enable the Shopping group for the chat.
Requests require KLEINANZEIGEN_APP_BASIC; missing credentials produce a
configuration error when the tool is called.
Setup: Supply your own Kleinanzeigen app API access credentials:
Keep kleinanzeigen_search and kleinanzeigen_listing in your allowlist,
restart Numi, and enable the Shopping group for the chat. The default API base
is https://api.kleinanzeigen.de; override it with KLEINANZEIGEN_API_BASE.
Without API access, leave the group disabled. Use TOOLS_DENYLIST to prevent
registration.
KLEINANZEIGEN_ENABLED=false is available for the provider's availability
check; these tools defer that check at registration, so it should not replace
the denylist as an access control.
kleinanzeigen_listing¶
Description: Fetch full Kleinanzeigen classified details, attributes, and seller info for up to 20 listing IDs.
Parameters:
{
"type": "object",
"properties": {
"listing_ids": {
"type": "array",
"items": {"type": "string"},
"description": "1–20 numeric Kleinanzeigen listing IDs.",
"minItems": 1,
"maxItems": 20
}
},
"required": ["listing_ids"],
"additionalProperties": false
}
Registered by default: Yes. Enable the Shopping group for the chat.
Requests require KLEINANZEIGEN_APP_BASIC; missing credentials produce a
configuration error when the tool is called.
ebay_search¶
Description: Search and filter eBay listings. Supports keywords or GTIN, category, price, condition, buying option, shipping, returns, seller country, sorting, and pagination. Output omits images and other verbose API fields.
Key parameters: query, gtin, category_id, min_price, max_price,
condition, buying_options, free_shipping, returns_accepted,
item_location_country, sort, page, and limit.
Provide at least one of query, gtin, or category_id; query and gtin
cannot be combined. Queries are limited to 100 characters and cannot contain
*. Prices must be finite and nonnegative, with min_price <= max_price.
The calculated offset (page - 1) * limit must not exceed 9,999.
Parameter schema:
{
"type": "object",
"properties": {
"query": {"type": "string"},
"gtin": {"type": "string"},
"category_id": {"type": "string"},
"min_price": {"type": "number", "minimum": 0},
"max_price": {"type": "number", "minimum": 0},
"condition": {"type": "string", "enum": ["NEW", "USED", "UNSPECIFIED"]},
"buying_options": {
"type": "array",
"items": {"type": "string", "enum": ["FIXED_PRICE", "AUCTION", "BEST_OFFER"]},
"uniqueItems": true
},
"free_shipping": {"type": "boolean", "default": false},
"returns_accepted": {"type": "boolean", "default": false},
"item_location_country": {"type": "string", "minLength": 2, "maxLength": 2},
"sort": {
"type": "string",
"enum": ["best_match", "price", "price_desc", "newly_listed", "ending_soonest"],
"default": "best_match"
},
"page": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 1},
"limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 12}
},
"required": [],
"additionalProperties": false
}
Registered by default: Allowlisted, but registered only when eBay is enabled
and EBAY_CLIENT_ID and EBAY_CLIENT_SECRET are configured. Enable the
eBay group for the chat.
Setup: Configure credentials for an eBay Production application with Browse API access:
The postal code is optional. Retain ebay_search and ebay_listing
in any custom allowlist, restart Numi, and enable the eBay group.
Defaults target EBAY_DE, German responses and delivery, and EUR.
The client obtains and caches OAuth application tokens.
EBAY_ENABLED=false disables the integration. Output defaults are
EBAY_MAX_SEARCH_RESULTS=50 and EBAY_MAX_DESCRIPTION_CHARS=3000;
see Configuration for the other settings.
ebay_listing¶
Description: Inspect one or multiple eBay listings using REST item IDs
returned by ebay_search. Returns compact price, shipping, seller,
availability,
returns, aspects, and bounded description information without images.
Parameters: item_ids accepts 1 to 10 REST item IDs in one call. Batched
detail lookup uses parallel single-item requests and does not require eBay's
restricted bulk scope.
Parameter schema:
{
"type": "object",
"properties": {
"item_ids": {
"type": "array",
"items": {"type": "string", "minLength": 1},
"minItems": 1,
"maxItems": 10,
"uniqueItems": true
}
},
"required": ["item_ids"],
"additionalProperties": false
}
Registered by default: Allowlisted, but registered only when eBay is enabled
and EBAY_CLIENT_ID and EBAY_CLIENT_SECRET are configured. Enable the
eBay group for the chat.
mydealz_search¶
Description: Search or browse MyDealz deals with query, hot/new tab, deal type, group, merchant, price, temperature, online/expiry, and cursor filters. Returns compact deal facts and exact next/previous cursors without images.
With no query or explicit tab, the tool browses hot deals. Use after or
before for pagination; the two cursors cannot be combined. Prices must be
finite and nonnegative, with min_price <= max_price.
Parameter schema:
{
"type": "object",
"properties": {
"query": {"type": "string", "maxLength": 120},
"tab": {"type": "string", "enum": ["hot", "new"]},
"kind": {"type": "string", "enum": ["all", "deals", "discussions", "vouchers"], "default": "all"},
"group": {"type": "string", "description": "Category group name, slug, or numeric ID."},
"merchant_id": {"type": "integer", "minimum": 1},
"min_price": {"type": "number", "minimum": 0},
"max_price": {"type": "number", "minimum": 0},
"min_temperature": {"type": "integer"},
"only_non_expired": {"type": "boolean", "default": true},
"online_only": {"type": "boolean", "default": false},
"after": {"type": "string"},
"before": {"type": "string"},
"limit": {"type": "integer", "minimum": 1, "maximum": 30, "default": 12}
},
"required": [],
"additionalProperties": false
}
Registered by default: Yes; enabled per chat through the MyDealz group.
Setup: No user credentials are required. Retain mydealz_search and
mydealz_deal in any custom allowlist, then enable the MyDealz group for the
chat.
Output limits default to MYDEALZ_MAX_SEARCH_RESULTS=30,
MYDEALZ_MAX_DESCRIPTION_CHARS=2400, and MYDEALZ_MAX_COMMENT_CHARS=600.
Set MYDEALZ_ENABLED=false and restart to disable registration.
mydealz_deal¶
Description: Inspect one deal by ID with a bounded description and optionally up to ten compact comments. Community text is treated as untrusted content.
Parameter schema:
{
"type": "object",
"properties": {
"deal_id": {"type": "integer", "minimum": 1},
"comments_limit": {
"type": "integer",
"minimum": 0,
"maximum": 10,
"default": 0,
"description": "0 omits comments; use 3-5 for caveats."
},
"comment_sort": {"type": "string", "enum": ["newest", "oldest"], "default": "newest"}
},
"required": ["deal_id"],
"additionalProperties": false
}
Registered by default: Yes; enabled per chat through the MyDealz group.
geizhals_search¶
Description: Search for products on Geizhals price comparison. Requires the Geizhals sidecar server to be running.
Parameters:
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Product keywords.",
"minLength": 1
},
"limit": {
"type": "integer",
"description": "Max results (default 8, max 25).",
"minimum": 1,
"maximum": 25,
"default": 8
}
},
"required": [
"query"
],
"additionalProperties": false
}
Registered by default: No. Append geizhals_search and geizhals_product
to the allowlist and enable the Price Search group.
Setup: Run the separate Geizhals API service using its own installation instructions.
In Numi's configuration, append geizhals_search and geizhals_product to the
existing allowlist. The client defaults to
http://127.0.0.1:8000; set TOOLS_GEIZHALS_API_BASE_URL in the server process
environment to the sidecar address reachable from Numi. A local .env entry
alone does not load this direct environment setting. In Docker, Compose's
env_file injects it, and container localhost does not
refer to a service on the host.
Restart Numi and enable the Price Search group. The sidecar must return
{"status": "ok"} at /health for its availability check. Discovery
defers that check, so allowlisted tools can remain registered while the
sidecar is offline; calls will fail until it is reachable.
Use the denylist to block access. TOOLS_GEIZHALS_ENABLED controls the
availability probe, not registration or each execution.
geizhals_product¶
Description: Fetch Geizhals product (a…) or variant (v…) details by
prefixed ID or URL: offers, price history, ratings, and optional specs.
Parameters:
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Prefixed ID from geizhals_search ('a123' product, 'v456' variant) or Geizhals URL."
},
"days": {
"type": "integer",
"minimum": 1,
"maximum": 365,
"default": 31,
"description": "Price history lookback in days (products)."
},
"loc": {
"type": "string",
"default": "de",
"description": "Locale: de or at."
},
"offers_limit": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"default": 5,
"description": "Max cheapest offers (products)."
},
"specs_limit": {
"type": "integer",
"minimum": 0,
"maximum": 30,
"default": 0,
"description": "Max specs to include (0 = omit)."
}
},
"required": [
"id"
],
"additionalProperties": false
}
Registered by default: No
chefkoch_search¶
Description: Search Chefkoch for tested German recipes by keyword, or fetch
recipes of the day (daily=true). Returns compact summaries with id, title,
rating, times, and canonical url. Use chefkoch_recipe for full ingredients and
steps.
No user credentials are required. TOOLS_CHEFKOCH_ENABLED=false makes the
provider's availability check fail; these tools defer that check during
discovery.
Use the denylist to block registration. This switch is read from the process
environment, not directly from a local .env file.
Parameters:
{
"type": "object",
"properties": {
"query": {"type": "string", "description": "Recipe search keyword(s); omit when daily=true."},
"daily": {"type": "boolean", "description": "Fetch recipes of the day instead of searching.", "default": false},
"limit": {"type": "integer", "description": "Max results. Default 10, max 25; with daily=true default 3, max 10.", "default": 10},
"offset": {"type": "integer", "description": "Pagination offset.", "default": 0},
"maximum_time": {"type": "integer", "description": "Max total preparation time in minutes."},
"minimum_rating": {"type": "number", "description": "Minimum average rating (1-5)."},
"has_image": {"type": "boolean", "description": "Only recipes with photos."},
"tags": {"type": "string", "description": "Comma-separated Chefkoch tag filter."}
},
"required": [],
"additionalProperties": false
}
Registered by default: Yes. Enable the Recipes group for the chat.
chefkoch_recipe¶
Description: Fetch full Chefkoch recipe details for 1 to 5 recipe IDs. Returns servings, times, ingredients, instructions, tips, and canonical url.
Parameters:
{
"type": "object",
"properties": {
"recipe_ids": {
"type": "array",
"items": {"type": "string"},
"description": "1–5 Chefkoch recipe IDs.",
"minItems": 1,
"maxItems": 5
}
},
"required": ["recipe_ids"],
"additionalProperties": false
}
Registered by default: Yes. Enable the Recipes group for the chat.
YouTube transcript helper¶
Description: Internal transcript and metadata extractor for YouTube videos.
Not registered as a standalone tool: pass YouTube URLs to fetch_web_page
instead.
Note: YouTube URLs passed to fetch_web_page are automatically routed to
YouTubeTranscriptTool via YouTubeUrlHandler.
Features:
- Fetches video metadata via yt-dlp
- Fetches transcripts via youtube-transcript-api with WebVTT track fallback
- Auto-selects transcript from preferred languages (
["de", "en"]by default) - Returns compact timestamped transcript text and chapter headers
Dependencies:
yt-dlppackageyoutube-transcript-apipackage
Note: YouTube frequently changes their systems, so extraction may occasionally fail. Try upgrading yt-dlp if issues occur.
Registered by default: No (used internally by fetch_web_page)
Tool Configuration¶
Tool Allowlist/Denylist¶
Tools can be configured using environment variables:
TOOLS_ALLOWLIST¶
Comma-separated list of tool names allowed at startup. The default is:
web_search,fetch_web_page,weather_fetch,code_interpreter,codemode,remember_fact,forget_fact,
recall_memory,past_chats,view,create_file,generate_image,read_skill,numi_docs,grocery_search_stores,grocery_profile,
grocery_get_offers,chefkoch_search,chefkoch_recipe,
kleinanzeigen_search,kleinanzeigen_listing,
academic_search,wiki_lookup,ebay_search,ebay_listing,mydealz_search,mydealz_deal
Optional tools also need their chat group activated. TOOLS_DENYLIST blocks a
tool even when it is allowlisted; its default is empty.
Rules:
- Denylist match → blocked.
- Missing allowlist match → blocked, except
request_tool_activation,research_spawn, andresearch_poll. - Availability checks may omit a tool; tools that defer this check report setup errors when called.
Tool Discovery¶
Tools are auto-discovered by the ToolRegistry at startup based on:
- Python files directly in
src/numi_chat/tools/are imported. - Concrete tool classes are instantiated without arguments.
- The allowlist, denylist, and availability policy determine registration.
New tools should inherit BaseTool. register_in_registry = False
excludes helper classes. A new optional tool must also be listed in
CUSTOM_TOOL_NAMES to be selectable in the web app; see
Adding Custom Tools.
Tool Availability¶
During discovery, ToolRegistry checks the allowlist, denylist, and each
tool's availability policy. Core tools such as code_interpreter remain
registered when optional runtime setup is missing and return a structured error
from execute(). Custom integrations may be omitted when credentials or a
sidecar are unavailable.
Tool Execution¶
ToolExecutorService checks the chat's active tool names and supplies
server-owned chat/user context. Concurrency-safe tools use a thread pool;
tools with concurrency_safe = False run serially within a batch.
Execution admission, output size, and the agent deadline are bounded.
A running Python call is not forcibly stopped at the deadline, so network
tools must set their own request timeouts.
Schema Modes¶
From config, TOOLS_SCHEMA_MODE="compact":
- compact: Truncate descriptions to
TOOLS_SCHEMA_DESCRIPTION_MAX_LEN - verbose: Keep full descriptions
TOOLS_SCHEMA_STRIP_PARAM_DESCRIPTIONS defaults to false; set it to true
only when provider token budgets require smaller schemas.
Tool Schema¶
BaseTool Abstract Class¶
All tools inherit from the BaseTool abstract class with these properties:
name¶
- Type: String
- Description: The name of the tool (must be unique)
- Required: Yes
description¶
- Type: String
- Description: A description of what the tool does
- Required: Yes
parameters¶
- Type: Dict[str, Any]
- Description: The JSON schema for the tool's parameters
- Required: Yes
execute()¶
- Type: Method
- Description: Execute the tool's logic with given parameters
- Returns: Use the response helpers below to return a JSON string
is_available()¶
- Type: Function
- Description: Check if the tool can run in the current environment
- Returns: Boolean
availability_reason()¶
- Type: Optional method returning
str | None - Description: Human-readable reason used when a tool is skipped during discovery
- Default: Not defined by
BaseTool; implement it when useful
Tool Reminders (system_hint)¶
- Declaration:
@tool_system_hints({...})decorator on the tool class - Purpose: Output-only reminders that steer the model during tool workflows
- Injection point: Added to tool result payload as
system_hint - Not included in: Function schema/definition
Response Methods¶
Tools have three response methods:
_ok(): Success response with data_noop(): No operation response_error(): Error response
Tool Schema Format¶
Tools are converted to OpenAI-compatible function schemas:
{
"type": "function",
"function": {
"name": "tool_name",
"description": "Tool description",
"parameters": {
"type": "object",
"properties": {
"param_name": {
"type": "string",
"description": "Parameter description"
}
},
"required": ["param_name"]
}
}
}
URL Handlers¶
fetch_web_page delegates per-URL fetching to a small handler registry defined
in src/numi_chat/tools/url_handlers.py. Each handler matches a URL pattern and
knows how to retrieve content from that source.
UrlHandler ABC¶
class UrlHandler(ABC):
def matches(self, url: str) -> bool: ...
def fetch(self, url: str, **options: Any) -> dict[str, Any]: ...
fetch() must return a dict with at least url, title, and text keys. Add
an error key on failure.
Built-in handlers¶
| Handler | Matches | Implementation |
|---|---|---|
YouTubeUrlHandler |
youtube.com, youtu.be URLs |
YouTubeTranscriptTool (transcript + metadata) |
ArxivUrlHandler |
arxiv.org, export.arxiv.org, ar5iv.labs.arxiv.org |
arXiv Atom API metadata + PDF text extraction via pypdf |
PdfUrlHandler |
Direct .pdf URLs, /pdf/ endpoints |
Multi-page structured PDF extraction via pypdf (25MB limit) |
| ### Adding a custom handler |
Implement the UrlHandler contract and call register_handler(instance)
before requests are handled. See src/numi_chat/tools/url_handlers.py and
tests/tools/test_url_handlers.py for the existing pattern. Match parsed
hostnames
and preserve the existing URL validation and bounded-fetch behavior.
Tool Best Practices¶
Validate model-supplied inputs inside execute; a JSON schema is not a
runtime authorization check. Use the server-supplied chat/user context for
ownership checks, give external requests timeouts, and keep output bounded.
Custom Python tools run with the server's permissions unless their
implementation provides its own sandbox.
Tool Examples¶
Example: Using web_search tool¶
{
"name": "web_search",
"parameters": {
"query": ["Python async await", "Python coroutines tutorial"]
}
}
Illustrative response excerpt:
{
"status": "success",
"data": {
"query": ["Python async await", "Python coroutines tutorial"],
"results": [
{
"query": "Python async await",
"title": "Async IO in Python: A Complete Walkthrough",
"url": "https://realpython.com/async-io-python/",
"snippet": "Async IO is a concurrent programming design..."
}
]
}
}
Example: Using fetch_web_page with YouTube¶
{
"name": "fetch_web_page",
"parameters": {
"urls": [
"https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"https://example.com/article"
]
}
}
The YouTube URL will be handled by the native transcript handler, while the other URL uses local extraction when enabled and otherwise uses the configured web fetch providers.
Example: Using code_interpreter tool¶
{
"name": "code_interpreter",
"parameters": {
"code": "import matplotlib.pyplot as plt\nimport pandas as pd\ndf = pd.DataFrame({'x': [1, 2, 3], 'y': [4, 5, 6]})\nsave_file('data.csv', df.to_csv(index=False))\nplt.plot(df['x'], df['y'])\nplt.show()"
}
}
Interpreter results keep output and file mappings once, inside data.
status, and any error or hint, are top-level fields. Existing saved
results retain their original format and remain readable.
Illustrative response (generated filenames vary):
{
"status": "success",
"data": {
"output": "",
"files": [
"/generated-files/11111111-1111-4111-8111-111111111111/abc123.png",
"/generated-files/11111111-1111-4111-8111-111111111111/def456_data.csv"
],
"file_map": {
"abc123.png": "/generated-files/11111111-1111-4111-8111-111111111111/abc123.png",
"data.csv": "/generated-files/11111111-1111-4111-8111-111111111111/def456_data.csv"
},
"code_interpreter_file_map": {
"data.csv": "/mnt/data/generated/def456_data.csv"
}
}
}