Tool reference
Lodgey has 16 custom tools plus full Bash and Python access. You don’t call these tools directly — Lodgey uses them automatically. But understanding what they do helps you interpret what the agent is doing and give better prompts.
Interaction tools
Section titled “Interaction tools”ask_user_question
Section titled “ask_user_question”Presents a structured question with clickable option cards. This is Lodgey’s primary interaction tool — you’ll see it at every decision point.
When it fires: Goal discovery, steering, clarification, data gathering, decision points.
What you see: A question with 2-5 clickable options, plus an “Other” text field for custom answers.
announce_plan
Section titled “announce_plan”Registers a step-by-step plan displayed as a live progress tracker. Updated as Lodgey works through each step.
When it fires: Before any multi-step task (processing multiple documents, running an investigation, building a full tax picture).
What you see: A compact progress bar with labelled steps (pending → running → done).
Data capture tools
Section titled “Data capture tools”update_situation
Section titled “update_situation”Persists tax facts to the project database. Called every time Lodgey learns something new.
What it stores: Taxpayer details, properties (addresses, types, values, loans), employers (names, ABNs, gross pay, tax withheld), rental income/deductions, capital gains, work deductions, totals.
file_evidence
Section titled “file_evidence”Records a single evidence item linked to a document or conversation.
What it stores: Category, description, amount, status (confirmed/estimated/needed), document reference.
Document tools
Section titled “Document tools”process_document
Section titled “process_document”Reads and extracts content from an uploaded file (PDF, image, CSV, Excel).
When it fires: After you upload a document. Returns raw extracted text that Lodgey then interprets.
search_email
Section titled “search_email”Searches your connected Gmail for tax documents. Uses Gmail search syntax with targeted queries.
When it fires: When Lodgey proactively looks for missing documents, or when you ask it to search your email.
Requires: Gmail connected via the side panel.
Analysis tools
Section titled “Analysis tools”analyze_gaps
Section titled “analyze_gaps”Cross-references all evidence against ATO requirements. Returns confirmed, estimated, and missing items per category.
When it fires: After processing documents, after situation updates, or when you ask “what’s missing?“
get_status
Section titled “get_status”Fetches the current progress summary. Results populate the Live Report dashboard.
When it fires: When you ask for status/progress, or periodically during long sessions.
cross_check
Section titled “cross_check”Full audit of the evidence pack. Checks:
- Every uploaded document has been processed and filed
- Every evidence item references a valid document
- Every property/employer has required evidence categories
- Flags estimates that could be confirmed
When it fires: After bulk uploads, before report generation, when you ask “audit my pack” or “is everything complete?”
Memory tools
Section titled “Memory tools”update_memory
Section titled “update_memory”Saves key findings, decisions, and context to the project’s long-term memory. Structured with markdown headings and merged by section.
When it fires: After important discoveries, corrections, or at the end of a session.
read_memory
Section titled “read_memory”Reads the project’s long-term memory from previous sessions.
When it fires: At the start of a new session to restore context.
Workbook tools
Section titled “Workbook tools”update_workbook
Section titled “update_workbook”Creates, updates, and styles the Live Report spreadsheet. Handles both data and formatting through structured actions:
create_sheet— new tab with headers and dataupdate_cells— modify cells or append rowsstyle_range— fonts, colours, borders, number formats, mergeset_column_widths— column sizingfreeze_panes— freeze header rowsdelete_sheet/rename_sheet/clear_sheet
When it fires: After processing documents, filing evidence, or when you ask Lodgey to update or format the report.
import_excel
Section titled “import_excel”Imports a user-uploaded .xlsx file into the workbook. Only used for imports — not for formatting.
Report tools
Section titled “Report tools”generate_report
Section titled “generate_report”Generates a downloadable Excel report. Returns a download link rendered as a button in chat.
When it fires: When you ask to export, download, or get a spreadsheet.
Interactive tools
Section titled “Interactive tools”render_artifact
Section titled “render_artifact”Renders an interactive calculator widget in the chat. Six available types: cgt_calculator, tax_planning, negative_gearing, forecast, portfolio_kpis, payg_variation.
When it fires: When you ask “what if”, “how much”, “show me”, or request a specific calculator.
Built-in tools (sandbox)
Section titled “Built-in tools (sandbox)”In addition to custom tools, Lodgey has access to a sandboxed environment with:
| Tool | What it does |
|---|---|
| Bash | Run shell commands — grep, jq, awk, sort, bc for calculations |
| Python | Execute scripts for complex tax calculations, data reconciliation |
| Read/Write | Read and write files in the sandbox |
| Web search | Look up ATO thresholds, ABN verification, company details |
| Web fetch | Retrieve content from URLs |
Lodgey uses the lightest tool that gets the job done. Structured tools for data persistence, Bash for quick calculations, Python for complex multi-step arithmetic.