Query Clarifier Copilot

An agent that analyzes research queries for ambiguity, scope, and actionability before research begins, transforming vague or broad questions into clear, specific, research-ready queries that produce higher-quality results.

When to Use This Agent

Choose Query Clarifier when:

• Refining ambiguous research questions before starting investigation
• Scoping broad topics into specific, answerable research objectives
• Identifying hidden assumptions in research requests
• Breaking complex questions into researchable sub-questions
• Ensuring research queries are specific enough to produce actionable findings

Consider alternatives when:

• Research query is already specific and well-scoped (proceed directly to research)
• Writing research reports from existing findings (use a report generator)
• Conducting the actual research (use a research analyst agent)

Quick Start

Copy
# .claude/agents/query-clarifier-copilot.yml
name: Query Clarifier
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
prompt: |
  You are a query clarification expert. Analyze research queries
  for ambiguity, scope, specificity, and actionability. Transform
  vague questions into clear, researchable queries. Identify
  assumptions, constraints, and sub-questions that need addressing.

Example invocation:

Copy
claude --agent query-clarifier-copilot "Clarify this research
  request: 'How is AI changing healthcare?' - identify ambiguities,
  suggest specific research angles, and produce a refined query."

Core Concepts

Query Analysis Dimensions

Dimension	Question to Ask	Example Issue
Specificity	What exactly is being asked?	"AI" could mean ML, generative AI, robotics
Scope	How broad or narrow is the topic?	"Healthcare" spans thousands of sub-fields
Timeframe	What period is relevant?	Last year vs last decade
Geography	Which markets or regions?	US, global, specific country
Perspective	Whose viewpoint matters?	Patients, providers, insurers, regulators
Actionability	What decision does this inform?	Strategic, tactical, or informational

Refinement Process

Original Query: "How is AI changing healthcare?"
        ↓
Ambiguity Analysis:
  - "AI" → Which AI? ML diagnostics? LLM clinical notes? Robotic surgery?
  - "healthcare" → Which sector? Hospitals? Pharma? Insurance?
  - "changing" → Adoption rates? Outcomes? Costs? Workflows?
        ↓
Refined Query: "What is the current adoption rate of FDA-approved
  ML diagnostic tools in US hospital radiology departments, and
  what measurable impact have they had on diagnostic accuracy
  and radiologist workflow efficiency since 2021?"

Sub-Question Decomposition

Copy
## Original: "Should we adopt microservices?"

### Sub-Questions:
1. What are our current system's scalability bottlenecks?
2. What is our team's experience with distributed systems?
3. What are the operational costs of running microservices vs monolith?
4. Which services would benefit most from independent deployment?
5. What migration path minimizes risk and disruption?

Configuration

Parameter	Description	Default
max_sub_questions	Maximum sub-questions to generate	5
ambiguity_threshold	Sensitivity for flagging vagueness	Medium
suggest_constraints	Propose scope constraints	true
identify_assumptions	Flag hidden assumptions	true
output_format	Refined query format	Structured markdown
interactive	Ask follow-up questions	true

Best Practices

1. Flag every ambiguous term, not just the obvious ones. Words like "performance," "scalable," "modern," and "best" mean different things to different people. "Improve performance" could mean faster response time, higher throughput, lower resource usage, or better user experience metrics. Each interpretation leads to fundamentally different research directions. Make the requester choose which interpretation they mean.

2. Always ask what decision the research will inform. Understanding the downstream decision transforms the research scope. "How is AI changing healthcare?" for a venture capital investment decision needs market size and growth projections. The same question for a hospital CTO needs vendor comparison and implementation case studies. The decision context determines what research is actually useful.

3. Propose scope constraints rather than leaving them open. Instead of asking "how broad should this be?", propose: "I suggest limiting to FDA-approved diagnostic AI tools in US hospital radiology departments since 2021. Should I broaden or narrow this scope?" Proposed constraints give the requester something concrete to react to, which is easier than defining scope from scratch.

4. Decompose complex queries into researchable sub-questions. A question like "should we adopt microservices?" is really five separate questions about current bottlenecks, team capabilities, operational costs, migration risk, and specific service candidates. Each sub-question has different research methods and sources. Decomposition prevents the research from being simultaneously too broad and too shallow.

5. Identify and state hidden assumptions explicitly. "What's the best cloud provider?" assumes cloud is the right choice, that one provider is better than multi-cloud, and that "best" means the same thing for this team as for others. Surfacing assumptions prevents research that answers the wrong question. Some assumptions may be valid; others may need investigation before the main research begins.

Common Issues

Requester pushes back on clarification as unnecessary delay. Frame clarification as time-saving: "Spending 10 minutes refining the query now will save 2 hours of irrelevant research results." Show an example of how a vague query produces unfocused research versus how a refined query produces targeted, actionable findings. The investment in clarification pays for itself in research quality.

Refined query is so specific that it misses important context. Balance specificity with completeness. After narrowing the query, add a "context scan" step: a quick survey of adjacent topics to catch relevant information outside the narrow scope. The refined query guides the deep research; the context scan ensures nothing critical is excluded by over-scoping.

Multiple valid interpretations exist and the requester wants all of them. When a query legitimately has multiple valid angles, create separate refined queries for each interpretation rather than one catch-all query. Research each independently and let the requester prioritize which to investigate first. Trying to research all interpretations simultaneously produces shallow coverage of everything and deep coverage of nothing.