Meta tools

Tools to help discover and introspect the Vee3 catalog.

GET/v1/meta-tools/tool

https://api.vee3.io/v1/meta-tools/tool

0 tokens

Return the full schema, examples, and token cost for one capability.

Authorization

Send your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

MCP

The same capability is available as an MCP tool on Vee3 hosted MCP.

Tool name

describe_tool

Parameters1 field

capability_idstringRequired

Capability id to describe (for example website-screenshot).

max length 128

Response53 fields

capability_idstring

Described capability id.

toolobject

51 fields

Full capability detail including fields, examples, and bindings.

capability_idstring

Capability id (for example website-screenshot).

group_idstring

Capability group id.

group_display_namestring

Human-readable group name.

display_namestring

Human-readable capability name.

summarystring

Short capability summary.

statusstring

Capability status (live, soon, or deprecated).

rest_methodstring

HTTP method for the REST endpoint.

rest_pathstring

REST path for the capability.

mcp_tool_namestring

MCP tool name when the capability is exposed over MCP.

token_costinteger

API tokens charged for one successful call.

agent_descriptionstring

Longer description intended for agents.

usage_unit_labelstring

Label for usage reporting (for example screenshots).

request_fieldsarrayitems

13 fields

Request parameter schema for the capability.

namestring

Request parameter name.

type_namestring

Parameter type (string, integer, boolean, or enum).

descriptionstring

Parameter description.

requiredboolean

Whether the parameter is required.

defaultstring

Default value when omitted, or null when none.

surfacesarrayitems

1 field

Surfaces where the parameter applies.

surfacestring

rest or mcp.

enum_valuesarrayitems

1 field

Allowed enum values when type_name is enum.

valuestring

Allowed enum value.

constraintsobject

3 fields

Optional numeric or length limits.

minimuminteger

Minimum allowed numeric value when set.

maximuminteger

Maximum allowed numeric value when set.

max_lengthinteger

Maximum allowed string length when set.

response_fieldsarrayitems

7 fields

Response field schema for the capability.

namestring

Response field name.

type_namestring

Field type (string, integer, boolean, enum, array, or object).

descriptionstring

Field description.

childrenarrayitems

3 fields

Nested response field specs when type_name is array or object. Items use the same shape and may nest further.

namestring

Response field name.

type_namestring

Field type (string, integer, boolean, enum, array, or object).

descriptionstring

Field description.

error_codesarrayitems

1 field

Error codes that may appear in error responses.

error_codestring

Machine-readable error code.

success_body_codesarrayitems

1 field

Non-error body codes that may appear on HTTP 200 responses.

body_codestring

Machine-readable success-body code.

examplesarrayitems

6 fields

Request examples for the capability.

namestring

Example identifier.

descriptionstring

What the example demonstrates.

request_bodyobject

1 field

Sample request payload for the capability.

parameterstring

Capability-specific request parameter documented in the example.

surfacesarrayitems

1 field

Surfaces where the example applies.

surfacestring

rest or mcp.

response_examplesarrayitems

5 fields

Response examples for the capability.

namestring

Example identifier.

descriptionstring

What the example demonstrates.

status_codeinteger

HTTP status code for the example response.

response_bodyobject

1 field

Sample response payload for the capability.

fieldstring

Capability-specific response field documented in the example.

HTTP errors: unauthorized, not_found, validation_error

Example request

Python

import requests

url = "https://api.vee3.io/v1/meta-tools/tool"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
}
params = {
    "url": "https://example.com"
}

response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
data = response.json()
print(data)

Example responses1 example

200Full schema and bindings for the website screenshot capability.

website_screenshot.json

