synaptiai/agent-capability-standard/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

Inputs not listed here are outside the capability's contract: a workflow step that binds them gets W604 (STANDARD v1.1 §5.5).

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