> For the complete user guide index, see [llms.txt](https://portraitresearch.com/documentation/llms.txt).

# Build a screen with the AI Assistant

[Canonical page](https://portraitresearch.com/documentation/screening/build-with-ai-assistant/)

## Applicability

- **Task:** Build a screen from explicit natural-language criteria
- **Access:** Portrait account; Normal usage and concurrency limits may apply; source entitlements can apply
- **Audience:** Portrait users discovering companies with explicit criteria
- **Surfaces:** web; ios
- **Workflow status:** current
- **Availability:** Production
- **Content type:** how-to
- **Last reviewed:** 2026-09-22

Describe the companies you want to find and the **AI Assistant** turns your criteria into screening filters. Refine the conditions, review the filter list, and run the screen from the web or the Portrait iOS app.

## Before you start

Sign in to Portrait and define the company universe, period, and condition you want to investigate. Review [Settings → Usage](https://portraitresearch.com/documentation/more/usage/) in the web app before a large run. A Project is optional; source access and usage limits apply on both surfaces.


## Build a screen on the web

Open **Screening** in the web app and select **New screening**.

The builder has two halves. On the left is the **AI Assistant** conversation pane; on the right is the **Screening filters** pane that holds your screen.

1. Describe the companies you want to find in the message box, for example: *"US-headquartered companies whose filings from the last 12 months report a change of CEO."*
2. The Assistant translates your description into quantitative constraints, qualitative conditions, and supported universe filters.
3. In the **new screen** builder, valid additions and updates apply directly to the Screening filters pane. Review that pane after each response; you do not need to accept each suggestion first.
4. When **editing an existing screen**, use **Add** or **Update filter** to apply a suggestion, or **Dismiss** or **Keep current** to leave it out. Requested removals can apply immediately when the affected filter has not changed since the request. Inspect the full filter list after asking the Assistant to change or remove a condition.
5. Edit or remove unwanted filters before choosing **Run screen**. Generating filters does not itself run the screen.

## Build or edit a screen on iOS

1. Open **Screening** and tap **New screen**. To edit a saved screen, open it, then open **Filters → Edit filters**. Editing requires edit access to that screen.
2. Describe the companies you want to find in the conversation.
3. Review the suggestions. Tap **Add** for a new filter or **Update filter** for a proposed change; use **Dismiss** or **Keep current** to leave a suggestion out. On iOS, additions and updates need confirmation even when creating a new screen.
4. Open **Filters** or tap **Review** to inspect the confirmed filters. Tap a filter to start a message asking for a change. Mobile filter editing uses the conversation; the manual expression and date controls are in the web app.
5. Review **Email on completion** in the Filters panel; it can notify everyone with access to the screen. Tap **Run screen**, then inspect the run's status and company results.

Accepted changes to an existing screen are saved as you edit. Requested removals can apply immediately; inspect the filter list after each response and use **Undo** when needed. A new screen is saved when you choose **Run screen**; if the run is refused, the saved screen can remain without a new run.

## Writing a good description

Use clear, specific instructions that can be translated into observable filter conditions.

* Write in full sentences with tangible details, the way you would instruct a new member of your team.
* Combine quantitative and qualitative criteria in one description, then verify how the Assistant splits them into filter types.
* Lead with the qualitative condition, then add or tighten numeric constraints during review.
* State company-size restrictions explicitly. For a $2 billion minimum market capitalisation, request it and check that the expression uses `market_cap > 2000000000`.

Review the **Screening filters** pane on the web or the **Filters** panel on iOS. A screen supports at most three qualitative filters; remove or replace one before adding a fourth. Running a screen consumes Normal included usage and is subject to budget and concurrency limits. See [Standard quantitative filters](https://portraitresearch.com/documentation/screening/standard-quantitative-filters/) and [Qualitative document filters](https://portraitresearch.com/documentation/screening/portrait-textual-reasoning/) for filter definitions and web configuration controls.

## Verify and troubleshoot

- Confirm the universe, each metric, operator, threshold, period, and qualitative query before running.
- Open the run and check its status and company results. An empty completed result means no company matched that run; it is different from a failed or still-running screen.
- Inspect company-level evidence for a sample of matches and non-matches.
- If the Assistant adds an unwanted constraint, edit or remove it and review the remaining filters again.
- If the screen already has three qualitative filters, remove one before adding another.
- If usage or concurrency blocks **Run screen**, no run started. Review **Settings → Usage**, wait for capacity, or reduce the scope.
- If results are too broad, make the condition observable and add a period; if too narrow, remove an unsupported or redundant constraint.

For saved configurations, run history, automatic runs, and date changes on rerun, see [Run and schedule screens](https://portraitresearch.com/documentation/screening/run-and-schedule-screens/).