{
  "page": "discovery",
  "title": "Let your agent pick the right API for each job",
  "path": "/discovery",
  "kind": "product",
  "description": "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.",
  "updated": "2026-10-23",
  "blocks": [
    {
      "type": "p",
      "text": "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."
    },
    {
      "type": "h2",
      "id": "ask",
      "text": "Ask in plain words"
    },
    {
      "type": "code",
      "title": "curl",
      "lang": "bash",
      "code": "curl https://api.arettic.com/v1/recommend \\\n  -H \"Authorization: Bearer sk_test_…\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"task\": \"find the email and job title of the CTO at acme.com\" }'"
    },
    {
      "type": "p",
      "text": "Or name a task type, like `find_verified_email`, with a region and limits on price and score."
    },
    {
      "type": "code",
      "title": "curl",
      "lang": "bash",
      "code": "curl https://api.arettic.com/v1/recommend \\\n  -H \"Authorization: Bearer sk_test_…\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"task_type\": \"find_verified_email\",\n    \"region\": \"US\",\n    \"constraints\": { \"max_price\": 50, \"min_score\": 40 }\n  }'"
    },
    {
      "type": "h2",
      "id": "ranking",
      "text": "How tools are ranked"
    },
    {
      "type": "list",
      "items": [
        "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."
      ]
    },
    {
      "type": "h2",
      "id": "run",
      "text": "Then run it"
    },
    {
      "type": "p",
      "text": "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."
    },
    {
      "type": "code",
      "title": "curl",
      "lang": "bash",
      "code": "curl https://api.arettic.com/v1/execute \\\n  -H \"Authorization: Bearer sk_test_…\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"tool_id\": \"hunter-verify-email\",\n    \"input\": { \"email\": \"jane@acme.com\" },\n    \"fallback\": true,\n    \"max_price\": 50\n  }'"
    },
    {
      "type": "h2",
      "id": "score",
      "text": "What the score measures"
    },
    {
      "type": "p",
      "text": "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)."
    },
    {
      "type": "note",
      "text": "Scores appear after the first benchmark run. Until then, tools are ranked by price."
    }
  ],
  "questions": [
    {
      "question": "What is API discovery for AI agents?",
      "answer": "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."
    },
    {
      "question": "Is recommend free?",
      "answer": "Yes. It uses no credits. It counts toward your plan's daily lookup quota."
    },
    {
      "question": "Can my agent use a provider that isn't the top pick?",
      "answer": "Yes. The ranking is advice. Your agent can send any purchasable `tool_id` to `execute`."
    },
    {
      "question": "Does Arettic rank the tools it sells higher?",
      "answer": "No. Whether a tool can be bought here is a field in the answer, not a factor in the rank."
    },
    {
      "question": "Does it work over MCP?",
      "answer": "Yes. The `recommend` tool on the [MCP server](/mcp) does the same."
    }
  ]
}