TUCAN's reach into the EMR is a catalog of typed Mastra tools — ~350
createTucanTool definitions across ~35 categories — each one a thin
wrapper around a NestJS service call that mutates Prisma or FHIR or
publishes a UI side effect over SSE.
Business Purpose
The tool catalog is what TUCAN can actually do. A "clinical
assistant" is only as useful as the actions it can take in the real
system; Dudoxx's edge is that every clinical, scheduling, billing, and
document action the doctor can do by clicking is also available to
TUCAN by call.
Because every tool is the same code path as the UI (a NestJS service call
through the Trusted Gateway), every safeguard the UI has — RBAC, tenant
isolation, audit log, FHIR partition scoping — applies automatically to
the LLM. The LLM is not a privileged actor; it is a typed remote
control of the existing controllers.
Tools also serve a second business purpose: they are the surface
through which TUCAN renders UI. Modals, notifications, info-containers,
patient drawer focus, document previews, navigation — all happen by the
LLM calling a category: 'ui' tool that publishes a ui:action SSE
event instead of mutating data.
Audiences
Investor: The catalog is the moat made concrete. ~350 typed
surfaces — write a prescription, book an appointment, draft a referral
letter, open a modal — each one a one-week-to-add unit of product
scope. Competitors must redo the integration work clinic by clinic;
Dudoxx amortizes it across tenants.
Clinical buyer (doctor / nurse / receptionist): Whatever you do in
the UI, you can ask for in plain language. Order labs, prescribe,
schedule, draft letters, review interactions, summarize a chart,
search ICD-10 — the same RBAC rules apply, the same audit trail is
written, the same patient is scoped.
Developer / partner: Adding a tool is createTucanTool({ id, description, inputSchema, metadata, execute }) plus a registry entry.
The Mastra DI surface (createDIContainer from @mastra/core) gives
the execute function direct access to every injected NestJS service
via the context.services object — no parallel API stack.
Internal (ops / support): Every tool call writes a ChatMessage{ role:'tool' }
row and a TucanUsageRecord row. "Did the AI do X?" becomes a SQL
query on chat_messages.tool_calls.
UI tools are the way TUCAN drives the frontend without leaking display
concerns into clinical mutations. Every tool under tools/ui/ has
category: 'ui', mutating: false, calls no FHIR / Prisma, and
publishes one or more ui:action SSE events via
context.services.eventBus.publishUIAction(...).
11 sidebar variants, DB-upsert (the only mutating UI tool, conceptually)
clear-info-containers
DB only
clears the sidebar table — does NOT publish SSE (the DB change is silent to the frontend; a regression to file)
navigate-to
navigate
10 page types, no DB
play-audio-feedback
play_audio_feedback
voice channel chime
focus-patient-drawer
open-drawer
patient context drawer
open-patient-card-modal
open-modal (open_patient_card)
rich patient overview
open-clinical-summary-modal
open-modal (open_clinical_summary)
recent visits / vitals / meds rollup
open-document-preview
open-preview
one-shot doc preview
open-table-view
open-modal (open_table)
data-grid for lists
Hallucinated / not yet implemented (the LLM may try them; the
frontend dispatcher logs handler:dropped):
open_panel / close_panel — no backend tool nor frontend case
render_component — no frontend switch case for arbitrary
components yet
get_clinical_notes — wrong name; real tool is list-clinical-notes
UI tools that emit a modal must include a modalId: randomUUID() in
the published payload — the frontend useTUCANUIActions hook dedupes by
modalId and silently drops actions without one
(tools/ui/show-modal.tool.ts:117).
The full SSE wire format for ui:action is owned by [[sse-event-engine]]
(W1). On the consumer side, the React hooks and AG-UI bridge live in
ddx-web (see W5 frontend page once filled; for now the contract anchor
is ddx-web/src/lib/sse/global-manager.ts and the
useTucanSSE / useTUCANUIActions hooks documented in the
ddx-ai-ui-events-frontend skill).
Tech Stack & Choices
Choice
Rationale
createTucanTool({...}) typed factory
Single point to enforce metadata (category, ragDescription, ragKeywords, mutating, alwaysInclude) — review checklist (~/.claude/rules/shared/review-checklists/mastra.md) bans tools without ragDescription.
Zod v4 (zod/v4) input schemas
Backend rule: import { z } from 'zod/v4'. Bare 'zod' is reserved for ddx-web (Next.js).
LLM-perspective ragDescription
"USE WHEN / DO NOT USE WHEN / REQUIRES / PRODUCES" four-line shape — see show-modal.tool.ts:79-84. Drives tool-RAG retrieval ([[tucan-rag-tools]]).
Multilingual ragKeywords (EN + DE minimum)
Dudoxx is German-first; the tool-RAG embedding space must match the operator's language.
`mutating: true
false` flag
`alwaysInclude: true
false`
outputInstructions field with "NEVER show UUIDs"
Mandatory when the output contains IDs; mastra checklist rule.
Per-agent static category filter
The agent gets its tool list at new Agent({ tools: filterByCategory([...]) }) time. No per-turn semantic reduction — see [[tucan-rag-tools]] for the dormant SkillSearchProcessor pitfall.
Hyphenated tool IDs
Mastra auto-converts 'show-modal' to show_modal for the LLM. Non-hyphenated IDs collide with this conversion.
Frontend deduping by modalId / containerId
SSE has at-least-once semantics; the consumer must dedupe. The publisher must provide a stable ID.
Data Flow
Business outcome: A doctor types "Check drug interactions for the
current med list before I add metformin." TUCAN reads the patient's
active medications from FHIR, runs the drug-interaction tool, and
opens a drug-interaction modal with severity colors — no data
mutation, just a UI side effect.
Technical mechanism:
Dispatcher resolves agent 'clinical', which has the
medications, clinical, fhir, ui categories bound at
construction (ddx-api/src/ai/tucan/registry/agent-type.registry.ts).
LLM emits a tool call: list-active-medications (category
medications).
The tool's execute(input, ctx) calls
ctx.services.medicationsService.listActive(...) — the real
NestJS service, with the doctor's tenant header forwarded.
ddx-api/src/ai/tucan/registry/tool-choice-guard.ts — guard that
prevents the LLM from picking a tool outside the bound catalog.
Operational Notes
The catalog count drifts. As of 2026-05-18, rg -c "createTucanTool" ddx-api/src/ai/tucan/tools reports 354 calls
across 168 files. Project memory previously said "130 tools"
(memory shard MEMORY_TUCAN_AI 2026-04-24) and "233 tools" (dispatch
brief). The single source of truth is the registry walk at runtime
— do not quote a static number in marketing copy without re-counting.
Mastra hyphen↔underscore rule. Tool id: 'show-modal' is exposed
to the LLM as show_modal. Mixed forms cause silent dispatch
failures. The frontend action type uses the underscore form (e.g.
show_modal, show_notification, update_info_container).
get_clinical_notes is a hallucination. Real tool: list-clinical-notes.
open_panel / close_panel / render_component are unimplemented
— the LLM may emit them, the frontend dispatcher logs
handler:dropped. Either implement them, or strip them from any
agent prompts that reference them.
clear-info-containers does NOT publish SSE — the DB change is
invisible to the frontend until the next page mount. Track as a
known defect; do not write a follow-up tool that depends on the
frontend learning the table was cleared.
Mastra review checklist applies to every new tool: ragDescription,
ragKeywords (EN + DE), mutating flag, outputInstructions ("NEVER
show UUIDs" when output contains IDs), error result includes
suggestion field. See ~/.claude/rules/shared/review-checklists/mastra.md.
Composite tools cannot call other tools. Mastra tools cannot
invoke each other from execute() without a registry shim — leave
composite logic in the NestJS service path
([[ddx-mastra-specialist_memory.md]]).
ragKeywords must distinguish siblings. Identical
ragDescription + ragKeywords produces identical embeddings;
retrieval picks the wrong tool. Add anti-synonyms ("NOT encounter",
"NOT fhir-encounter") and a canonical TOOL_ID suffix when two tools
serve adjacent intents — pitfall confirmed in commit f6eef8a18.
Related Topics
[[tucan-assistant]] — orchestration entry point that dispatches tools.
[[tucan-dispatcher]] — the per-stage state machine that calls
DispatcherStage which finally invokes Mastra Agent.generate.
[[tucan-rag-tools]] — Qdrant-backed tool discovery (build-time only,
not per-turn).
[[tucan-intent-filtering]] — intent-classifier that narrows the agent
before per-agent category filtering.
[[agent-templates]] — agent template factory consumed by
agent-type.registry.
[[tucan-context-builder]] — context.services injection (the DI
bridge from NestJS into Mastra tool execute).