Nox Tools
Audience: Engineering · QA · Support · Management · Where in app: Internal — invoked automatically when you chat with Nox · Plan availability: All Nox plans (individual action tools are entitlement-gated)
A "tool" is a structured function Nox can call mid-answer to fetch scoped data or take an action. The LLM never queries the database directly — it asks a tool, the tool runs a tenant-scoped query, and the result comes back structured. The v1 knox_* tools are registered in ms-ai/src/knox-agent/tools/knox-tool-registry.ts; the v2 engine reuses most of them and adds its own native tools — see v2 engine tools. Every call is tenant-scoped, OTel-traced (knox.tool.<name>), and logged to knox_usage_events. Since 2026-07 the LLM reads a curated markdown rendering of each result (services/knox-tool-markdown.ts) while the structured object still feeds the canvas/citations; the per-turn model_markdown is persisted for the admin conversation viewer. Transcript/session/facts/action-feed tools (knox_chat_transcript, knox_call_transcripts, knox_call_transcript_full, knox_session_search, knox_extracted_facts, knox_action_feed) have custom renderers — the generic renderer only walked scalar fields, so nested messages[]/conversations[]/facts[] were silently dropped from what the model saw.
This page merges the Nox knowledge-base tool list with the actual code registry, so a few names differ from older docs (e.g. the KB's
knox-aggregateisknox_aggregatein code;knox-send-notificationis now realized asknox_draft_followup/knox_send_followup/knox_enrich_contact). The table below is authoritative against the code as of this writing.
v2 engine tools
On the v2 engine (every company since 2026-11-02) the planner — not an intent router — picks tools. Every tool is filed under a domain in ms-ai/src/knox-v2/tools/domains.ts, and each domain carries one code-owned "use for / not for" line the planner reads beside the tools. tools/manifest.ts gives each v1 tool a tier (read, reversible_write, external_send, irreversible) that drives autonomy (auto + Undo vs a card) and the send guard. Researchers only get read tools; writers get the rest. v1 tools reach v2 through adapter/tool.adapter.ts; native tools live in tools/native/ (48 files).
| Domain | Native tools (plus the v1 knox_* tools filed there) |
|---|---|
pipeline | knox_query (backend named queries — pipeline_deals, leads, agentk_setup, …), hunt_material, stage_people, stage_meaning_confirm / stage_meanings_set, stalled_deals, dormant_review, deal_set (value, owner, next step, won/lost reason), task_create / task_done, contact_note_add, customer_found |
contact | group_email (queued in nox_email_queue), group_call, calendar_free_slots, plus knox_place_call, knox_schedule_sms, knox_draft_followup / knox_send_followup, knox_book_meeting, knox_engage_visitor, knox_visitor_watch |
email | email_search, email_thread_get, email_send, crm_email_task (the business mailbox; GHL when no mailbox) |
conversations | call_agents_report, call_log_search, trend_compare, agency_playgrounds, plus the session/visitor/transcript/stats knox_* reads |
agents | agent_review, agent_instructions_rewrite, agent_lesson_add / _remove / _results, agent_reply_preview, agents_list, agentk_redraft, agentk_step_edit, call_retry_rule, sales_lesson_apply, sales_reply_rule_add |
automations | automation_guide, automation_draft, automation_review, automation_update, automation_rename, automation_publish, automation_undo, automation_delete |
agentk | agentk_icp_adjust, agentk_message_variant, agentk_prospect_rate, agentk_sequence_pause, plus knox_agent_k_pipeline / knox_agent_k_weights |
admin | ask_admin, contact_admin, admin_callback / _cancel, look_at_screen, rule_record / rule_list / rule_apply_note, guard_rule_set, goal_set / goal_list / goal_progress / goal_close, alert_mute / alert_unmute / alerts_recent, do_not_disturb, nox_style_set, nox_wake_voice_set, nox_escalate (hand-off → support ticket) |
nox | plan_today, plan_set, plan_item_update, plan_prefs, standup_facts, standup_record, check_in_answer, case_open / _get / _list / _note / _update / _close, notes_read / notes_write (run-scoped), nox_recent_work, nox_waiting, knox_remember |
knowledge | profile_get / profile_update (business profile), nox_qa_add / _edit / _delete, nox_restore, knox_knowledge_search |
setup | get_page_guide (page guides + approved product notes), get_onboarding_state, feature_signals, adoption_next_check, recommendation_send, nox_agent_configure, nox_name_set, plus knox_config_* and navigation |
billing | get_billing_facts (plan, wallet, connection fees) |
product_api | api_search, api_read, api_check, api_call — the product's own API for what no listed tool covers (backend NoxApiCallController) |
web | web_research (gpt-4o-mini Responses API, NOX_WEB_RESEARCH_DAILY_CAP 20/company/day) |
crm_external | knox_crm (GHL / HubSpot / Jobber / Salesforce, only when connected) |
The voice agent carries none of these — it delegates to a v2 run with nox_delegate (see Voice).
How Nox picks a tool (v1 fallback)
Each sub-agent has an allowlist — it can only call tools on its list. The intent classifier routes the question to a sub-agent, and that sub-agent's system prompt tells it which tool to reach for. For ambiguous questions, the generalist sees nearly the full toolset. See What is Nox for the routing map.
- Read tools return data and never change anything.
- Action tools (marked
kind: 'action') have side effects (place a call, send a message, write a CRM note). They are mirrored into the unified action feed (knox_action_events,source='nox_write') for "what did Nox do?" auditing, supportdry_runpreviews, and are idempotency-keyed so a re-asked action collapses to one side-effect.
The full tool registry
Legend for Sub-agents column: Nav = navigation, An = analytics, Kn = knowledge, Act = action, Out = outreach, Gen = generalist.
Product knowledge & navigation
| Tool | What it does | Reads / Writes | Sub-agents |
|---|---|---|---|
knox_knowledge_search | Searches the Knock Knock product knowledge base (this docs corpus). Takes only query (the model-set area/type filters were removed 2026-10). Returns numbered sources S1, S2… the LLM must cite as [S1]. 3-prong retrieval (URL-filtered + global + summary) merged by reciprocal rank fusion, then Cohere rerank. | Reads knox_knowledge_chunks (pgvector). Write: none. | Nav, Kn, An, Act, Gen |
knox_page_context | Detailed metadata about a specific portal page — purpose, UI elements, related settings. | Reads knox_page_registry. | Kn, Gen |
knox_navigate | Finds portal pages related to a topic (page discovery). | Reads knox_page_registry. | Kn, Gen |
knox_propose_navigation | Surfaces a navigation action card with a 3s countdown + Cancel. URL must come from a portal_urls: line of a knowledge-search source — never invented. Max 1 per answer. | Validates against the URL allowlist; renders UI card. | Nav, Kn, An, Act, Gen |
knox_open_record | Opens a specific session recording in the portal ("open that session", "play it"). Pass a user_session_id from an earlier tool result. | Renders a navigation card to the recording. | Nav, An, Gen |
Person, visitor & session
| Tool | What it does | Reads / Writes | Sub-agents |
|---|---|---|---|
knox_person_lookup | Resolves a free-form reference (name / email / phone / company) to one or more identity-graph Person entries. Call this FIRST when a question names a person. Surfaces CRM-only contacts: crm_only: true = a real lead that exists only in GHL/HubSpot (e.g. Agent-K-created, never seen on-site); mention_only: true = only spoken/typed about — never draft/send to it. Result rows carry pid:<person_id> for downstream tools (knox_visitor_watch). Name matching is fuzzy: one substituted character tolerated for pure-letter tokens of 4–12 chars (STT mishears — backend 864d3c0ae); emails, digits, short tokens stay exact. | Reads people / person_profiles + connected CRM. | An, Out, Gen |
knox_visitor_profile | Cross-visit profile for one visitor by user_session_id: visit count, engagement, intent trajectory, devices[] set, optional timeline + first-vs-last comparison. | Reads knox_visitor_profiles / visitor_profiles. | An, Out, Gen |
knox_visitor_search | Semantic search across visitors over their narrative summaries (pgvector ANN over knox_search_index). Behavioural/topical only — NOT for name lookups. | Reads knox_search_index. | An, Gen |
knox_session_analysis | Full structured analysis for one visit by file_id: intent, page trips, friction, device fields, hour/day, optional LLM narrative. | Reads knox_session_analyses. | An, Out, Gen |
knox_session_search | Semantic search across analyzed sessions ("rage-clicked checkout"). Pass user_session_id to scope to one visitor's history. Does NOT sort by time. | Reads knox_search_index / knox_session_analyses. | An, Gen |
knox_recent_sessions | Most-recent recorded visits, strict ORDER BY analyzed_at DESC. The only tool that sorts by time — use for "who visited last". Returns real file_id + user_session_id. | Reads knox_session_analyses. | An, Gen |
knox_history_lookup | Pulls Nox's own recent Q+A pairs for this admin ("you said something different yesterday"). | Reads knox_agent_conversations. | An, Gen |
knox_extracted_facts | Typed facts extracted from chats/calls (budgets, objections, competitors, timelines, use cases). | Reads person_profiles.extracted_facts (via mirror). | An, Out, Gen |
Conversations, bookings & calls
| Tool | What it does | Reads / Writes | Sub-agents |
|---|---|---|---|
knox_call_transcripts | Voice call transcripts ranked by quality. Returns conversation_id, visitor_id, duration, outcome, sentiment, quality_score (0–1), quality_method, summary, when_local. | Reads knox_call_transcripts. | An, Out, Gen |
knox_call_transcript_full | One call by conversation_id, including the verbatim turn-by-turn transcript JSON. Don't loop it — the JSON is large. | Reads knox_call_transcripts. | An, Gen |
knox_chat_transcript | Full widget/channel chat transcript(s) for one visitor by user_session_id (resolve via knox_person_lookup first). Newest-first, one per channel. A chat_id that matches no chat is retried as a session id (the model mixes the ids up — backend 3664de145). | Reads backend /internal/knox/chats/transcript. | An, Out, Gen |
knox_visitor_bookings | Booking/meeting/appointment history for one visitor, oldest→newest, with created_at. | Reads user_sessions.bookings[] / bookings. | An, Out (via profile path), Gen |
knox_recent_bookings | Bookings across the tenant in a window. A row matches if created in the window OR its meeting day falls in it (matched_via says which). The right tool for "today's meetings". | Reads bookings / user_sessions.bookings[]. | An, Gen |
Analytics & stats
| Tool | What it does | Reads / Writes | Sub-agents |
|---|---|---|---|
knox_stats | Tenant business stats — sessions, conversations, bookings, traffic mix, hot leads, friction, top pages. Two kinds: baseline (rolling 30-day "normal") and window (metric: headline | traffic_sources | timeline | hot_leads | friction_summary | top_pages). Use first for "how many" / "hot leads" / "conversion rate". | Reads backend stats endpoints (same source as the dashboard). | An, Gen |
knox_aggregate | Behavioural metrics not in knox_stats: bounce_rate, rage_cluster_count, dead_click_pages, top_exit_pages, top_questions, termination_reasons; cohort lists (unengaged_visitors, engaged_no_booking, form_abandonment_pages, silent_visitors); conversion_funnel; pipeline-stage cohorts; crm_linked_active (may lag — prefer knox_crm kind=recently_identified); page_order, visitor_paths. | Reads pre-computed analysis artifacts + visitor-profile mirror. | An, Gen |
knox_presence | Real-time "who is on the site right now" snapshot. Tenant-wide → visitors_on_site_now, by_page, by_visitor_profile_id (named, with pipeline_stage). With user_session_id → scalar online/current_url/connected_at. | Reads ms-sessions presence registry (Redis). | An, Gen |
knox_is_visitor_live | Is a specific person on the site right now? Resolve via knox_person_lookup first, pass name + candidate person_ids/user_session_ids. Matches across fragmented identity. NOW-only. | Reads ms-sessions presence. | Gen |
knox_daily_brief | Composes today's brief (current calendar day, admin tz): traffic, funnel, bookings, lost leads. Returns templated summary_md. | Reads canonical backend stats endpoints. | An, Gen |
CRM & action-feed (read)
| Tool | What it does | Reads / Writes | Sub-agents |
|---|---|---|---|
knox_crm | Queries the connected CRM (GoHighLevel, HubSpot, Jobber, or Salesforce — the result's provider names which, so Nox can say what it read) for live pipeline/opportunity/contact data. Kinds include presence_identified, recently_identified, search_contact, pipelines, opportunities, contact_stage, contact_sessions. recently_identified reads user_sessions directly (source of truth, no lag). | Reads CRM via integration creds + user_sessions. | An, Out, Gen |
knox_action_feed | Unified read across every write-side action in the tenant — GHL workflows, Nox tools, voice bookings, calendar, email. Filter by visitor/source/action_kind/outcome/window. First-pass "what happened?". | Reads knox_action_events. | An, Gen |
knox_automation_activity | GHL-only automation events (workflows, outbound calls, SMS, email) — "did the missed-booking callback go through for Sarah?". Narrower than knox_action_feed. | Reads knox_ghl_automation_events. | An, Gen |
knox_list_scheduled_actions | The company's booked-for-later outreach (scheduled AI calls and agent SMS). Filters: kind (call/sms/all), status (default scheduled), paging. Renamed from the transient knox_list_scheduled_calls. Write sides: knox_place_call scheduled_at / knox_schedule_sms; cancellation stays on the admin surfaces (Calls page / SMS agent Scheduled tab / Chats Scheduled tab). | Reads backend scheduled_nox_actions. | Act, An, Gen |
Per-admin memory
| Tool | What it does | Reads / Writes | Sub-agents |
|---|---|---|---|
knox_remember | Stores a durable fact about this admin across sessions (a stated preference / stable working fact). One fact per call. | Writes knox_admin_memory (pgvector). | (memory utility) |
knox_recall | Searches what Nox remembers about this admin. (Top memories are already injected into context each turn; this is for targeted lookups.) | Reads knox_admin_memory. | (memory utility) |
Action tools (side effects — entitlement-gated)
| Tool | kind | What it does | Reads / Writes | Sub-agents |
|---|---|---|---|---|
knox_place_call | action | Initiates an outbound AI call to a visitor via ElevenLabs/Twilio. Phone resolved from the profile — never passed in. Idempotency keyed on (visitor, booking, day). Supports dry_run. Suppressed if a GHL workflow already dialled today. Optional scheduled_at (ISO, max 30 days out) books the call instead — backend fires it at the exact time via the BullMQ scheduled-action queue (see Nox subsystem), deferring quiet-hours slots to the next 9am local; cancel via POST /knox/actions/scheduled/:id/cancel. Per-contact channel frequency caps enforced backend-side. | Reads profile; writes outbound call / scheduled_nox_actions + knox_action_events. | Act |
knox_schedule_sms | action | Books an SMS-agent text for later ("text Sarah tomorrow at 10am"). Two modes mirroring the /ai-sms/webhook contract: plain sends the message verbatim; ai composes from context at fire time. Fired at the exact time by the scheduled-action queue (quiet hours defer to next 9am contact-local; a contact with no timezone is judged by their number's region); the fired row keeps result.body (the words sent) and result.from. Cancel from the SMS agent screen's Scheduled tab or the Chats Scheduled pane. Target via user_session_id (phone from profile), or phone verbatim; ghl_contact_id links audit + DND checks. | Writes scheduled_nox_actions (kind sms). | Act, An, Gen |
knox_engage_visitor | action | Sends an auto-trigger message into a LIVE visitor's widget right now ("nudge Sarah while she's on pricing"). Message is written by the widget's greeter pipeline biased by instruction (or literal message verbatim); book biases toward booking; force overrides the auto-engage cooldown. Requires confirmed: true; supports dry_run. Delivery is receipt-confirmed: ms-comm relays the widget delivery receipt to backend POST /internal/engage-receipt — not_live/undeliverable comes back honestly. For "next time they return" use knox_visitor_watch action=engage. | Reads presence; writes widget message + knox_action_events. | Act, An, Gen |
knox_draft_followup | action | Composes a customer-facing email/SMS draft for review (the LLM writes the body, the tool persists a DRAFT + in-chat Send card). Does not send unless the account opted into autonomous send. Drafts end on the last sentence — backend NoxGhlActionService._send appends the tenant signature deterministically at send. Target via user_session_id or ghl_contact_id. | Writes a draft action (NoxActionModel / knox_action_*). | Out, An |
knox_send_followup | action | Approves and sends a previously-drafted follow-up via the CRM. Call only after explicit "send it" confirmation, with the draft's action_id + confirmed: true. Honesty-gated: only status "sent" means it went out. | Writes/sends message via CRM; updates action. | Out, An |
knox_discard_followup | action | Discards a drafted/failed follow-up without sending (the conversational Dismiss) by its nox_action_id; also used to clean up drafts the model superseded. A sent action can't be discarded. requiredRole: admin. | Writes action status dismissed. | Act, Out, An, Gen |
knox_enrich_contact | action | Writes a structured internal note (intent score, pages, source, last visit) + a coarse intent tag onto a GHL contact. Internal CRM note, not a customer message. | Writes to GHL contact. | Act, Out, An |
Visitor watch (standing alerts)
The four former watch tools are consolidated into one tool with an action parameter:
| Tool | What it does | Reads / Writes | Sub-agents |
|---|---|---|---|
knox_visitor_watch | action=notify alerts the admin when a specific (verified) visitor returns; action=engage has the AI proactively engage on return with an instruction, optionally nudging a booking, once or recurring; action=list shows active watches; action=cancel stops one by id. notify/engage require a real person_id from knox_person_lookup. | Reads/writes directives (KnoxVisitorDirectiveModel). | Out, Gen |
Delivery: auto-engage messages are composed and pushed by ms-communication (POST /nox-auto-engage). Tenants can also list/cancel watches in Settings → Nox (GET/DELETE /knox/visitor-watches); admin diagnostics (last_attempt_at, last_skip_reason) render only in the super-admin view.
Nox funnel tools (funnel-enabled tenants)
See Nox Funnel for the engine. All action results are honesty-gated — ok:false means it did not happen.
| Tool | kind | What it does | Sub-agents |
|---|---|---|---|
knox_funnel | read | The source of truth for lead-state questions: summary (stage counts + very-warm hot list), priorities (ranked who-to-contact-next with reasons + suggested channel), stats (deterministic conversion/velocity/pacing math), contact (one contact's journey). If not enabled, fall back to knox_stats. | An, Gen |
knox_tag_contact | action | Adds/removes GHL tags on a contact (auto — no confirmation). | Act, Gen |
knox_move_pipeline | action | Moves/creates a GHL opportunity into a mapped pipeline stage; reports mode moved / created / tag_fallback (scope-refused writes fall back to a tag). | Act, Gen |
knox_trigger_workflow | action | Enrolls a contact in a GHL workflow — confirmation per nox_funnel.actions.workflow_trigger_mode (default confirm). workflow_id accepts an id or a name from pipeline_mapping.workflows; with a non-empty mapping an unmatched value returns unknown_workflow + the mapped names. | Act, An, Gen |
knox_book_meeting | action | Books a GHL calendar slot — hard confirm (confirmed: true); booked only when an appointment_id comes back. | Act, An, Gen |
knox_mark_customer | action | Marks a lead Won (terminal, manual-only stage) and drops it off the priority list; mark: false undoes. | Act, Gen |
knox_funnel_reconcile | action | Lists/applies the reconciliation queue ("9 people in Master Nurture behave like intermediate leads — tag them?"). The action prompt forbids building a mismatch list from knox_crm rows. | Act, An, Gen |
knox_brief_offers | action | Grounds "yes, do the first one" against the daily brief's persisted offers (brief_offers, ~48h validity) and executes via the mapped real tool. | An, Gen |
knox_agent_k_weights | action | Steers Agent K sourcing: sets a source/signal weight multiplier (0.25–3, rank-only, never volume). | Act, Gen |
Configuration & options
- Allowlists are per sub-agent, set in each
agents/knox-*.agent.ts. Changing what a specialist can do = editing its allowlist. - Role & plan gating: tools may carry
requiredRole(member < admin < owner) andrequiredPlanTier(free < starter < growth < pro < enterprise);getAvailableToolsfilters the toolset per caller. dry_runon action tools previews the side effect without committing.
Behaviors & edge cases
- Isolation. Every tool takes
company_idfrom auth context and scopes to that tenant. The cross-tenantknox_search_indexis filtered bycompany_idbefore returning. - Cohere rerank is best-effort in
knox_knowledge_search— on Cohere error (or noCOHERE_API_KEY) the reciprocal-rank-fusion order stands, cut to top-K. - Presence is a snapshot — may be stale by the time Nox answers.
knox_aggregatecrm_linked_activecan lag/undercount (reads the mirror) — for "who in my CRM visited this week",knox_crm kind=recently_identifiedis the source of truth.- Empty ≠ zero. Aggregate metrics with no eligible data return empty, and Nox should disambiguate rather than report "0".
- Action audit is fire-and-forget — it never fails the action; dry-runs are not audited.
- Invented ids are rejected honestly.
knox_session_analysis/knox_visitor_profilereturn an explicit "no analysis/profile found — the id may be invented" note instead of empty data; tool errors come back as structured_errorenvelopes the model must report, never paper over.
Plan & limits
- All read tools ship with any Nox plan. Action tools (
knox_place_call,knox_schedule_sms,knox_engage_visitor,knox_draft_followup,knox_send_followup,knox_enrich_contact) are individually entitlement-gated — verify per account. - Every tool call consumes tokens/credits (
knox_usage_events).
Roadmap gaps (tools not yet built)
- Account-entity tool — "is anyone from ACME on the site?" needs a normalized
account_key. - Pipeline-stitch tool — on funnel-enabled tenants
knox_funnel+ pipeline mapping now covers this; a generic CRM-stage join for non-funnel tenants is still missing. - Predict / recommend tools — need a learned model + recommendation persistence (the funnel brief's deterministic offers cover part of "recommend").
See Capabilities for which questions these gaps block.
Technical implementation
- Registry:
ms-ai/src/knox-agent/tools/knox-tool-registry.ts(register/getAvailableTools/executeTool). Each tool implements theKnoxToolinterface (tools/knox-tool.interface.ts) with a Zodparametersschema and anexecute(input, context). - Action tools implement the extra
KnoxActionToolshape (tools/knox-action.tool.interface.ts) —kind: 'action',buildIdempotencyKey,resolveTargetVisitorId. - Telemetry: OTel span
knox.tool.<name>per call;KnoxToolCallCollectorwrites toknox_action_events/knox_action_audit; usage toknox_usage_events.
Related
- What is Nox — the assistant overview & routing
- Capabilities — done/partial/future per question type
- Daily Brief · Voice
- Nox / Knox Admin Assistant · Knowledge Base RAG
- Data model: collections & tables · Visitor data