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

meta-tools.describe

Parameters1 field

tool_namestringRequired

MCP tool name (for example `x-twitter.create_post`) or capability id (for example `create-x-post`).

max length 128

Response46 fields

capability_idstring

Described capability id.

toolobject

44 fields

Full capability detail including fields, examples, and bindings.

mcp_tool_namestring

MCP tool name when the capability is exposed over MCP.

group_idstring

Capability group id.

summarystring

Short capability summary.

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.

defaultscalar

Default value when omitted (string, integer, or boolean), 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 = {
    "tool_name": "website-screenshots.capture"
}

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": "website-screenshots.capture",
    "token_cost": 20,
    "request_fields": [
      {
        "name": "url",
        "type_name": "string",
        "description": "Public http or https URL to capture.",
        "required": true,
        "default": null,
        "surfaces": [
          {
            "surface": "mcp"
          },
          {
            "surface": "rest"
          }
        ],
        "constraints": {
          "minimum": null,
          "maximum": null,
          "max_length": 2048
        }
      },
      {
        "name": "file_name",
        "type_name": "string",
        "description": "Optional account-relative storage path for the screenshot.",
        "required": false,
        "default": null,
        "surfaces": [
          {
            "surface": "mcp"
          },
          {
            "surface": "rest"
          }
        ],
        "constraints": {
          "minimum": null,
          "maximum": null,
          "max_length": 255
        }
      }
    ],
    "response_fields": [
      {
        "name": "screenshot_id",
        "type_name": "string",
        "description": "Unique identifier, prefix ss_."
      },
      {
        "name": "screenshot_url",
        "type_name": "string",
        "description": "Signed download URL from account file storage."
      },
      {
        "name": "download_code",
        "type_name": "string",
        "description": "Short code to pass to vee3-get-file."
      }
    ],
    "error_codes": [
      {
        "error_code": "unauthorized"
      },
      {
        "error_code": "url_blocked"
      },
      {
        "error_code": "screenshot_timeout"
      },
      {
        "error_code": "uploaded_file_name_in_use"
      }
    ],
    "success_body_codes": [],
    "examples": [
      {
        "name": "basic_viewport",
        "description": "Capture the default viewport after DOM content loaded.",
        "request_body": {
          "url": "https://example.com",
          "wait_until": "domcontentloaded"
        },
        "surfaces": [
          {
            "surface": "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"
        }
      }
    ]
  }
}