Skip to main content
describe_tool gives you everything you need to call a tool correctly and confidently. It returns the complete JSON Schema for the tool’s parameters (including types, required fields, enums, and examples), the exact per-call credit cost, an execute_as template you can copy directly into execute_tool, and the current upstream health status for the tool. Calling it takes one credit-free lookup and eliminates the guesswork that causes invalid-parameter errors.
Always call describe_tool before every execute_tool. Parameter schemas and costs can change as providers update their APIs. Never assume that a schema you retrieved in a previous session is still current, and never invent parameter names from memory.
​
name
string
required
The canonical Provider/Operation name for the tool you want to describe — for example Firecrawl/scrape, Twitter/searchTweets, or Brave/getWebSearch. You can also pass a browse-tree path (for example crypto/market/...) or the special value agentkey_account to describe the account tool itself.If you pass a name with a typo, describe_tool returns a set of fuzzy-match suggestions rather than an error. Read those suggestions and correct the name rather than retrying the same call blindly.

​
Returns

​
params
object
The full JSON Schema for the tool’s parameters, including property types, required fields, enum values where applicable, and inline examples. Copy these definitions to build your execute_tool call.
​
cost
object
Pricing information for one call to the tool.
​
cost.credits_per_call
number
Credits deducted from your balance per execution.
​
cost.usd_per_call
number
Approximate USD equivalent of one call.
​
cost.cost_by_provider
object
A breakdown of cost per underlying provider, shown when AgentKey routes across multiple providers for the same operation.
​
execute_as
object
A ready-to-run template with the name field already set and placeholder values for every required parameter. Copy this object, fill in the placeholders, and pass it directly to execute_tool.
​
health
string
The current upstream availability status for this tool. Values are typically healthy, degraded, or unavailable. If the status is anything other than healthy, consider checking the account tool for a broader view of provider health before proceeding.

​
Cost guidance

Before you run a batch of calls, multiply cost.credits_per_call by your planned call count and compare the result against your current balance. For any bulk work involving three or more calls or a non-trivial credit amount, run the free account tool first to confirm you have sufficient balance.

​
Example

describe_tool("Firecrawl/scrape")

{
  "name": "Firecrawl/scrape",
  "cost": { "credits_per_call": 0.2, "usd_per_call": 0.004 },
  "execute_as": { "name": "Firecrawl/scrape", "params": { "url": "<The URL to scrape.>" } },
  "params": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "format": "uri" } } }
}

​
Next step

Copy the execute_as object, replace the placeholder values with real inputs, and pass it to execute_tool.

execute_tool

Run the tool with your filled-in parameters and receive the provider’s response.