{
  "capability_id": "website-screenshot",
  "tool": {
    "capability_id": "website-screenshot",
    "group_id": "website-screenshots",
    "group_display_name": "Website Screenshots",
    "display_name": "Website screenshots",
    "summary": "Capture any public URL - viewport, full page, signed PNG or JPEG.",
    "agent_description": "Capture a screenshot of a public website...",
    "usage_unit_label": "screenshots",
    "status": "live",
    "rest_method": "POST",
    "rest_path": "/v1/website-screenshots/screenshot",
    "mcp_tool_name": "capture_website_screenshot",
    "token_cost": 20,
    "request_fields": [
      {
        "name": "url",
        "type_name": "string",
        "description": "Public http or https URL to capture.",
        "required": true,
        "default": null,
        "surfaces": [
          "mcp",
          "rest"
        ],
        "constraints": {
          "minimum": null,
          "maximum": null,
          "max_length": 2048
        }
      },
      {
        "name": "return_mode",
        "type_name": "enum",
        "description": "How to deliver the result.",
        "required": false,
        "default": "both",
        "surfaces": [
          "mcp",
          "rest"
        ],
        "enum_values": [
          "url",
          "image",
          "both"
        ]
      }
    ],
    "response_fields": [
      {
        "name": "screenshot_id",
        "type_name": "string",
        "description": "Unique identifier, prefix ss_."
      },
      {
        "name": "screenshot_url",
        "type_name": "string",
        "description": "Signed GCS URL, valid for about 1 hour."
      }
    ],
    "error_codes": [
      "unauthorized",
      "url_blocked",
      "screenshot_timeout"
    ],
    "success_body_codes": [
      "inline_image_unavailable"
    ],
    "examples": [
      {
        "name": "basic_viewport",
        "description": "Capture the default viewport after DOM content loaded.",
        "request_body": {
          "url": "https://example.com",
          "wait_until": "domcontentloaded"
        },
        "surfaces": [
          "rest"
        ]
      }
    ],
    "response_examples": [
      {
        "name": "signed_url",
        "description": "Response when return_mode is url.",
        "status_code": 200,
        "response_body": {
          "screenshot_id": "ss_example01abcdef12",
          "status": "completed",
          "url": "https://example.com",
          "screenshot_url": "https://storage.googleapis.com/vee3-screenshots/ss_example01abcdef12.png?X-Goog-Signature=...",
          "return_mode": "url"
        }
      }
    ]
  }
}

GET/v1/meta-tools/token-balance

https://api.vee3.io/v1/meta-tools/token-balance

0 tokens

Return monthly token allowance, usage, remaining balance, and reset time.

Authorization

Send your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

MCP

The same capability is available as an MCP tool on Vee3 hosted MCP.

Tool name

get_token_balance

Parameters0 fields

Response7 fields

billing_planstring

Current billing plan id (free, starter, pro, scale).

monthly_token_allowanceinteger

Total tokens included in the current billing period.

tokens_usedinteger

Tokens consumed in the current billing period.

tokens_remaininginteger

Tokens left before quota is exhausted.

billing_period_startstring

ISO 8601 start of the current billing period.

billing_period_endstring

ISO 8601 end of the current billing period.

billing_period_resets_atstring

ISO 8601 timestamp when the token allowance resets (same as period end).

HTTP errors: unauthorized, payment_required

Example request

Python

import requests

url = "https://api.vee3.io/v1/meta-tools/token-balance"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
}
params = {
    "url": "https://example.com"
}

response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
data = response.json()
print(data)

Example responses1 example

200Token allowance and usage for a free-plan account mid-period.

free_plan_balance.json

{
  "billing_plan": "free",
  "monthly_token_allowance": 1000,
  "tokens_used": 120,
  "tokens_remaining": 880,
  "billing_period_start": "2026-05-01T00:00:00Z",
  "billing_period_end": "2026-06-01T00:00:00Z",
  "billing_period_resets_at": "2026-06-01T00:00:00Z"
}

GET/v1/meta-tools/tools

https://api.vee3.io/v1/meta-tools/tools

0 tokens

Return every live Vee3 capability and MCP tool name available to agents.

Authorization

Send your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

MCP

The same capability is available as an MCP tool on Vee3 hosted MCP.

Tool name

list_all_tools

Parameters0 fields

Response11 fields

toolsarrayitems

10 fields

Live tool summaries for every capability exposed to agents.

capability_idstring

Capability id (for example website-screenshot).

group_idstring

Capability group id.

group_display_namestring

Human-readable group name.

display_namestring

Human-readable capability name.

summarystring

Short capability summary.

statusstring

Capability status (live, soon, or deprecated).

rest_methodstring

HTTP method for the REST endpoint.

rest_pathstring

REST path for the capability.

mcp_tool_namestring

MCP tool name when the capability is exposed over MCP.

token_costinteger

API tokens charged for one successful call.

HTTP errors: unauthorized, insufficient_tokens, payment_required

