Query best practices for Microsoft Web IQ

  • Start with Auto. Let Web IQ select relevant types of results. Choose a specialized API when you specifically need web pages, news articles, images, or videos, or want to manage searches yourself.
  • With Auto, keep the complete task together. Include related questions and any facts that must be found before answering another part.
  • When managing searches yourself, give each query a clear target. Include names and details that change the answer, not the full conversation or answer-formatting instructions.

This guide applies to AI agents and other applications that use Microsoft Web IQ. It uses "your agent" for the component that sends queries and uses the results.

Both Auto and specialized search APIs accept natural-language questions or keywords. Choose the wording that clearly describes what you need to find. Auto returns evidence with supporting citations, not necessarily a finished answer; your agent uses that evidence to compose its response.

Start with Auto or choose a specialized search API

Use Auto as the starting point when you want Web IQ to select relevant types of results, such as web, news, or weather. You don't need to choose a separate API for each part of the question.

Choose a specialized API when you need a specific result type or want your agent to control each search and decide what to look up next.

What you need Starting point Example query
Let Web IQ choose relevant types of results for the complete question. Auto What is the weather in Seattle this Saturday, and what is the latest news about Pike Place Market?
Retrieve web pages, or control each step in a series of web lookups. Web Search Microsoft FY2026 Q1 revenue
Retrieve news articles about an event or development. News Search latest Adobe Photoshop feature announcements
Find images of a subject. Image Search Microsoft Surface Pro 12 platinum
Find videos, such as a recording or demonstration. Video Search official Microsoft Build 2026 keynote video

These are starting points, not exclusive uses: Auto can also retrieve evidence for a simple web question or a request for news.

Note

Auto and Auto Advanced are generally available to every Web IQ AppID from November 17, 2026. See the Auto reference.

Choose an Auto mode

After choosing Auto, select a mode based on your task:

Mode When to start here
Auto (mode: lite, the default) Speed is the priority. Use it as the default starting point for straightforward questions and related facts about one topic.
Auto Advanced (mode: advanced) Comprehensiveness is the priority. Evaluate it for research that needs evidence from several documents or requires finding one fact before looking up another.

Omitting mode defaults to lite; Auto doesn't automatically choose between the two modes. Neither mode guarantees complete coverage. See the Auto parameters.

Construct Auto queries around the complete task

Describe what you need to find, including how the parts of the question relate. Remove greetings, the full chat history, and instructions about formatting the final answer.

Ask for different types of information together

For a task that combines weather, restaurants, and news, keep those needs in one Auto query:

{
  "query": "What is the weather in Seattle this Saturday, which highly rated restaurants are near Pike Place Market, and what is the latest news about Pike Place Market?",
  "mode": "lite"
}

Auto can select different types of results for the task without your agent making separate weather, restaurant, and news calls. The types returned can vary. Check that the evidence covers each part, including the intended Saturday and the dates of news articles.

Preserve dependent questions

Some questions require identifying an entity before retrieving a document about it. Keep both steps in the Auto query, including the requested document type:

{
  "query": "Which U.S. president signed the act establishing NASA, and what did he warn about science and technology in his farewell address? Find the official government sources for both.",
  "mode": "advanced"
}

This request connects two evidence needs: identify the president from NASA's account of its founding, then retrieve his farewell address and its science-and-technology warning from the National Archives transcript.

With Web Search, your agent can find and verify the president, then search for that president's farewell address. A single Web Search might cover both; check that the evidence includes the address's science-and-technology warning, not just NASA's founding.

For several facts about one person, send one coherent question:

{
  "query": "What are Bill Gates's age, education, and business background?",
  "mode": "lite"
}

For a comparison, preserve the subject, metric, and period:

Compare Microsoft's annual revenue from 2012 through 2020.

Don't rewrite this as Microsoft revenue: doing so loses the comparison and time range.

Write focused queries for specialized search APIs

When you choose a specialized API, describe the information or media you want to retrieve. Remove instructions such as "return JSON," "be concise," and "include citations"; those belong in the prompt that generates the answer.

API Example query What to preserve
Web Search What was Microsoft's revenue in FY2026 Q1? The subject, metric, and reporting period.
News Search latest Adobe Photoshop feature announcements The subject and the event or development. Check article dates and relevance.
Image Search Microsoft Surface Pro 12 platinum The product, model, and relevant appearance.
Video Search official Microsoft Build 2026 keynote video Whether you need an official recording, demonstration, tutorial, interview, or trailer.

Split searches when your agent manages the steps

User request:

