# Let your agent pick the right API for each job

Your agent names the job, as a task type or in plain words. Arettic ranks every tool for it by public score, then price, and your agent runs the top one.

Can an AI agent choose which API to call? Yes. With Arettic, your agent describes the job and gets back the tools that can do it. They're ranked by a public score for that job and region, each with its price per passing result and the check it must pass. No provider is hardcoded, and a better one needs no code change.

## Ask in plain words

**curl**

```bash
curl https://api.arettic.com/v1/recommend \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{ "task": "find the email and job title of the CTO at acme.com" }'
```

Or name a task type, like `find_verified_email`, with a region and limits on price and score.

**curl**

```bash
curl https://api.arettic.com/v1/recommend \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "find_verified_email",
    "region": "US",
    "constraints": { "max_price": 50, "min_score": 40 }
  }'
```

## How tools are ranked

- By score, highest first. Two scores within 2 points count as a tie, and the cheaper tool goes first.
- Tools with no score yet come after every scored tool, cheapest first.
- Whether a tool is sold on Arettic never changes its rank. Paying never changes a score, rank or routing decision.
- On Pro and up, owners can pin a tool so it's tried first, or exclude one.

## Then run it

Send the first `tool_id` marked `purchasable` to `execute`. With `fallback: true`, if an item fails, the next-ranked tool runs once within your `max_price`. Only the tool that passes is charged.

**curl**

```bash
curl https://api.arettic.com/v1/execute \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_id": "hunter-verify-email",
    "input": { "email": "jane@acme.com" },
    "fallback": true,
    "max_price": 50
  }'
```

## What the score measures

Each tool gets a 0 to 100 score per job and region, from accuracy, pass rate, audit precision, reliability and speed, minus a penalty for upheld disputes. Every tool runs the same test cases each week. The formula and every input are on [How scores work](/docs/scores).

> Scores appear after the first benchmark run. Until then, tools are ranked by price.

## Questions

### What is API discovery for AI agents?

It lets an agent find the right API for a job at runtime, instead of a developer hardcoding one provider. On Arettic, `recommend` returns the tools for a job ranked by score, then price.

### Is recommend free?

Yes. It uses no credits. It counts toward your plan's daily lookup quota.

### Can my agent use a provider that isn't the top pick?

Yes. The ranking is advice. Your agent can send any purchasable `tool_id` to `execute`.

### Does Arettic rank the tools it sells higher?

No. Whether a tool can be bought here is a field in the answer, not a factor in the rank.

### Does it work over MCP?

Yes. The `recommend` tool on the [MCP server](/mcp) does the same.

Updated 2026-10-23. This page as HTML: https://arettic.com/discovery · Markdown: https://arettic.com/discovery.md · JSON: https://arettic.com/discovery.json