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. There are 42 tools registered in ms-ai/src/knox-agent/tools/knox-tool-registry.ts. 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.

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.

How Nox picks a tool

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

Tool	What it does	Reads / Writes	Sub-agents
knox_knowledge_search	Searches the Knock Knock product knowledge base (this docs corpus). Returns numbered sources S1, S2… the LLM must cite as [S1]. 3-prong retrieval (URL-filtered + global + summary) with 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. Now also 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.	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.	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 or HubSpot) 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

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 ScheduledNoxActionJob (5-min cron) fires it, 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_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. 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_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-beta 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).	Act, Gen
knox_book_meeting	action	Books a GHL calendar slot — hard confirm (confirmed: true); booked only when an appointment_id comes back.	Act, 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?").	Act, 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) 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 it falls back to raw embedding distance.
• 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.

Plan & limits

• All read tools ship with any Nox plan. Action tools (knox_place_call, 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-beta 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.

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