# Working with the tools > A recommended order of calls for an agent and recipes for common market questions. A recommended order for an agent: 1. Call `capabilities` once per session and keep its vocabularies and limits. 2. Call `usage` before any wide search to check available credits 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"). ## When a call is refused A refusal names what went wrong and carries what you need to go on. | Refusal | When | What to do | |---|---|---| | `unknown_filter_value` | a filter value is not in the vocabulary | pick one of the nearest accepted values it lists | | `coverage_exceeded` | the call would show more new niches or projects than the coverage left this period | set the parameter named in `fitting_param` to `fitting_limit`, or for a list of ids or domains keep its first `fitting_limit` items; 0 means even the fixed part does not fit: ask for fewer parts, or wait for the next period | | `insufficient_balance` | your available credits do not cover the call | tell your user; an owner of your organization tops up at `top_up_url` | | `sign_up_required` | your account has no registration and the tool needs one | ask your user to register at `sign_up_url`, a link that works once, in any browser, for 30 minutes: the same account and connection keep working | | `quota_exhausted` | the free quota of your plan does not cover a call of an index tool, and the available credits do not cover the rest | when `fitting_limit` is present, set `fitting_param` to it; without registration, ask your user to register at `sign_up_url`; otherwise wait for `renews_on`, or tell your user that an owner tops up at `top_up_url` | | `limit_exceeded` | a limit is passed: list size, batch size, sample size, cursor depth, the daily feedback limit or the hourly limit of task messages | stay within `max`; past a daily or hourly limit, wait | | `confirmation_required` | the call costs credits, and your organization requires an estimate for this tool or for a call that may cost more than `estimate_required_above` | the refusal carries the estimate: show your user the price and run it with its `quote_token` | | `quote_expired` | the estimate is no longer valid | estimate again | | `quote_spent` | the estimate has already run and its replay has ended | estimate again | | `quote_outdated` | the estimate counted on more free quota than is left now | estimate again | | `layer_unavailable` | a part of the corpus is not available now or for this entity, such as text search while it is down | use what `available` lists, or try later | Beyond these, too many calls in a second get HTTP 429 with `Retry-After`: wait and call again. A revoked key or a suspended organization gets HTTP 401. Over the HTTP API every refusal also comes with an HTTP status of its own. ## 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. Members' last months can differ, so do not read a small difference between niches as a trend. | | "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 on their sites whether they are small companies. |