データツール

最適なツールを見つける

カタログを閲覧し、キーワードで検索し、タスクを説明して費用付きの手順プランを受け取り、実行前にツールの入力スキーマを確認します。

カタログのエンドポイントは公開されており、無料です。キーなしで呼び出せるので、エージェントは適切なツールを選ぶために必要なだけ呼び出せます。検索に使うエンドポイントは次の 4 つです。

やりたいこと	呼び出すエンドポイント
すべてのツール、または 1 カテゴリのツールを見る	`GET /v1/tools`
「tiktok comments」のような短いクエリでツールを探す	`POST /v1/tools/discover`
タスク全体を説明し、費用付きのプランを受け取る	`POST /v1/tools/suggest`
1 つのツールの入力スキーマ、入力例、価格を読む	`GET /v1/tools/{id}`

カタログを閲覧する#

GET /v1/tools は、利用可能なすべてのツールを価格付きで返します。クエリパラメータで一覧を絞り込めます。

category：reviews や lead-generation などのカテゴリ ID を 1 つ指定します。カテゴリを参照してください。
q：キーワード。結果は関連度順に最大 100 件返ります。
lang：zh または ja を指定すると、ツール名と説明がその言語で返ります。デフォルトは英語です。

cURL

curl "https://lovelyrouter.com/v1/tools?category=reviews"

レスポンスはツールオブジェクトのリストです（ここでは 1 件に省略しています）。

JSON

{
  "object": "list",
  "data": [
    {
      "id": "google-maps-reviews",
      "name": "Google Maps reviews",
      "platform": "Google Maps",
      "category": "reviews",
      "description": "Reviews of a Google Maps place (by place ID or URL): text, stars, date, owner replies.",
      "price": {
        "per_call_usd": 0,
        "per_result_usd": 0.000675,
        "unit": "review",
        "label": "$0.000675 / review"
      },
      "default_results": 20,
      "max_results": 500,
      "featured": false
    }
  ]
}

price オブジェクトは最新の価格です。default_results は max_results を指定しないときに実行が使う結果数の上限で、max_results はそのツールが受け付ける上限の最大値です。各フィールドの説明はツールオブジェクトにあります。

キーワードで検索する#

POST /v1/tools/discover は短いクエリを受け取り、関連度の score 付きで最も一致するツールを返します。プラットフォーム名とツール名は説明文より重く評価されるため、プラットフォーム名を含むクエリではそのプラットフォームのツールが上位に来ます。

cURL

curl https://lovelyrouter.com/v1/tools/discover \
  -H "content-type: application/json" \
  -d '{"query": "google maps reviews", "limit": 3}'

JSON

{
  "query": "google maps reviews",
  "count": 3,
  "results": [
    {
      "id": "google-maps-reviews",
      "name": "Google Maps reviews",
      "platform": "Google Maps",
      "category": "reviews",
      "price": { "per_call_usd": 0, "per_result_usd": 0.000675, "unit": "review", "label": "$0.000675 / review" },
      "default_results": 20,
      "max_results": 500,
      "score": 0.889
    },
    {
      "id": "google-maps-places",
      "name": "Search Google Maps places",
      "platform": "Google Maps",
      "category": "search",
      "price": { "per_call_usd": 0.00075, "per_result_usd": 0.000238, "unit": "place", "label": "$0.000238 / place + $0.00075 / call" },
      "default_results": 10,
      "max_results": 200,
      "score": 0.717
    },
    {
      "id": "google-maps-leads",
      "name": "Google Maps leads with emails",
      "platform": "Google Maps",
      "category": "lead-generation",
      "price": { "per_call_usd": 0, "per_result_usd": 0.00075, "unit": "place", "label": "$0.00075 / place" },
      "default_results": 10,
      "max_results": 200,
      "score": 0.556
    }
  ]
}

limit のデフォルトは 5 で、最大 40 です。score は結果の並べ替えに使い、絶対的な指標としては扱わないでください。同じクエリに対するツール同士を比べるための値です。

タスクのプランを立てる#

タスクに複数のツールが必要な場合や、どのツールが合うか分からない場合は、タスクを普通の言葉で説明してください。POST /v1/tools/suggest は 1 秒未満で手順付きのプランを返します。最初に実行するツール、必要に応じて 2 つ目のツール、近い代替案が含まれ、それぞれに入力例と見積もり費用が付きます。

cURL

curl https://lovelyrouter.com/v1/tools/suggest \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"task": "Find vegan restaurants in Austin and summarize what their reviews complain about"}'

レスポンス（一部省略）：

JSON

{
  "task": "Find vegan restaurants in Austin and summarize what their reviews complain about",
  "source": "ai",
  "cached": false,
  "count": 2,
  "suggestions": [
    {
      "step": 1,
      "role": "primary",
      "match": 0.961,
      "id": "google-maps-places",
      "name": "Search Google Maps places",
      "price": { "per_call_usd": 0.00075, "per_result_usd": 0.000238, "unit": "place", "label": "$0.000238 / place + $0.00075 / call" },
      "input": {
        "searchTerms": ["coffee shop"],
        "location": "Austin, Texas, USA",
        "maxResults": 3,
        "language": "en"
      },
      "input_required": [],
      "max_results": 10,
      "est_cost_usd": 0.00313,
      "run": {
        "method": "POST",
        "path": "/v1/tools/google-maps-places/run",
        "body": { "input": { "searchTerms": ["coffee shop"], "location": "Austin, Texas, USA", "maxResults": 3, "language": "en" }, "max_results": 10 }
      }
    },
    {
      "step": 2,
      "role": "next",
      "match": 0.875,
      "id": "google-maps-reviews",
      "name": "Google Maps reviews",
      "price": { "per_call_usd": 0, "per_result_usd": 0.000675, "unit": "review", "label": "$0.000675 / review" },
      "input": { "placeIds": ["ChIJN1t_tDeuEmsRUsoyG83frY4"], "maxReviews": 3, "reviewsSort": "newest" },
      "input_required": [],
      "max_results": 20,
      "est_cost_usd": 0.0135,
      "run": {
        "method": "POST",
        "path": "/v1/tools/google-maps-reviews/run",
        "body": { "input": { "placeIds": ["ChIJN1t_tDeuEmsRUsoyG83frY4"], "maxReviews": 3, "reviewsSort": "newest" }, "max_results": 20 }
      }
    }
  ],
  "total_est_cost_usd": 0.01663
}

