Tools overview

The assistant’s “tools” are the things the LLM can do beyond chatting. Each connector contributes one or more tools that the agent picks from on every turn.

Three connectors today

Connector	Tool count	Purpose	Detail page
`mysql`	20	Read business data — curated queries + saved reports + generic SQL	MySQL / DB
`docs`	3	List, read, and full-text-search the docs site	—
`code`	3	List, read, and search across the monorepo	—

(Phase 4 will add Sentry, GitHub, and Jira connectors as MCP sidecars; this page will grow as they land.)

How the LLM picks a tool

On every turn, the Anthropic API receives the conversation plus the full list of registered tools. The model chooses to call zero or more of them based on the user’s question, then the assistant feeds the tool result back as another user turn and asks the model to continue. Loop ends when the model returns a final text-only response with no tool calls.

What gets logged

Every tool invocation writes a row to tunnelflight_assistant.assistant_audit_log (table schema in /tech/db-schema). Columns capture: the tool name, the inputs (as JSON, with sensitive keys scrubbed), the result (success / failed / rejected), and a target reference like a member id or report id where applicable. Audit-log rows are the canonical “what did the assistant do” record for compliance review.

Where tools live in the code


assistant/src/infrastructure/connectors/
├── docs/                            # docs_list, docs_read, docs_search
├── code/                            # code_list, code_read, code_search
└── mysql/
    ├── MysqlConnector.ts            # generic: mysql_run_read_sql, mysql_describe_table
    └── curated/                     # 18 hand-crafted business-question tools
        ├── DashboardHeadlinesTool.ts
        ├── RevenueSummaryTool.ts
        ├── RegistrationsInPeriodTool.ts
        ├── …                         (full list on the MySQL page)
        ├── ListSavedReportsTool.ts   # admin's catalog of SQL reports
        ├── DescribeSavedReportTool.ts
        └── RunSavedReportTool.ts

Adding a new tool

Tools are defined with defineTool({ name, description, inputSchema, execute }) from @/domain/agent/defineTool. The schema is a Zod schema, which is serialised to JSON Schema for Anthropic’s API. The connector’s register(registry) method adds each tool to the lifecycle registry. The lifecycle then publishes the full set to the agent loop.

For curated MySQL tools specifically, the convention is one tool per file under curated/, named <Question>Tool.ts, exporting a single defineTool({…}) call. Test fixtures live in savedReports.test.ts plus per-tool tests where the SQL has non-trivial parameter handling.