agent-earth

---
name: agent-earth
description: AgentEarth external tool marketplace skill — discover and execute 1400+ external API tools (weather, finance, search, maps, AI generation, and more) via the AgentEarth MCP connector.
version: "1.1.0"
author: "AgentEarth"
---

# AgentEarth Skill

This connector exposes 5 MCP tools backed by the AgentEarth platform. AgentEarth
gives access to 1400+ external API tools across categories including AI
generation, web search, maps, weather, finance, media metadata, developer
APIs, and news. Use these MCP tools directly — do not call any HTTP endpoint
yourself; the connector already handles authentication.

> **Requires WorkBuddy 4.23.0+** (streamableHttp MCP type). If the connector
> shows as unavailable, tell the user to upgrade WorkBuddy.

## Available Tools

### GetAccountOverview

Returns the authenticated user's account info. Takes no arguments.

**Response fields**: `user_id`, `user_name`, `key_name`, `credit` (remaining balance), `error_no` (`0` = success).

Call this directly — without `RecommendTools` first — whenever the user asks
about their AgentEarth account, user ID, API key name, or credit balance.

### RecommendTools - discover tools for a task

| 参数 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| query | string | 是 | 面向任务的自然语言描述 |
| limit | integer | - | 返回工具数量上限 (1-50)，默认 5 |

Returns a list of candidate tools, each with:

- `tool_name` — the tool's identifier
- `tool_url` — opaque URL to pass to `ExecuteTool`; **never modify it**
- `description`, `when_to_use` — what the tool does and when to pick it
- `credit` — cost of one call, use this plus task fit to choose among candidates
- `input_schema` — JSON Schema for `ExecuteTool`'s `params`
- `associated_tools` — optional companion tools (e.g. a geocoding/ID lookup tool) that may need to be called first if a required field can't be filled directly from user input

Call this before `ExecuteTool` for any external-tool task. Read every
candidate's `input_schema` and `associated_tools` before picking one — some
fields require an ID or code obtained from a companion lookup tool rather
than free text (e.g. a weather tool that needs a location ID resolved by a
geocoding tool first).

### ListTools - browse tools without semantic search

| 参数 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| page | integer | - | 页码，从 1 开始，默认 1 |
| page_size | integer | - | 每页数量 (1-100)，默认 20 |
| keyword | string | - | 按名称/描述关键词过滤 |
| sort | string | - | 排序方式：`hot`（热度，默认）/ `new`（最新）/ `name`（名称） |

Use when the user wants to browse or search tools by name/category rather
than describe a task. For large catalogs, paginate with `page` and
`page_size` (max 100 per page) instead of requesting everything at once.

### GetToolDetail - inspect one tool by exact name

| 参数 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| tool_name | string | 是 | 精确工具名 |

Returns the same shape as one entry from `RecommendTools`/`ListTools`
(`tool_url`, `description`, `input_schema`, etc). Use when you already know
the exact `tool_name` (e.g. from `associated_tools`, or the user named a
specific tool) and don't need semantic search.

### ExecuteTool - run a tool

| 参数 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| tool_url | string | 是 | 从 `RecommendTools`/`GetToolDetail` 原样取得的 URL，禁止修改、拼接或重排 |
| params | object | - | 按所选工具 `input_schema` 构造的入参 |

Must be called after `RecommendTools` or `GetToolDetail`. `tool_url` must be
passed through byte-for-byte as returned — do not edit, re-encode, or
reconstruct it. Build `params` strictly from the selected tool's
`input_schema.properties`; validate `required`, `type`, `enum`, and
`additionalProperties` before calling.

## Examples

- "What's my AgentEarth credit balance?" → call `GetAccountOverview()` directly (no `RecommendTools`).
- "Use AgentEarth to check today's weather in Shanghai" → `RecommendTools({"query": "current weather in Shanghai"})` → pick a weather tool from the candidates → if its `input_schema` needs a location ID/adcode rather than a free-text city name, call the companion lookup tool named in `associated_tools` first → `ExecuteTool({"tool_url": <candidate's tool_url>, "params": {...}})`.
- "Use AgentEarth to check the current Bitcoin price" → `RecommendTools({"query": "current bitcoin price"})` → `ExecuteTool` with the chosen finance tool's `tool_url` and schema-derived `params`.
- "List the AgentEarth tools related to maps" → `ListTools({"keyword": "map"})` to browse by name instead of describing a task.
- User names a specific tool exactly (e.g. "run ae_qweather_geo_top_city") → `GetToolDetail({"tool_name": "ae_qweather_geo_top_city"})` instead of `RecommendTools`.

## Workflow

1. Account questions (user ID, user name, key name, credit balance) → call
   `GetAccountOverview` directly. Skip `RecommendTools` for these.
2. External-tool tasks → call `RecommendTools` with a natural-language
   description of the task, or `ListTools`/`GetToolDetail` when the user
   wants to browse or inspect tools by name.