What were Microsoft's Q1 earnings, and what new Surface products were announced?

With Auto, you can keep this request together. If you choose to have your agent manage separate Web searches, give each query a focused target. For example, if the fiscal year and announcement period are already known:

Microsoft FY2026 Q1 earnings
Microsoft Surface product announcements 2026

These queries don't depend on each other's results, so your agent can execute them independently. Splitting gives your agent control over each search; it doesn't mean a single Web Search can never return evidence about both subjects. Don't select a fiscal year or announcement period that wasn't established by the request or known context.

Similarly, your agent might compare results from Microsoft latest quarterly revenue and Apple Inc. latest quarterly revenue. Check the reported periods before comparing the numbers: "latest" doesn't establish that both companies report the same period.

Apply these query tips to any search API

Resolve shorthand from known context

If a user asks "How old is Satya?" and the conversation establishes that they mean Satya Nadella, use Satya Nadella age or How old is Satya Nadella?

Don't expand an ambiguous name without that context. Ask for clarification when different interpretations would produce different results.

Keep queries within the documented 1,000-character limit. Don't fill that budget with the full conversation or system prompt. See Query behavior and result quality.

Include names and details that change the answer

Preserve names, versions, places, and time periods when they change the answer. The following examples assume those details are already known from the user or trusted context.

Need Less effective More specific
Person Satya Satya Nadella education
Company Apple Apple Inc. earnings
Location Portland election results Portland, Maine election results November 2026
Product Surface problems Microsoft Surface Pro 12 reported battery issues
Version .NET changes What's new in .NET 10 compared with .NET 9?

Don't guess which person, Portland, product version, or time period the user means. A rewrite should make known context explicit, not manufacture it.

Distinguish freshness from historical time constraints

Intent Example query
Latest developments latest Microsoft AI acquisitions
Recent coverage of a topic recent Adobe Photoshop feature announcements
A historical month Microsoft AI acquisitions March 2026
A particular event and period Microsoft Build announcements May 2026

Use only as much date precision as the task needs. If the request asks about a month, don't invent an exact day. If it explicitly asks about a day, preserve that constraint.

Dates in a query express the retrieval target; they aren't a strict publication-date filter. Web Search doesn't expose a date-range request filter. For current news coverage, use News Search. See Web Search date filtering.

Use site restrictions intentionally

Web Search and Auto support site: and -site:. Use them only when a source restriction is part of the request or your source policy:

Microsoft Surface Pro 12 support site:support.microsoft.com
Adobe Photoshop feature updates -site:example.com

Don't add a restriction merely because a site seems likely to have the answer. It can exclude useful evidence and reduce relevance. Validate returned source URLs when source restrictions matter; don't treat query text as an authorization control. See the Web Search query parameter.

Use documented parameters to complement the query

Keep the subject and information need in query. Use other parameters for supported retrieval controls, rather than adding phrases such as "ten results" or "wide images" to the query.

Parameters Applies to Guidance and reference
responseFilter Auto Omit it to allow all supported types of results. ["web", "news"] allows only web and news, but neither is guaranteed to appear. Use it to restrict result types, not to choose a separate endpoint for each question. See the Auto response-filter FAQ.
language, region Auto and specialized search APIs Use supported two-letter codes. The query's own language remains important; these parameters don't replace a clearly worded query. See Language, region, and location.
location Auto, Web Search, News Search Provide geographic context in lat:<latitude>;long:<longitude> format when relevant. Still name a place in the query when it identifies the subject. See the Auto parameters.
contentFormat, maxLength, maxResults Web Search and News Search For grounding, start with contentFormat: "passage", maxLength: 3000, and maxResults: 10. maxLength is characters per result, not tokens. See Passages and content formats.
aspectRatio, imageSize Image Search Use values such as "wide" and "large" to filter images without obscuring the subject in query. See the Image Search parameters.
duration Video Search Use "short", "medium", or "long" for a duration requirement. See the Video Search parameters.

For example, the following Web Search request body describes precise evidence and requests query-relevant passages:

{
  "query": "Microsoft FY2026 Q1 cloud revenue and year-over-year growth",
  "contentFormat": "passage",
  "maxLength": 3000,
  "maxResults": 10
}

The same principle applies to image filtering:

{
  "query": "Microsoft Surface Pro 12 platinum",
  "aspectRatio": "wide",
  "imageSize": "large"
}

These settings are endpoint-specific. Don't send Web Search's contentFormat, maxLength, or maxResults to Auto, or Image Search filters to Web Search.

Reference