Retrieve tool schemas available to the agent and proxy web fetch requests through the backend.

Overview

The Tools API exposes two capabilities: fetching the schemas for all tools the agent can invoke, and a server-side web fetch proxy that converts raw HTML into clean readable text.

Schema List

GET/tools

Returns the JSON Schema definitions for all built-in tools available to the agent.

Response fields

toolsarray

Tool definitions. Each includes name, description, and input_schema.

countnumber

Total number of tools returned.

GET /tools
Authorization: Bearer YOUR_API_KEY

{
  "tools": [
    {
      "name": "read_file",
      "description": "Read the contents of a file at the given path.",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": { "type": "string", "description": "Relative path to the file" }
        },
        "required": ["path"]
      }
    }
  ],
  "count": 31
}

Schema List with Validation

GET/tools/v2

Identical to v1 but each schema includes an additional validation block with constraints the agent must respect (e.g. path restrictions, size limits, permission requirements).

Response fields

toolsarray

Tool definitions. Each includes name, description, input_schema, and a validation block.

countnumber

Total number of tools returned.

schema_versionstring

Schema version identifier — "2" for this endpoint.

GET /tools/v2
Authorization: Bearer YOUR_API_KEY

{
  "tools": [
    {
      "name": "write_file",
      "description": "Write content to a file.",
      "input_schema": { ... },
      "validation": {
        "requires_permission": true,
        "max_bytes": 524288,
        "blocked_paths": [".env", ".misar/hooks/"]
      }
    }
  ],
  "count": 31,
  "schema_version": "2"
}

Use v2 when building custom agent integrations that need to enforce permission gates or size limits before sending tool results back to the backend.

Web Fetch Proxy

POST/tools/web-fetch

Fetch a URL server-side and receive clean, readable text. The proxy strips navigation, ads, and boilerplate, returning only the main content — suitable for injecting into an agent's context.

Request body

urlstringbodyrequired

URL to fetch. Must be HTTPS.

max_bytesnumberbodydefault: 10240

Maximum response size in bytes (max: 10 KB).

Response fields

urlstring

The URL that was fetched (may differ from input if redirected).

titlestring

Page title extracted from the HTML.

contentstring

Main page content converted to readable plain text.

content_bytesnumber

Size of the returned content in bytes.

fetched_atstring

ISO 8601 timestamp of when the fetch occurred.

POST /tools/web-fetch
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "url": "https://docs.example.com/api/authentication",
  "max_bytes": 10240
}

{
  "url": "https://docs.example.com/api/authentication",
  "title": "Authentication — Example Docs",
  "content": "## Authentication\n\nAll requests require a Bearer token...",
  "content_bytes": 3412,
  "fetched_at": "2026-03-21T15:00:00Z"
}

Only HTTPS URLs are accepted. HTTP URLs and private network addresses (localhost, RFC 1918 ranges) are rejected with a 400 error.

Status codes

400 — Invalid URL, HTTP URL, or private network address.
422 — URL is reachable but returned non-HTML content.
502 — Upstream fetch failed or timed out.
429 — Rate limit exceeded.