Describe tool

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

← All Meta tools endpoints · Capability overview

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"
        }
      }
    ]
  }
}