# Agent workflow

Written for a model that has the unzoi tools. The order below is the one that
spends the fewest calls and the least context for a correct answer.

## The loop

1. **Name the entity, if there is one.** `resolve_entity { "q": "ASML Holding NV",
   "type": "organization", "from": ... }` returns the spellings the index holds,
   grouped under an `entity_id` such as `organization:asml`. Filters are exact
   matches on those spellings; a value the index does not hold matches nothing
   and looks like no coverage.
2. **Find what happened.** `list_stories` with the `entity_id` (or `q`) and a time
   range. One row per event, with its article and outlet counts, is almost always
   more useful than forty copies of the same wire story.
3. **Expand one event.** `get_story { "id": story_id }` returns the whole story in
   one call: counts, outlets, first and last seen, who reported it first, the
   entities it is about and its newest articles. Do not search again to expand a
   story you already have.
4. **Read one article.** `get_article { "id": ... }` for names, places with
   coordinates, dates, quotations and amounts.
5. **Widen from a result you trust.** `find_related { "id": ... }` for similar
   stories; `related_entities { "entity_id": ... }` for who appears alongside an
   entity, with the shared articles as evidence.

## Other questions, other tools

| The question | Tool |
|---|---|
| How did attention move over time? | `aggregate_news` with `interval` |
| What is happening near a place? | `search_news` or `list_stories` with `near` and `radius_km`, or `bbox` |
| Which bankruptcies, outages or strikes? | `event_type`, with `q` alongside when recall matters |
| How are two entities connected? | `connection_path` |
| What changed around an entity? | `entity_network` with `compare_from` and `compare_to` |
| What do these companies have in common? | `shared_exposures` |
| Tell me when it happens | `create_watch`, then `watch_events` |
| How much can I still spend? | `account_status`, which is free |

## Rules that keep answers honest

- **Always pass a time range** and say which window you searched.
- **Never conclude absence** when `partial` is true, `coverage` is anything but
  `complete`, or `from_clamped` is true. See the completeness guide.
- **Zero results with a filter set** may mean the value is wrong: resolve it, or
  drop the filter, before reporting that nothing happened.
- **Cite outlets and link their URLs.** An outlet count is breadth of
  distribution, not the number of independent newsrooms: wire services and
  ownership groups put one report on many domains.
- **Present co-mentions as reporting patterns.** `related_entities` measures who
  was written about together, not who owns, funds or supplies whom.
- **Spend credits deliberately.** `credits_charged` on every result is what the
  call cost. Searches cost 1; vector ranking, story expansion, entity ids,
  geographic scans and relationships cost more. Preview an expensive call with
  `estimate=true`, and pass `max_credits` so it is refused rather than overspending.