Example request

Python

import requests

url = "https://api.vee3.io/v1/meta-tools/tools"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
}
params = {
    "url": "https://example.com"
}

response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
data = response.json()
print(data)

Example responses1 example

200All live capabilities exposed to agents.

live_tools.json

{
  "tools": [
    {
      "capability_id": "list-all-tools",
      "group_id": "meta-tools",
      "group_display_name": "Meta tools",
      "display_name": "List all tools",
      "summary": "Return every live Vee3 capability and MCP tool name available to agents.",
      "status": "live",
      "rest_method": "GET",
      "rest_path": "/v1/meta-tools/tools",
      "mcp_tool_name": "list_all_tools",
      "token_cost": 0
    },
    {
      "capability_id": "website-screenshot",
      "group_id": "website-screenshots",
      "group_display_name": "Website Screenshots",
      "display_name": "Website screenshots",
      "summary": "Capture any public URL - viewport, full page, signed PNG or JPEG.",
      "status": "live",
      "rest_method": "POST",
      "rest_path": "/v1/website-screenshots/screenshot",
      "mcp_tool_name": "capture_website_screenshot",
      "token_cost": 20
    }
  ]
}

GET/v1/meta-tools/group-tools

https://api.vee3.io/v1/meta-tools/group-tools

0 tokens

Return every live tool in one capability group.

Authorization

Send your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

MCP

The same capability is available as an MCP tool on Vee3 hosted MCP.

Tool name

list_group_tools

Parameters1 field

group_idstringRequired

Group id to list tools for (for example website-screenshots).

max length 128

Response12 fields

group_idstring

Requested group id.

toolsarrayitems

10 fields

Live tool summaries in the requested group.

capability_idstring

Capability id (for example website-screenshot).

group_idstring

Capability group id.

group_display_namestring

Human-readable group name.

display_namestring

Human-readable capability name.

summarystring

Short capability summary.

statusstring

Capability status (live, soon, or deprecated).

rest_methodstring

HTTP method for the REST endpoint.

rest_pathstring

REST path for the capability.

mcp_tool_namestring

MCP tool name when the capability is exposed over MCP.

token_costinteger

API tokens charged for one successful call.

HTTP errors: unauthorized, not_found, validation_error

Example request

Python

import requests

url = "https://api.vee3.io/v1/meta-tools/group-tools"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
}
params = {
    "url": "https://example.com"
}

response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
data = response.json()
print(data)

Example responses1 example

200Live tools in the website-screenshots group.

website_screenshots_group.json

{
  "group_id": "website-screenshots",
  "tools": [
    {
      "capability_id": "website-screenshot",
      "group_id": "website-screenshots",
      "group_display_name": "Website Screenshots",
      "display_name": "Website screenshots",
      "summary": "Capture any public URL - viewport, full page, signed PNG or JPEG.",
      "status": "live",
      "rest_method": "POST",
      "rest_path": "/v1/website-screenshots/screenshot",
      "mcp_tool_name": "capture_website_screenshot",
      "token_cost": 20
    }
  ]
}

GET/v1/meta-tools/groups

https://api.vee3.io/v1/meta-tools/groups

0 tokens

Return every capability group with summaries and live tool counts.

Authorization

Send your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

MCP

The same capability is available as an MCP tool on Vee3 hosted MCP.

Tool name

list_groups

Parameters0 fields

Response5 fields

groupsarrayitems

4 fields

Capability groups with live tool counts.

group_idstring

Group id (for example website-screenshots).

display_namestring

Human-readable group name.

summarystring

Short group summary.

live_tool_countinteger

Number of live capabilities in the group.

HTTP errors: unauthorized

Example request

Python

import requests

url = "https://api.vee3.io/v1/meta-tools/groups"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
}
params = {
    "url": "https://example.com"
}

response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
data = response.json()
print(data)

Example responses1 example

200All capability groups with live tool counts.

catalog_groups.json

{
  "groups": [
    {
      "group_id": "meta-tools",
      "display_name": "Meta tools",
      "summary": "Discovery and introspection helpers for agents.",
      "live_tool_count": 5
    },
    {
      "group_id": "website-screenshots",
      "display_name": "Website Screenshots",
      "summary": "Capture screenshots of public websites.",
      "live_tool_count": 1
    }
  ]
}