Use Havilo research when a question needs judgment across your network, such as finding investors who fit a startup. Give the client the goal and constraints, review the proposed plan, then ask it to run.
Every tool here requires AI_FEATURE_ACCESS. Only ai_runs_start takes a reach: its xray and global_search modes also require VIEW_GLOBAL_NETWORK. Understanding, planning, and ai_run reason within the connected workspace, because reach is the user's setting and an MCP connection carries the narrowest one.
Understand
ai_understand tests how Havilo interprets a natural-language question. It returns the structured understanding and diagnostics without planning or executing work.
Use it when the request is ambiguous, when entity types or named Entities may resolve in more than one way, or when you want to refine the question before doing more work.
Plan
ai_plan returns the proposed work and a plan_hash for running it later. It saves the plan without executing it. Both ai_understand and ai_plan are read-only tools; planning does not require write approval.
Review:
- the interpreted goal;
- resolved workspace objects;
- the ordered work in the plan;
- warnings or assumptions;
- the requested model.
If the plan misses your intent or asks for clarification, refine the request and plan again.
Reviewed run
Two tools start a reviewed plan, and the difference is only how the plan is named.
ai_run names it by the 16-character plan_hash from ai_plan. Havilo saves the complete reviewed plan and execution settings before returning that handle. The same user can execute it in the same workspace after a server restart. It enqueues immediately because the plan was already reviewed.
ai_runs_start takes the whole execution plan object instead. Use it for a plan supplied independently, or pass the execution_plan returned by ai_plan. It validates and previews by default; repeat the reviewed input with a stable idempotency_key and apply: true to enqueue.
Both return a job ID. Follow it with jobs_get, then inspect the saved results when the job completes.