3. Review the candidates' `tool_url`, `description`, `when_to_use`, and
   `input_schema`. Pick the best fit by task relevance, schema clarity, and
   `credit` cost; keep a fallback candidate when one exists.
4. If a required param needs an ID/code from a companion tool (see
   `associated_tools`), call that tool first.
5. Call `ExecuteTool` with the exact `tool_url` and `params` built from
   `input_schema`.
6. Never invent a required value (URL, ID, token, code snippet, or other
   concrete input) that the user hasn't provided — ask the user instead.

## Reading the Result

`ExecuteTool`'s MCP result has an `isError` field — that is the reliable
success/failure signal, not a fixed field inside the payload:

- **`isError` absent/false** — the call succeeded. The content is the
  **raw response of the underlying third-party API**, in that API's own
  format (it may or may not contain something resembling `error_no`/status
  fields of its own — don't assume a single universal shape across tools).
- **`isError: true`** — the call failed. The error detail comes back
  wrapped as `<tool_output>...</tool_output>`, often followed by a
  `<platform_annotation>` with a suggestion (e.g. "revise your request
  parameters based on the upstream provider's error message"). Use that
  detail to correct `params` and retry, or fall back to another candidate
  from `RecommendTools` if the issue isn't fixable from user-provided input.

`GetAccountOverview` and `GetToolDetail`/`RecommendTools`/`ListTools` (the
AgentEarth-native lookups, as opposed to `ExecuteTool` passthrough results)
do use `error_no == 0` as their own success signal.

## Fault Tolerance & Degradation

- **Authentication failure (401/403)**: If a tool call returns an auth error,
  the API key may be invalid, expired, or revoked. Tell the user to reconnect
  AgentEarth from the WorkBuddy Connector page — do not ask them to paste a
  key in chat. After reconnection, retry the call.
- **Rate limiting (429)**: If a tool call is rate-limited, wait briefly and
  retry once. If it persists, inform the user that they may have hit their
  plan's rate limit and suggest trying again later or upgrading their
  AgentEarth plan.
- **MCP connection timeout or server unreachable**: If a tool call times out
  (default timeout is 60s) or the MCP server appears unreachable, tell the
  user the AgentEarth service may be temporarily unavailable and suggest
  retrying later. Do not attempt to construct HTTP requests yourself.
- **Empty results from `RecommendTools`/`ListTools`**: If no tools match the
  query, broaden the search by rephrasing the task description, removing
  overly specific constraints, or trying different keywords. If still no
  results, inform the user that AgentEarth may not cover this particular use
  case.
- **`isError: true` from `ExecuteTool`**: Read the error detail in
  `<tool_output>`, correct `params` accordingly, and retry. If the issue
  persists, fall back to another candidate from `RecommendTools`.
- **Large result sets & pagination**: When `ListTools` returns many results,
  use `page` and `page_size` to paginate (max 100 per page). For
  `RecommendTools`, increase `limit` (up to 50) if the initial candidates
  don't fit the task. For `ExecuteTool` results that are unexpectedly large,
  summarize the key fields for the user rather than dumping the entire
  payload.

## When NOT to Use AgentEarth

- **Real-time or latency-critical applications** where sub-second freshness
  is required — AgentEarth tools are API-based and subject to upstream
  provider latency.
- **Tasks requiring guaranteed data persistence** — AgentEarth tools are
  read-only data retrieval and generation services, not storage systems.
- **Sensitive internal data queries** — do not route internal/private data
  through third-party API tools.

## Credentials

The AgentEarth API key is injected by WorkBuddy from the connector's Token
form (`token-schema.json`) directly into the MCP connection — this skill
never sees or handles it. Do not ask the user to paste an API key in chat.

If the user has never used AgentEarth before and the connector is not yet
configured, guide them to the WorkBuddy Connector page to add the AgentEarth
connector and enter their API key there.

If the connector shows as disconnected or a call fails with an auth error,
tell the user to (re)connect AgentEarth from the WorkBuddy Connector page.

If the user needs a new or replacement AgentEarth API key (lost, revoked, or
first-time setup), point them to `https://agentearth.ai/r/8oo9zmDn` — sign in, then open the
avatar menu in the top-right corner and go to **API Keys** — then have them
paste it into the WorkBuddy Connector's Token form, never into the chat.

## Incorrect Flow

- Calling `ExecuteTool` before `RecommendTools`/`GetToolDetail`.
- Modifying, re-encoding, or reconstructing `tool_url`.
- Inventing required params instead of asking the user.
- Treating `error_no == 0` as the success signal for `ExecuteTool` results —
  use `isError` instead.
- Making raw HTTP requests to AgentEarth endpoints yourself, or asking the
  user for their API key — this connector only ever talks to AgentEarth
  through the 5 MCP tools above.