Working with the tools

A recommended order for an agent:

1. Call capabilities once per session and keep its vocabularies, limits and corpus date.
2. Call usage before any wide search to check balance and coverage.
3. If the user cannot yet name a company, start with search_cohorts. Many market questions are answered by get_cohort with parts: ["distributions"] alone, without listing any site.
4. Move to search_projects with filters and a small limit. Read the descriptions and drop what is off-topic before revealing anything.
5. Use estimate: true before any call that may show many new entities, and stop if the price or the coverage does not fit the question.
6. Reveal only the projects the user needs named.
7. Buy profile parts in bands first. Ask for precision: exact only when the user needs exact numbers, and keep the result: the surcharge applies again on every exact call.
8. When the user already has domains, use lookup_domain instead of searching.
9. When something goes wrong or is missing, send send_feedback (see "Feedback").

Recipes

User question	Path
"Is anyone already doing X, and who?"	search_cohorts with a short description, search_projects with the same text and a small limit, reveal the closest few, then get_channels and get_keywords to see how they get users.
"Where is there room near X?"	search_cohorts with X to find its niche, get_cohort on it with parts: ["hierarchy"], then search_cohorts with X and filters.level: 1 to compare nearby narrow niches by size, median index and share of growing members.
"Is competitor.com healthy?"	lookup_domain, then get_audience, get_channels, get_keywords. State that growth covers one month only.
"List sites in niche N with 15–75k visits."	search_projects with filters.cohort_id of N and filters.scale_band: ["b15k_75k"], then reveal the ones that match.
"Which niches in market M are growing?"	search_cohorts at the level you need, then get_cohort with parts: ["distributions"] for each niche: it shows both the growing and the declining share.
"Where does a site stand among its peers?"	get_project_card with parts: ["index", "cohorts", "neighbours"], then get_cohort with parts: ["distributions"] on its niche; profile parts for the neighbors in bands.
"Find look-alikes of P, but small."	lookup_domain on P if you have only its domain, then search_projects with P's project id as seed and filters.scale_band; reveal candidates and check team size.