Docs

Everything an agent needs to call the tools: three ways in (A2A, MCP and REST), one response shape, the error codes, and the limits.

Quickstart

Call any tool with a JSON body:

curl -X POST https://agentops.tools/v1/weather.forecast \
  -H 'content-type: application/json' \
  -d '{"location": "Lisbon", "days": 3}'

Or use query parameters with GET. Arrays are comma-separated. Nested objects need POST:

curl "https://agentops.tools/v1/fx.convert?amount=100&from=USD&to=EUR"

A2A

The agent card is at https://agentops.tools/.well-known/agent-card.json. It lists one skill per tool. Each skill id is the tool name, such as weather.forecast. The JSON-RPC endpoint is https://agentops.tools/a2a.

Both protocol versions work. Send A2A-Version: 1.0 and call SendMessage, the current release. Or leave the header out and call message/send, the 0.3 name.

curl -X POST https://agentops.tools/a2a \
  -H 'content-type: application/json' \
  -H 'A2A-Version: 1.0' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "SendMessage", "params": {"message": {
        "messageId": "m1", "role": "ROLE_USER",
        "parts": [{"data": {"skill": "weather.forecast", "input": {"location": "Lisbon", "days": 3}}}]}}}'

Put the skill and its input in one data part, as above. A text part holding only the skill id also works, with empty input. For media tools, send one file part: raw (base64) or url in protocol 1.0, or file.bytes or file.uri in 0.3. It fills the tool's base64 or url input.

The reply is one agent message. Its data part holds the usual envelope, so check ok first. Tool errors arrive there. JSON-RPC errors cover requests the agent cannot read, and methods it does not offer.

Code	Meaning
`-32601`	Method not found, or the method belongs to the other protocol version.
`-32602`	Invalid params: no skill selected, or a malformed message or part.
`-32001`	Task not found. This agent stores no tasks, so every task id is unknown.
`-32003`, `-32004`	Push notifications, streaming and ListTasks are not offered.
`-32005`	The client accepts only non-JSON output. Replies are always JSON.
`-32007`	No extended agent card is configured.
`-32009`	The A2A-Version header names a version this agent does not speak.

No tasks are stored. Every reply is a message, so GetTask, CancelTask and SubscribeToTask answer TaskNotFound.
Streaming (SendStreamingMessage) and push notifications are not offered.
A2A calls share the quota with REST and MCP, counted per client IP.

MCP

The MCP endpoint is https://agentops.tools/mcp, using Streamable HTTP. It is stateless: there are no sessions to manage. Tool names replace dots with underscores, so weather.forecast is weather_forecast. Each tool result is the same JSON envelope as REST, delivered as text. Input that fails validation returns an MCP protocol error before the tool runs.

Response envelope

Every REST response, and every MCP tool result, has this shape:

{
  "ok": true,
  "data": { "...": "tool-specific fields" },
  "meta": {
    "tool": "weather.forecast",
    "version": "1.0.0",
    "took_ms": 182,
    "cached": false,
    "stale": false,
    "source": ["Open-Meteo forecast API"],
    "attribution": "Weather data by Open-Meteo.com (CC BY 4.0)"
  },
  "error": null
}

cached is true when the result came from cache. stale is true when the upstream failed and a recent cached copy was returned instead. Show attribution wherever you display the data.

Error codes

When ok is false, error.code says what kind of failure it was:

Code	HTTP	Meaning
`INVALID_INPUT`	400	The input did not match the schema. `hint` names the problem.
`NOT_FOUND`	404	No such tool, or the place or record does not exist.
`BLOCKED_TARGET`	403	A URL points at a private or non-public address. Only public sites can be fetched.
`TOO_LARGE`	413	The input or output is over its size limit.
`UNSUPPORTED`	422	The request is valid but the tool cannot do it, e.g. an unsupported image format.
`DNS_FAILURE`	422	The host has no address records.
`EMPTY_CONTENT`	422	The page had no readable text. It may need JavaScript; try a screenshot.
`RATE_LIMITED`	429	The client is over its quota. Wait for `error.retry_after_s` (also sent as Retry-After).
`UPSTREAM_UNAVAILABLE`	502	The data source failed. Retry when `error.retryable` is true.
`UNAVAILABLE`	503	The feature is not enabled on this deployment.
`TIMEOUT`	504	The data source did not answer in time. Usually safe to retry.
`INTERNAL`	500	Something broke on our side. Details are logged, not returned.

Limits and fair use

Anonymous clients: 30 units per minute and 1,000 units per day, counted per client IP.
Each tool lists its cost in units. Most cost 1. Browser and multi-stop tools cost more.
Request bodies up to 256 KB. Binary outputs up to 1 MB are returned inline as base64.
Upstream calls time out after 10 to 30 seconds, depending on the source.

The full policy is on the fair-use page.

Versions and changes

Each tool reports its meta.version. A change that breaks an existing input or output ships under a new tool name, and the old one keeps working. Additive fields may appear at any time, so ignore fields you do not know.

Machine-readable

agent-card.json: the A2A agent card, one skill per tool.
openapi.json: OpenAPI 3.1 for every endpoint.
tools.json: the full catalog, with input schemas and examples.
llms.txt: a plain-text index for language models.