find-and-run skill

How the looot plugin's find-and-run skill searches by job, runs with fallback, and reads the outcome and receipt.

find-and-run is the plugin’s core skill. It loads automatically whenever a task needs external or live data: SEO and SERP data, keyword volume, backlinks, people and company enrichment, email finding and verification, social profiles, or web scraping.

What it does

The skill uses search, inspect, run, runs_get, runs_list, runs_evidence and balance. Searching and inspecting are free. discover_smart costs a small fee, so the skill asks before using it.

1. Search by the job, not the vendor. It calls search with a plain-words query, for example “find a work email from a name and domain”. Each row has an endpointId, provider, the job id in capability, estimatedPrice, priceBasis, and costPerSuccessUsd (price divided by success rate). works holds rate, runs and p50Ms; thin: true means fewer than 5 runs back the rate. access is runs_now, needs_your_account or coming_soon.
2. Read jobInputs. The search answer’s top-level jobInputs lists each job’s inputs with coverage, so the agent knows which field name gets accepted by the most providers.
3. Run the job. It sends endpointId: "job:<job id>" with the shared input names from jobInputs, plus a new idempotencyKey for every run and, usually, a fallback object (maxAttempts, maxCostUsd, prefer). looot tries providers of that job in order, free ones first, inside one hold.
4. Read the answer. It checks status and error first, since a call can succeed and still carry status: "failed". Then it reads outcome (hit, weak, miss, error, rejected, skipped or pending), normalized.fields when the job has one, servedEndpointId and servedProviderId (who actually answered, which can differ from endpointId after a fallback), requestedJob for what was asked, and route for the fallback trail (servedBy, outcome, chargedUsd, attempts, skipped, summary).
5. Get the receipt. runs_evidence for every attempt with its cost, or runs_list for history.

If search comes back empty with a no_supply_for_job warning, the skill tells the user no endpoint does that job, and can call capability_request to ask looot to add one.

Worked example

User: “Find the work email of Jane Doe at example.com.”

The agent searches, then runs the job with fallback:

{"tool": "search", "input": {"query": "find a work email from a name and domain"}}

{
  "tool": "run",
  "input": {
    "endpointId": "job:people.email.find",
    "input": {"first_name": "Jane", "last_name": "Doe", "domain": "example.com"},
    "idempotencyKey": "jane-doe-example-find-01",
    "fallback": {"maxAttempts": 3, "maxCostUsd": 0.1, "prefer": "cheapest"}
  }
}

The run comes back completed, with outcome: "hit", normalized.fields.email set, servedProviderId naming the provider that answered, and route.summary reading something like “hunter: found ($0.0245). Charged $0.0245.”

Agent’s answer: “Found jane.doe@example.com, served by [provider from servedProviderId]. Charged [actualCost]. Verify it before sending anything important; see the money and troubleshooting skills for what a weak or guessed result means.”

See money for cost rules, recipes for ready-made flows, and troubleshooting for error codes.