inquire

Intent

Generate targeted clarifying questions when a user request is ambiguous or underspecified, enabling the agent to gather missing information before committing to an action.

Success criteria:

• •Questions target specific missing parameters or ambiguous interpretations
• •Each question provides bounded answer options when applicable
• •Confidence score reflects actual ambiguity level
• •Evidence anchors reference the specific ambiguous elements

Compatible schemas:

• •schemas/output_schema.yaml
• •reference/capability_ontology.yaml#/inquire

Inputs

Procedure

1. •

   Analyze the input: Examine the ambiguous_input for completeness

   • •Identify required parameters for the likely intended action
   • •Check for conflicting interpretations
   • •Note any implicit assumptions that need validation
2. •

   Categorize ambiguity types: Classify what's unclear

   • •Missing parameters: Required information not provided
   • •Conflicting interpretations: Multiple valid ways to interpret the request
   • •Constraint gaps: Boundaries or limits not specified
   • •Domain uncertainty: Unclear which domain or scope applies
3. •

   Generate clarifying questions: For each ambiguity, formulate a question

   • •Target specific missing information
   • •Provide bounded options when possible (2-4 choices)
   • •Frame questions to elicit actionable answers
   • •Prioritize questions by impact on execution
4. •

   Ground claims: Attach evidence anchors to the ambiguity analysis

   • •Reference specific phrases or words that are ambiguous
   • •Link to context that informed the interpretation
   • •Format: input:phrase, context:field, or inference:reason
5. •

   Format output: Structure results according to the output contract

6. •

   Assess confidence: Rate how confident you are that clarification is needed

   • •High confidence (0.8-1.0): Clear missing required parameters
   • •Medium confidence (0.5-0.8): Ambiguous but could proceed with assumptions
   • •Low confidence (0.0-0.5): Probably clear enough, clarification optional

Output Contract

Return a structured object:

questions:
  - question: "Which database should this operation target?"
    parameter: "target_database"
    options: ["production", "staging", "development"]
  - question: "Should this include archived records?"
    parameter: "include_archived"
    options: ["yes", "no"]
ambiguity_analysis:
  missing_parameters: ["target_database", "date_range"]
  conflicting_interpretations:
    - interpretation: "Query all users"
      confidence: 0.6
    - interpretation: "Query only active users"
      confidence: 0.4
  confidence_without_clarification: 0.3
confidence: 0.85  # How confident we are that clarification is needed
evidence_anchors: ["input:users", "context:previous_query_was_active_only"]
assumptions: []  # No assumptions made - we're asking for clarification

Field Definitions

Examples

Example 1: Ambiguous API Request

Input:

ambiguous_input: "Update the user's email"
context:
  recent_topic: "user management"
  available_users: 150
max_questions: 3

Output:

questions:
  - question: "Which user's email should be updated?"
    parameter: "user_id"
    options: []  # Open-ended - too many users to list
  - question: "What should the new email address be?"
    parameter: "new_email"
    options: []
  - question: "Should this send a verification email to the new address?"
    parameter: "send_verification"
    options: ["yes", "no", "only if production"]
ambiguity_analysis:
  missing_parameters: ["user_id", "new_email"]
  conflicting_interpretations: []
  confidence_without_clarification: 0.1
confidence: 0.95
evidence_anchors: ["input:the user's", "input:email"]
assumptions: []

Evidence pattern: The phrase "the user's" indicates a specific user is intended but not identified. "email" is ambiguous - could mean view, update, or verify.

Example 2: Multiple Valid Interpretations

Input:

ambiguous_input: "Show me the report"
context:
  available_reports: ["sales", "inventory", "user_activity"]
  last_viewed_report: "sales"
max_questions: 2

Output:

questions:
  - question: "Which report would you like to see?"
    parameter: "report_type"
    options: ["sales", "inventory", "user_activity"]
  - question: "For what time period?"
    parameter: "date_range"
    options: ["today", "this week", "this month", "custom range"]
ambiguity_analysis:
  missing_parameters: ["report_type", "date_range"]
  conflicting_interpretations:
    - interpretation: "Show sales report (last viewed)"
      confidence: 0.5
    - interpretation: "Show most recently generated report"
      confidence: 0.3
    - interpretation: "Show all available reports"
      confidence: 0.2
  confidence_without_clarification: 0.5
confidence: 0.7
evidence_anchors: ["input:the report", "context:available_reports:3", "context:last_viewed:sales"]
assumptions: []

Evidence pattern: "the report" implies a specific report but context shows 3 options. Recent history (sales) provides a weak signal.

Verification

• • Output contains at least one question when confidence > 0.5
• • Each question has a non-empty parameter field
• • Options array is provided for bounded-choice questions
• • Evidence anchors reference specific input elements
• • Confidence is justified by ambiguity analysis

Verification tools: None beyond allowed tools

Safety Constraints

• •mutation: false
• •requires_checkpoint: false
• •requires_approval: false
• •risk: low

Capability-specific rules:

• •Do not make assumptions - the purpose is to ask, not to guess
• •Limit questions to max_questions to avoid overwhelming users
• •If confidence < 0.3, consider returning empty questions (input may be clear enough)
• •Never include sensitive data in question options

Composition Patterns

Commonly follows:

• •critique - After identifying issues with a request, inquire resolves them
• •receive - After receiving a new request that needs clarification

Commonly precedes:

• •receive - After inquiring, wait for user's clarification response
• •integrate - Merge clarification into the original request
• •plan - Once clarified, proceed to planning

Anti-patterns:

• •Never use inquire after execute - clarify BEFORE acting
• •Avoid chaining multiple inquire calls - combine questions into one request
• •Don't use with mutate in the same step - inquire is read-only

Workflow references:

• •See reference/workflow_catalog.yaml#clarify_intent for the complete clarification workflow