start_consultation
Start a new strategic consultation, debate, or research task.
This is the PRIMARY entry point for any analysis. Use this tool to:
- Get a quick second opinion ('quick' mode).
- Run a full multi-perspective debate ('standard' mode).
- Conduct deep research and analysis ('deep' mode).
- Gather evidence on a topic ('research' mode).
USE THIS WHEN:
- User asks for strategic advice, analysis, or a second opinion
- User wants pros/cons on a decision or idea
- User says "debate this", "analyze this", "what do you think about..."
- User needs help evaluating options or trade-offs
- User wants research on a topic before making a decision
DO NOT USE FOR:
- Simple factual questions (use your own knowledge)
- Non-strategic queries like definitions or explanations
- Tasks that don't involve decision-making or evaluation
Args:
question: The strategic question, topic, or claim to analyze.
mode: The depth/type of analysis:
- 'quick': fast 30s pros/cons analysis (use for "quick take", "quick check", or very simple questions).
- 'standard': rigorous debate and detailed analysis (use for "deliberate", "debate", "consult"). This is the DEFAULT for most strategic questions.
- 'deep': full pipeline with web research (use for "analyze", "research project", "deep dive", or when external information is needed).
- 'research': only gather evidence without debate (use for "find papers", "search web").
sources: Optional list of sources (documents, context) to use. If omitted, internal knowledge and context will be used.
context: Background context or situation description to inform the analysis.
analysis_id: Optional custom ID for tracking.
counsel_id: Optional ID of a specific counsel/persona configuration to use.
presentation_format: Desired output format (e.g., 'brief', 'memo', 'json').
Returns:
Dict containing the 'analysis_id' needed for status polling and results.
get_consultation_status
Check the progress/status of a running analysis.
USE THIS WHEN:
- You called start_consultation and need to check if it's done
- User asks "is my analysis ready?" or "what's the status?"
- Polling for completion before calling get_consultation_report
- Checking if a running analysis needs user input (pauses/steering)
WORKFLOW: Call this after start_consultation, repeat until status='completed',
then call get_consultation_report for final results.
Args:
analysis_id: The ID returned by `start_consultation`.
include_intervention_status: If True, checks if user input is needed (pauses/steering).
include_transcript: If True, includes full debate transcript (slower).
Use False (default) for fast polling, True when user wants progress details.
Returns:
Dict with 'status' (running/completed/failed), 'phase', and 'progress'.
get_consultation_report
Retrieve the final results, decision card, and artifacts.
USE THIS WHEN:
- get_consultation_status shows status='completed'
- User asks "what's the result?" or "show me the analysis"
- You need to present the final recommendation to the user
- Fetching the decision card, pros/cons, or executive summary
DO NOT USE IF:
- Analysis is still running (check status first)
- Analysis failed (status='failed' - handle error instead)
Args:
analysis_id: The ID of the completed analysis.
include_tensions: Whether to include the 'Crux Registry' (key tensions/trade-offs).
presentation_format: Format to render results (e.g., 'brief', 'detailed', 'memo').
ctx: Request context to read client hints (e.g. locale).
Returns:
The final analysis output, including recommendation, rationale, and key factors.
manage_consultation
Intervene in or modify a running analysis.
USE THIS WHEN:
- User wants to pause, stop, or cancel a running analysis
- User says "focus more on X" or "consider Y" mid-analysis (use 'steer')
- User wants to add new evidence during an ongoing debate
- User wants to edit the identified trade-offs or tensions
DO NOT USE FOR:
- Starting a new analysis (use start_consultation)
- Checking status (use get_consultation_status)
- Getting results (use get_consultation_report)
Args:
analysis_id: The analysis to manage.
action: The specific intervention to perform.
payload: Data required for the action:
- for 'steer': string guidance ("Focus more on X").
- for 'add_sources': list of source objects.
- for 'pause'/'abort': optional reason string.
Returns:
Success status of the intervention.
list_resources
List available resources (past analyses, configs, sessions).
USE THIS WHEN:
- User asks "show my past analyses" or "list my debates"
- User wants to see available counsel configurations
- User needs to find a previous analysis to reference
- Browsing available templates or persona configurations
Args:
type: What to list:
- 'consultations': Past debates/analyses.
- 'counsels': Available persona configurations.
- 'advisor_sessions': Active advisor chat sessions.
- 'templates': Pre-built counsel templates.
limit: Max items to return.
offset: Pagination start index.
Returns:
List of resource items.
sharpen_question
Refine and clarify a strategic question BEFORE analysis.
USE THIS WHEN:
- User's question is vague, broad, or unclear
- Question could mean multiple things
- You want to ensure high-quality analysis by improving the question first
- User says "help me frame this" or "what's the right question to ask?"
DO NOT USE FOR:
- Questions that are already specific and well-defined
- When user explicitly says "analyze this exact question"
- Simple queries that don't need refinement
WORKFLOW: Call this before start_consultation if the question seems unclear.
Use the refined question in start_consultation for better results.
Args:
question: The initial (potentially vague) question.
context: Context about the user's situation.
auto_select: If True, automatically pick the best refinement (good for automation).
Returns:
'selected_question' (the refined version) and 'enhanced_questions' (options).