Skip to main content

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-aggregate is knox_aggregate in code; knox-send-notification is now realized as knox_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).

DomainNative tools (plus the v1 knox_* tools filed there)
pipelineknox_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
contactgroup_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
emailemail_search, email_thread_get, email_send, crm_email_task (the business mailbox; GHL when no mailbox)
conversationscall_agents_report, call_log_search, trend_compare, agency_playgrounds, plus the session/visitor/transcript/stats knox_* reads
agentsagent_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
automationsautomation_guide, automation_draft, automation_review, automation_update, automation_rename, automation_publish, automation_undo, automation_delete
agentkagentk_icp_adjust, agentk_message_variant, agentk_prospect_rate, agentk_sequence_pause, plus knox_agent_k_pipeline / knox_agent_k_weights
adminask_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)
noxplan_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
knowledgeprofile_get / profile_update (business profile), nox_qa_add / _edit / _delete, nox_restore, knox_knowledge_search
setupget_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
billingget_billing_facts (plan, wallet, connection fees)
product_apiapi_search, api_read, api_check, api_call — the product's own API for what no listed tool covers (backend NoxApiCallController)
webweb_research (gpt-4o-mini Responses API, NOX_WEB_RESEARCH_DAILY_CAP 20/company/day)
crm_externalknox_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, support dry_run previews, 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​

ToolWhat it doesReads / WritesSub-agents
knox_knowledge_searchSearches 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_contextDetailed metadata about a specific portal page — purpose, UI elements, related settings.Reads knox_page_registry.Kn, Gen
knox_navigateFinds portal pages related to a topic (page discovery).Reads knox_page_registry.Kn, Gen
knox_propose_navigationSurfaces 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_recordOpens 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​

ToolWhat it doesReads / WritesSub-agents
knox_person_lookupResolves 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_profileCross-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_searchSemantic 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_analysisFull 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_searchSemantic 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_sessionsMost-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_lookupPulls Nox's own recent Q+A pairs for this admin ("you said something different yesterday").Reads knox_agent_conversations.An, Gen
knox_extracted_factsTyped facts extracted from chats/calls (budgets, objections, competitors, timelines, use cases).Reads person_profiles.extracted_facts (via mirror).An, Out, Gen

Conversations, bookings & calls​

ToolWhat it doesReads / WritesSub-agents
knox_call_transcriptsVoice 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_fullOne 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_transcriptFull 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_bookingsBooking/meeting/appointment history for one visitor, oldest→newest, with created_at.Reads user_sessions.bookings[] / bookings.An, Out (via profile path), Gen
knox_recent_bookingsBookings 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​

ToolWhat it doesReads / WritesSub-agents
knox_statsTenant 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_aggregateBehavioural 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_presenceReal-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_liveIs 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_briefComposes 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)​

ToolWhat it doesReads / WritesSub-agents
knox_crmQueries 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_feedUnified 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_activityGHL-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_actionsThe 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​

ToolWhat it doesReads / WritesSub-agents
knox_rememberStores 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_recallSearches 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)​

ToolkindWhat it doesReads / WritesSub-agents
knox_place_callactionInitiates 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_smsactionBooks 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_visitoractionSends 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_followupactionComposes 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_followupactionApproves 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_followupactionDiscards 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_contactactionWrites 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:

ToolWhat it doesReads / WritesSub-agents
knox_visitor_watchaction=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.

ToolkindWhat it doesSub-agents
knox_funnelreadThe 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_contactactionAdds/removes GHL tags on a contact (auto — no confirmation).Act, Gen
knox_move_pipelineactionMoves/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_workflowactionEnrolls 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_meetingactionBooks a GHL calendar slot — hard confirm (confirmed: true); booked only when an appointment_id comes back.Act, An, Gen
knox_mark_customeractionMarks a lead Won (terminal, manual-only stage) and drops it off the priority list; mark: false undoes.Act, Gen
knox_funnel_reconcileactionLists/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_offersactionGrounds "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_weightsactionSteers 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) and requiredPlanTier (free < starter < growth < pro < enterprise); getAvailableTools filters the toolset per caller.
  • dry_run on action tools previews the side effect without committing.

Behaviors & edge cases​

  • Isolation. Every tool takes company_id from auth context and scopes to that tenant. The cross-tenant knox_search_index is filtered by company_id before returning.
  • Cohere rerank is best-effort in knox_knowledge_search — on Cohere error (or no COHERE_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_aggregate crm_linked_active can lag/undercount (reads the mirror) — for "who in my CRM visited this week", knox_crm kind=recently_identified is 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_profile return an explicit "no analysis/profile found — the id may be invented" note instead of empty data; tool errors come back as structured _error envelopes 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 the KnoxTool interface (tools/knox-tool.interface.ts) with a Zod parameters schema and an execute(input, context).
  • Action tools implement the extra KnoxActionTool shape (tools/knox-action.tool.interface.ts) — kind: 'action', buildIdempotencyKey, resolveTargetVisitorId.
  • Telemetry: OTel span knox.tool.<name> per call; KnoxToolCallCollector writes to knox_action_events / knox_action_audit; usage to knox_usage_events.