プランの読み方#

role はそのステップの位置付けを示します。primary は最初に実行するツール、next はタスクが求める 2 種類目のデータを取得するツール（この例ではステップ 1 で見つけた場所のレビュー）、alternative は primary の代わりに使える次点の候補です。
match は、そのステップに対するプランナーの確信度で、0 から 1 の値です。
input はツールの入力例であり、あなたのタスク用に書かれたものではありません。 値を自分のものに置き換えてください。上の例では "coffee shop" を "vegan restaurant" にします。input_required には必ず設定すべきフィールドが並びます。完全なスキーマは GET /v1/tools/{id} で取得できます。
est_cost_usd は、表示されている max_results（ツールのデフォルトの上限）でのそのステップの最大費用です。max_results を変えると、費用もそれに比例して変わります。
total_est_cost_usd は primary と next のステップの合計です。代替案は追加ではなく置き換えとして実行するものなので、含まれません。
run はツールを実行するためのリクエストのひな形です。入力を埋めたら、body を path に送ります。

suggestions が空のリストなら、カタログにタスクに合うツールがないことを意味します（例：「詩を書いて」）。プランナーが利用できない場合、エンドポイントはキーワード一致にフォールバックし、source を keyword にします。同じタスクには 1 日間キャッシュから回答し、cached: true が付きます。

オプションと制限#

ボディには task（必須、最大 2,000 文字）、limit（提案数、1〜8、デフォルト 5）、lang（zh または ja）を指定します。

プランの作成は無料ですが、レート制限があります。

呼び出し元	制限
API キーあり	キーごとに 1 分あたり 100 リクエスト
キーなし	1 分あたり 100 リクエスト（すべての匿名の呼び出し元で共有）

制限を超えると、エンドポイントは秒数を示す retry-after ヘッダー付きで 429 を返します。キーを送れば、自分専用の制限枠が使えます。

ツールを詳しく見る#

ツールを実行する前に、入力スキーマを確認してください。GET /v1/tools/{id} はツールオブジェクトに加えて、input_schema（input の JSON Schema）、そのまま使える example_input、実行の制限時間 timeout_s、すぐ使える run リクエストを返します。

cURL

curl https://lovelyrouter.com/v1/tools/trustpilot-reviews

レスポンス（一部省略）：

JSON

{
  "id": "trustpilot-reviews",
  "name": "Trustpilot reviews",
  "platform": "Trustpilot",
  "category": "reviews",
  "description": "Trustpilot reviews of a company by domain: stars, text, date, reply.",
  "price": {
    "per_call_usd": 0.0075,
    "per_result_usd": 0.0015,
    "unit": "review",
    "label": "$0.0015 / review + $0.0075 / call"
  },
  "default_results": 20,
  "max_results": 500,
  "featured": false,
  "input_schema": {
    "type": "object",
    "properties": {
      "companyUrls": {
        "type": "array",
        "title": "Company URLs or Domains",
        "description": "Enter Trustpilot company URLs (e.g., https://www.trustpilot.com/review/example.com) or just the domain (e.g., example.com). One per line."
      },
      "maxReviewsPerCompany": {
        "type": "integer",
        "title": "Max reviews per company (reviews)",
        "description": "Maximum number of reviews to scrape per company. Set to 0 for unlimited reviews.",
        "default": 0,
        "minimum": 0
      },
      "sort": {
        "type": "string",
        "title": "Sort Order",
        "enum": ["relevance", "recency"],
        "default": "recency"
      }
    },
    "required": ["companyUrls"]
  },
  "example_input": {
    "companyUrls": ["pipedrive.com"],
    "maxReviewsPerCompany": 20
  },
  "timeout_s": 300,
  "run": {
    "method": "POST",
    "path": "/v1/tools/trustpilot-reviews/run",
    "body": { "input": { "companyUrls": ["pipedrive.com"], "maxReviewsPerCompany": 20 }, "max_results": 20 }
  }
}

フィールド名とその意味はツールごとに異なるため、input は必ず input_schema に従って組み立ててください。費用を抑えるためにツール独自の件数フィールド（この例では maxReviewsPerCompany）を設定する必要はありません。どちらにしても max_results が実行の上限になります。ツールページではすべてのツールについて同じスキーマを確認でき、ログインすればその場でツールを試せます。

存在しないツール ID や提供終了したツール ID には 404 が返ります。

名前と説明をローカライズする#

カタログへのどのリクエストにも lang=zh または lang=ja を追加できます。GET ではクエリパラメータとして、POST ではボディの "lang" として指定します。ツール名と説明が翻訳されて返ります。ID、価格、入力スキーマは変わりません。

cURL

curl "https://lovelyrouter.com/v1/tools/google-maps-reviews?lang=ja"

次のステップ#

ツールを実行する

組み立てた入力で実行を開始します。

MCP サーバー

エージェント自身に検索・プラン作成・実行を任せます。