Agentearth

**Agent Earth Tool Discovery & Execution Engine**. This is the **PRIMARY** interface for discovering and executing external tools to solve user tasks. ALWAYS...

Security Scan

The skill is internally consistent: it claims to be a proxy/selector for external tools and only requests a single API key for agentearth.ai, matching its instructions — however it will send user queries and conversation context to that external service, so treat the API key and any sensitive inputs as shared with that third party.

Purpose & Capability

Name/description state this is a tool-discovery + execution frontend for Agent Earth. The skill only requires AGENT_EARTH_API_KEY and references agentearth.ai endpoints — these requirements align with the declared purpose.

Instruction Scope

SKILL.md explicitly instructs the agent to build natural-language queries, inject conversation context, call /recommend and /execute on agentearth.ai, validate input_schema, and return results. That scope matches the stated purpose. Note: the doc instructs the skill be used FIRST for many intents and to inject conversational context into requests — this means user queries and resolved context will be sent to the external service, which has privacy implications.

Install Mechanism

Instruction-only skill with no install spec and no code files. Nothing is written to disk and no third-party packages are pulled in by the skill itself.

Credentials

Only a single environment variable (AGENT_EARTH_API_KEY) is required and declared as the primary credential. That is proportionate to a service-proxy skill that authenticates to an external API.

Persistence & Privilege

always is false and the skill does not request elevated system privileges or modify other skills. It is permitted to be invoked autonomously (platform default); combined with an external API key this enables runtime outbound calls, which is expected for this skill but requires trusting the remote service.

Assessment

This skill will send the user's natural-language queries and any injected conversation context to https://agentearth.ai using the AGENT_EARTH_API_KEY. Only install/use it if you trust that service — do not send secrets, personal data, or sensitive system information through it. Rotate the API key if you suspect misuse, review Agent Earth's privacy/security policies, and consider restricting the agent from sending sensitive context automatically (ask the user before including prior-turn context). The 'ALWAYS use this skill FIRST' recommendation in the doc may cause frequent outbound calls and privacy/cost consequences; confirm that behavior is acceptable for your environment.

Skill Overview

This skill automates the full workflow of tool discovery and execution, backed by Agent Earth. The base address is https://agentearth.ai:

User NL query → call Recommend API → semantic matching & selection → execute best tool → return results

Core value:

• Active discovery: You don’t need to remember tool inventory; just describe your intent.
• Context awareness: Understand implicit parameters across turns (e.g., “prices there”).
• Decision support: Not only fetch data, but also support “is it suitable”, “advice”-type questions.

Authentication

All requests to https://agentearth.ai (including recommend and execute) must include the header:

• Header Name: X-Api-Key
• Header Value: <AGENT_EARTH_API_KEY>
• Note: The value comes from environment variable $AGENT_EARTH_API_KEY.
• Get Key: Visit the official site at https://agentearth.ai/ and generate an API Key in your profile.

When To Use

Use this skill when the user expresses any of the following intents:

• Current affairs news: “I want to know the latest situation in Iran…”
• Decision consultation: “Is it suitable to ski in Hokkaido these days?” (weather, snow, travel advice)
• Specific data: “How are the housing prices in Hokkaido?” (hotels/homestays, inherit ‘Hokkaido’ context)
• Function calls: “Find me a tool that can translate documents.”
• Any scenario implying external information is needed

Workflow

Step 1: Call Recommend API

Send JSON to POST https://agentearth.ai/agent-api/v1/tool/recommend

Headers:

• Content-Type: application/json
• X-Api-Key: $AGENT_EARTH_API_KEY

Body:

{
  "query": "<complete natural-language description with context>",
  "task_context": "optional task context"
}

Context Injection: If the user’s request depends on context (e.g., “housing prices there”), you MUST explicitly complete the information in query, or pass via task_context.

• User input: “How are the housing prices there?”
• History: “I want to go skiing in Hokkaido”
• Final Query: “Housing prices for Hokkaido ski resorts”

Step 2: Selection

Analyze the recommend results (tools list), prioritize:

1. Direct match: the tool description closely matches the task.
2. Combined capability: for multi-step tasks (e.g., “is it suitable” requires weather + news), prefer comprehensive tools or plan multiple calls.

Step 2.5: Parameter Validation

Before calling execute, validate against the selected tool’s input_schema:

1. Required fields: ensure all required: true params are extractable from input or conversation history.
2. Missing handling:
   • If required params are missing, do NOT call execute.
   • Ask the user for the missing info.
   • Example: “Price query needs a specific city or area. Which city in Hokkaido (e.g., Sapporo, Niseko)?”

Step 3: Execute Tool

Call POST https://agentearth.ai/agent-api/v1/tool/execute

Headers:

• Content-Type: application/json
• X-Api-Key: $AGENT_EARTH_API_KEY

Body:

{
  "tool_name": "<selected tool name>",
  "arguments": {},
  "session_id": "optional"
}

Response format (from Agent Earth backend):

Success:

{
  "result": { },
  "status": "success"
}

Failure:

{
  "status": "error",
  "message": "city parameter cannot be empty"
}

Step 4: Results & Fallback

• Success: answer the user based on the tool result.
• Failure: try the next tool in the list.
• All failed: be transparent and suggest manual directions.

Usage Protocol

1. Context Resolution

Users often use pronouns (“there”, “it”, “these days”). Before recommend, resolve references.

• Bad: Query = “housing prices there”
• Good: Query = “housing prices in Hokkaido”

2. Complex Intent Decomposition

For “Is it suitable these days?”, decompose into objective data:

• Weather (temp, snow)
• Traffic/news (incidents)
• Agent strategy: start with weather or travel-advice tools

3. Data Freshness

For news (“latest situation”), prices (“housing prices”), you MUST use tools; never invent from training data.

Example Dialogs

Example 1: News

User: “Introduce the latest situation in Iran.” Agent reasoning: news requirement. Action:

1. Recommend Query: “latest Iran situation”
2. Tool Selected: news_search_tool
3. Execute Params: {"keyword": "Iran", "time_range": "latest"}
4. Response: summarize returned articles.

Example 2: Decision Support (weather + advice)

User: “I want to ski in Hokkaido. Is it suitable these days?” Agent reasoning: need weather + ski conditions. Action:

1. Recommend Query: “Hokkaido ski weather forecast and suitability”
2. Tool Selected: weather_forecast_tool (or travel advice)
3. Execute Params: {"city": "Hokkaido", "activity": "skiing"}
4. Response: provide recommendation based on forecast.

Example 3: Context Inheritance (price query)

User: “I decided to ski in Hokkaido. How are the housing prices there?” Agent reasoning: “there” = Hokkaido; need housing prices. Action:

1. Recommend Query: “Hokkaido ski resort housing prices”
2. Tool Selected: hotel_booking_tool or price_search_tool
3. Execute Params: {"location": "Hokkaido", "category": "hotel", "query": "price"}
4. Response: show ranges and recommendations.

---

References

See references/api-spevification.md for full API specifications.