Skip to content

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 a query of up to 200 characters. Use English keywords or an exact setting name. It returns up to five matching pages with a heading, excerpt, and start_line; no matches gives an empty list.
  • action: "read" takes a manual path and an optional one-based start_line (default 1). It returns up to 40 lines of Markdown and a next_start_line when 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.

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:realtime for the fastest mode), Exa (auto, dynamic highlights; exa:lite for 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; provider in the output names the one that answered
  • Experimental numi-search asks 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 it
  • include_domains limits results to known relevant sites; start_published_date filters after a date
  • Search returns excerpts, not full documents; use fetch_web_page to read full text
  • Unsupported legacy cache_only, text/summary, and end-date options return explicit errors
  • Validated output with query, results, provider, and optional errors
  • Each result entry is schema-validated and includes query, url, title, optional published_date, and snippet
  • Result entries include url, title, and snippet fields 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 citation marker 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:

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: true and an exact continuation offset in the text; read_full also respects this budget.
  • Web providers return at most the first 90,000 characters; neither offsets nor read_full can 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", omit query or use ""; offset and read_full are supported
  • For mode="highlights", optionally provide a focus query; omit offset/read_full or use 0/false
  • Direct handlers fetch from the source; live asks 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 (PageContentResultContract with url, title, author, text, offset, total_characters, truncated, fetch_status, and error)

Configuration:

  • DIRECT_WEB_FETCH_ENABLED=true enables local direct HTML extraction before the web providers; it defaults to false
  • WEB_FETCH_PROVIDERS sets the provider order; it defaults to WEB_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:

{
  "type": "object",
  "properties": {
    "code": { "type": "string" }
  },
  "required": ["code"]
}

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() or plt.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, and zoneinfo → tzdata for IANA time zones
  • Skill folders are mounted read-only at /mnt/skills/<name> when the code names that path; their scripts/ helpers import after adding the folder to sys.path, and the packages those helpers import load automatically. See Manage Skills
  • Pyodide packages are cached under state/code-sandbox after the first download, so later runs work without CDN access
  • Each Pyodide run is capped at TOOLS_CODE_INTERPRETER_MAX_MEMORY_MB, and at most TOOLS_CODE_INTERPRETER_MAX_CONCURRENT run 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 modules
  • TOOLS_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-monty 1.5 or newer (required) for scripts without third-party dependencies
  • mcp-run-python and Deno for third-party libraries and fallback execution
  • Optional: DENO_PATH if Deno not in PATH (legacy D_AI_DENO_PATH still 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:

NUMI_TEST_SANDBOX=1 uv run pytest tests/tools/test_code_interpreter.py -k office_files_roundtrip -q

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:

  • search ranks the user's other chats by how many query words they contain and returns up to 5 hits with a title, date and short snippet
  • recent lists the 8 most recently active chats, each pointing at its latest user message
  • read returns up to 3 turns from the hit onward, or the latest 3 without a message_id, at most about 9,000 characters, with earlier and later message 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 and read it 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_enabled switch 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_generator or code_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 example draft.png); the newest copy saved under that name is used. For a generated document, the error names its code_interpreter path.

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:1 at high quality
  • 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 (default openai/gpt-image-2.6-sunburst)
  • IMAGE_GEN_ASPECT_RATIO (default 1:1)
  • IMAGE_GEN_QUALITY (default high)
  • IMAGE_GEN_MAX_PROMPT_CHARS (default 4000)
  • IMAGE_GEN_TIMEOUT_CONNECT (default 10.0)
  • IMAGE_GEN_TIMEOUT_READ (default 240.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.

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:

uv run python src/numi_chat/tools/rewpi/get_rewe_certs.py --output-dir src/numi_chat/tools/rewpi

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_available and next_offset for 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.

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:

KLEINANZEIGEN_APP_BASIC="user:password"

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.

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:

EBAY_CLIENT_ID="your-app-id"
EBAY_CLIENT_SECRET="your-cert-id"
EBAY_DELIVERY_POSTAL_CODE="10115"

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.

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.

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

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-dlp package
  • youtube-transcript-api package

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:

  1. Denylist match → blocked.
  2. Missing allowlist match → blocked, except request_tool_activation, research_spawn, and research_poll.
  3. 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:

  1. Python files directly in src/numi_chat/tools/ are imported.
  2. Concrete tool classes are instantiated without arguments.
  3. 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"
    }
  }
}