Agent Earth

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

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

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

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

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.