APIClaw

Server Details

Real-time Amazon data API built for AI agents. 200M+ products, 1B+ reviews, live BSR, pricing, and competitor data as clean JSON. 10 agent skills for market research, competitor monitoring, pricing analysis, and listing audits.

Status: Healthy
Last Tested: 2026-06-23 03:32
Transport: Streamable HTTP
URL

Glama MCP Gateway

Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.

MCP client

Glama

MCP server

Full call logging

Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.

Tool access control

Enable or disable individual tools per connector, so you decide what your agents can and cannot do.

Managed credentials

Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.

Usage analytics

See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.

100% free. Your data is private.

Tool Definition Quality

A3.6/5.0

Tool DescriptionsA

Average 4.1/5 across 35 of 35 tools scored. Lowest: 3.4/5.

Server CoherenceB

Disambiguation4/5

Most tools have distinct purposes across domains (video, ecommerce, fashion, TikTok, web scraping). However, some ambiguity exists: openapi_v2_realtime_product (legacy) and openapi_v3_realtime_product coexist, and openapi_v2_products_search vs openapi_v2_fashion_product_search could confuse agents without careful reading of descriptions.

Naming Consistency2/5

Tool names are inconsistent: most use the 'openapi_v2_' prefix (e.g., openapi_v2_categories), but several use verb-first patterns (create_video_asset, get_video_asset, poll_video_task, submit_video_generation, get_account_balance). This mix of conventions makes the naming unpredictable.

Tool Count3/5

35 tools is on the high side but acceptable given the broad scope covering multiple domains (video generation, ecommerce, fashion, TikTok, web scraping). It feels like a bundled API rather than a focused server, but each domain has a reasonable number of tools.

Completeness4/5

Each domain has good coverage: video generation has create/read/list/submit/poll, ecommerce has search/history/realtime/reviews/analysis, fashion has embeddings/searches/similarity/detection, TikTok has categories/creators/products/videos, web tools have crawl/scrape/search. Minor gaps include lack of delete operations for assets or tasks, but core workflows are covered.

Available Tools

35 tools

create_video_assetAInspect

Returns an assetId you can immediately reference in a video generation request as asset://<assetId> inside any image_url.url / video_url.url / audio_url.url field.

The provider downloads your URL asynchronously: the response status is typically Processing immediately after creation and transitions to Active within seconds. You can poll GET /openapi/v2/model/video/assets/{assetId} to observe the transition before submitting a video generation request, or submit immediately — the video generation handler will retry- or fail-fast if the asset isn't ready yet.

Available to CONTRACT-tier API keys only. Currently free; no credits are deducted for asset registration.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[Asset]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Publicly-reachable HTTPS URL of the asset file. The provider downloads it directly — the URL must require no authentication (presigned URLs are fine; private / login-walled URLs are not). After successful registration the asset is referenced from the video generation API as `asset://<assetId>`; the original URL is kept only for your own audit (we never re-fetch it).
`name`	No	Optional display name for your own bookkeeping. Has no effect on video generation; if omitted, the asset is stored and returned with `name: null`.
`assetType`	Yes	Modality of the asset — `Image`, `Video`, or `Audio`.

Tool Definition Quality

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description covers key behavioral traits: asynchronous processing, status transitions, retry/fail-fast handling by video generation, and cost. It lacks details on rate limits or other constraints but is generally adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the main purpose, but it includes verbose output schema examples (200 and 422 responses) that are not needed since the tool has no separate output schema. This reduces conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (async, multi-step workflow, parameter constraints), the description is complete. It covers usage pattern, polling interaction, tier restrictions, cost, and return value explanation, providing all necessary context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds significant context beyond the schema, such as the asset:// reference format, URL accessibility requirements, and the purpose of the name parameter. This greatly aids agent understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Register a public URL as a video-generation asset.' It explains the returned assetId and how it is used in generation requests, distinguishing it from sibling tools like submit_video_generation and get_video_asset.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use this tool, including the asynchronous download, polling options, and submission timing. It mentions the CONTRACT-tier key requirement but does not explicitly exclude non-contract users or mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_account_balanceAInspect

Get account billing balance

Returns the authenticated user's billing balance. CONTRACT-tier (USD wallet) customers receive a usd view; all other tiers receive a credits view in external decimal credits.

Polling this endpoint is the only way for CONTRACT-tier customers to observe their USD balance — per-call responses on other endpoints intentionally omit balance fields (ADR-0005 §5).

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "title": "Data",
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[Union[UsdAccountBalance, CreditAccountBalance]]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Tool Definition Quality

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully carries the burden of behavioral disclosure. It clearly states it is a read operation (returns balance), indicates no destructive side effects, and explains the different responses per tier ('...CONTRACT-tier... receive usd view; all other tiers receive a credits view'). It also mentions that this endpoint is the only way for CONTRACT-tier to observe their balance, adding important context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is overly verbose, including extensive output schema JSON and detailed explanations of meta fields. While structured, it could be significantly shortened without losing essential information. Every sentence does not earn its place; for example, the detailed credit fields description is excessive for tool selection.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and an output schema is provided, the description is complete. It covers the purpose, behavior, response structure (including example), and special use cases (CONTRACT-tier). The provided output schema ensures the agent knows what to expect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the input schema provides no information. Per rubric, with 0 parameters the baseline is 4. The description does not need to add parameter semantics, and it correctly avoids inventing unnecessary details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The title 'Get account billing balance' clearly states the verb and resource. The description elaborates on the purpose: retrieving the authenticated user's billing balance, with distinct views for different tiers. No sibling tool is balance-related, so it is well-distinguished.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly guides usage by stating that polling is the only way for CONTRACT-tier customers to observe their USD balance. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it. While adequate, it could be more explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_video_assetAInspect

Get a video-generation asset by id

Fetch a single asset's metadata and live status.

Returns 404 if the asset doesn't exist or belongs to another customer (we deliberately do not distinguish to avoid leaking asset-id existence across tenant boundaries).

Available to CONTRACT-tier API keys only.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[Asset]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`asset_id`	Yes

Tool Definition Quality

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavioral traits: returns 404 for missing or cross-tenant assets, and is available only to CONTRACT-tier keys. This adds value beyond the tool name and schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core description is concise and front-loaded. The extensive output schema and examples are provided as additional info but are not part of the description proper. The description itself is efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool (1 parameter, no nested objects), the description covers purpose, behavior, restrictions, and notes that it returns metadata and live status. The output schema is provided separately, so the description is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 0% description coverage and the description adds no details about the asset_id parameter (e.g., format, length). The parameter is straightforward but the description misses an opportunity to clarify its semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets a video-generation asset by ID and fetches metadata and live status. This distinguishes it from siblings like list_video_assets (which lists multiple) and poll_video_task (which polls generation tasks).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates when to use (fetch single asset) and notes security behavior (404 to avoid leaking existence) and access restriction (CONTRACT-tier). It does not explicitly compare to siblings but provides enough context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_video_assetsAInspect

List your video-generation assets

List the calling customer's assets, newest first.

Listing is served entirely from our local registry — the live provider status is intentionally not joined per-item to keep the listing fast and cheap. Items therefore omit the status field (see AssetListItem in the response schema); call GET /openapi/v2/model/video/assets/{assetId} when you need the current status of a specific asset.

Available to CONTRACT-tier API keys only.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "title": "Data",
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[list[AssetListItem]]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description
`page`	No	Page number, 1-indexed.
`pageSize`	No	Items per page (max 100).
`assetType`	No	Optional filter by modality.

Tool Definition Quality

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Explains status omission for performance, local registry usage, and alternative endpoint. No annotations provided, so description carries full burden; it does so effectively.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is well-structured but verbose, especially with full response examples and output schema that could be summarized. First sentence is clear, but overall length could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, performance characteristics, auth requirements, and alternative tool. Output schema in examples provides return info. Missing pagination details (already in schema).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Parameter descriptions in input schema are clear (page, pageSize, assetType with enum). Description adds no extra semantic value beyond schema, which has 100% coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it lists video-generation assets for the calling customer, newest first. Differentiates from get_video_asset (single asset) and create_video_asset via sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides context: listing is fast but omits status; directs to get_video_asset for status. Notes CONTRACT-tier restriction. Lacks explicit when-not-to-use but offers clear guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_categoriesAInspect

Categories V2

Query Amazon category hierarchy by ID, path, parent, or keyword.

Use this to discover category structure for filtering in other endpoints. Example: pass categoryKeyword="yoga" to find matching categories, or parentCategoryPath=["Sports & Outdoors"] to list child categories.

Query modes (mutually exclusive):

No parameters: Returns all root categories
categoryId: Get specific category by ID
categoryPath: Get specific category by path
parentCategoryId: Get children of parent category by ID
parentCategoryPath: Get children of parent category by path
categoryKeyword: Search categories by keyword

Related: /products/search and /markets/search accept categoryPath for filtering.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "title": "Data",
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[list[Category]]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`categoryId`	No	Category identifier
`marketplace`	No	Amazon marketplace code	US
`categoryPath`	No	Category hierarchy from root to current level (e.g., ['Electronics', 'Computers', 'Laptops'])
`categoryKeyword`	No	Filter by category name keyword (matches any level in category hierarchy, e.g., 'Electronics' or 'Laptops')
`parentCategoryId`	No	Parent category ID
`parentCategoryPath`	No	Parent category path

Tool Definition Quality

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description provides extensive behavioral details: response format (200 success with meta, data, error), query mode behaviors (no params returns root, categoryId returns specific, etc.). However, it lacks info on rate limits or authentication, but the read-only nature is implied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is lengthy, including full JSON responses and output schemas that could be considered verbose. However, it is well-structured with sections (query modes, examples) and front-loads the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description provides a detailed response structure including examples and meta fields. It covers all query modes and relationships to sibling tools, making it complete for understanding how to use the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all 6 parameters. The description adds context by explaining query modes, mutual exclusivity, and providing an example ('categoryKeyword="yoga"'), which meaningfully supplements the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Query Amazon category hierarchy by ID, path, parent, or keyword.' It specifies the verb (query), resource (Amazon category hierarchy), and methods. It also distinguishes from sibling tools by noting related endpoints like /products/search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use this to discover category structure for filtering in other endpoints.' It enumerates mutually exclusive query modes and gives an example. It mentions related tools but could more explicitly state when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_competitorsAInspect

Competitor Lookup V2

Search competitor products by keyword, brand, ASIN, or category with filters.

Use this to identify competing products around a specific listing or brand. Example: pass asin="B07FR2V8SH" to find all products competing in the same keywords and category. Data is based on the latest daily snapshot; results are paginated (max 100 per page). Related: /products/search for broader keyword discovery.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "title": "Data",
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[list[Product]]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`asin`	No	Amazon Standard Identification Number (10-char alphanumeric). Example: 'B07FR2V8SH'.
`page`	No	Page number
`badges`	No	Include products with these badges. Example: ['bestSeller', 'amazonChoice', 'newRelease', 'aPlus', 'video'].
`sortBy`	No	Sort field	monthlySalesFloor
`keyword`	No	Search keyword
`pageSize`	No	Page size
`brandName`	No	Filter by brand name.
`dateRange`	No	Aggregation window for metrics like monthly sales, revenue, and rating count. '30d' (default) — last 30 days. 'YYYY-MM' — that calendar month, e.g. '2026-04'. Available months: '2026-02' up to the most recent completed month.	30d
`sortOrder`	No	Sort direction: asc or desc	desc
`sellerName`	No	Filter by seller name.
`marketplace`	No	Amazon marketplace code	US
`categoryPath`	No	Category hierarchy from root to current level (e.g., ['Electronics', 'Computers', 'Laptops'])
`fulfillments`	No	Fulfillment filter. Example: ['FBA', 'FBM'].
`excludeBadges`	No	Exclude products with these badges. Supported: ['aPlus', 'video'].
`excludeBrands`	No	Brand names to exclude. Example: ['Generic'].
`includeBrands`	No	Brand names to include. Example: ['Apple', 'Samsung'].
`excludeSellers`	No	Seller names to exclude.
`includeSellers`	No	Seller names to include. Example: ['Apple Store'].
`sellerCountMax`	No	Maximum number of sellers. Example: 20.
`sellerCountMin`	No	Minimum number of sellers. Example: 1.
`excludeKeywords`	No	Keywords to exclude from results. Example: ['refurbished', 'used'].
`keywordMatchType`	No	Keyword match type: 'fuzzy', 'phrase', or 'exact'. Null = fuzzy.

Tool Definition Quality

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the description discloses key behaviors: data freshness ('latest daily snapshot'), pagination limits ('max 100 per page'), and example usage. It does not explicitly state read-only nature or authentication requirements, but these are implied by the search context. Strong disclosure given the absence of annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The descriptive text is front-loaded and efficient, but the overall description is inflated by including full response schemas (200 and 422) and extensive JSON blocks. This reduces conciseness for an agent, as the essential usage information is buried within a long document.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the complexity (22 parameters, no required, rich filtering), the description covers all essential aspects: purpose, usage, example, pagination, data snapshot, and related tools. It even includes an output schema (detected in description, despite context signal reporting false), which fully documents return values and metadata.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with detailed parameter descriptions (enums, defaults, examples). The tool description adds an example (ASIN lookup) and contextual usage, but does not further explain individual parameters beyond what the schema provides. Baseline 3 is appropriate since the schema already does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Competitor Lookup V2 - Search competitor products by keyword, brand, ASIN, or category with filters.' It specifies the resource (competitor products) and the action (search/lookup). It also distinguishes from sibling tools via a related link to a broader search endpoint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells when to use this tool: 'Use this to identify competing products around a specific listing or brand.' It provides a concrete example with ASIN and even mentions an alternative ('Related: /products/search for broader keyword discovery'), helping the agent decide between tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_ecommerce_rerankAInspect

Rerank documents for ecommerce search queries

Rerank a list of product documents by relevance to ecommerce search queries.

Use this to improve product search result ordering. Pass one or more search queries and a shared list of product documents (titles, descriptions, or concatenated attributes). The model scores each document against each query and returns them sorted by relevance. Powered by a fine-tuned Qwen3-Reranker model optimized for ecommerce product matching.

Credits: 1 credit per query in the batch. A request with 3 queries costs 3 credits.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[EcommerceRerankResult]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description
`topK`	No	Return only the top K most relevant documents per query. Omit to return all documents ranked.
`queries`	Yes	List of search queries to rerank documents against. Max 10 queries per request.
`documents`	Yes	List of document lists, one per query (documents[i] is reranked against queries[i]). Max 100 documents per query.

Tool Definition Quality

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description discloses credit costs (1 credit per query) and includes detailed output schema. It does not mention destructive actions or auth needs, but the tool is a read-only rerank, so the description is reasonably transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with clear sections and is not overly verbose. It includes necessary details like credit billing and response formats, but could be slightly more concise. Still, it is well-organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema provided separately, the description includes a full output schema, covers error responses, credit costs, and usage instructions. It is comprehensive for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for all three parameters. The description adds extra context, such as the expected content of documents (titles, descriptions, attributes) and that documents[i] reranks against queries[i], which adds value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reranks product documents for ecommerce search queries, specifying the verb (rerank), resource (documents), and context. It distinguishes from sibling tools like search and embedding endpoints by focusing on reranking and mentioning the fine-tuned Qwen3-Reranker model.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises using this tool to improve product search result ordering and explains the input format (queries and documents). It does not explicitly state when not to use it or provide alternatives, but the context among siblings implies its specialized role.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_fashion_image_embeddingAInspect

Generate fashion image embeddings (768-dim vectors for similarity search)

Generate fashion-specific image embeddings using fine-tuned SigLIP2.

Encode product images into 768-dim vectors aligned with the text embedding space. Use cases: visual similarity search, image-to-text matching, duplicate detection, catalog indexing. Accepts HTTPS URLs or base64-encoded images. Vectors are L2-normalized by default. Credits: 1 credit per request.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[FashionImageEmbeddingResult]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`imageUrls`	Yes	Product images to encode: HTTPS URLs (e.g. 'https://cdn.example.com/product.jpg') or base64-encoded strings (with optional data URI prefix). Max 8 per request. Supported formats: JPEG, PNG, WebP.
`normalizeVectors`	No	L2-normalize output vectors to unit length (default true). When true, dot product = cosine similarity.

Tool Definition Quality

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses embedding generation, L2 normalization, credit cost, and input formats. However, the response schema omits the actual embedding data structure, and there is no mention of rate limits or authentication. With no annotations, the description carries the full burden but leaves gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose but includes lengthy response examples and schemas that are partially redundant. It is moderately concise but could be more streamlined.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description covers input constraints, behavior, credit cost, and response structure reasonably well. It misses the exact embedding output format but provides enough context for most use cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description does not add significant new information beyond the schema; it reiterates input formats and default normalization. No extra clarification is needed given the schema's completeness.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'generate fashion image embeddings (768-dim vectors for similarity search)', specifying the verb, resource, and dimensionality. The distinction from sibling tools like openapi_v2_image_embedding is implied by the fashion-specific focus.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Lists specific use cases (visual similarity search, image-to-text matching, etc.) and input constraints (URLs/base64, max 8 images). However, does not explicitly contrast with sibling tools for when to use this versus the general image embedding tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_fashion_image_searchAInspect

Search fashion products by image similarity

Search fashion products by visual similarity to a query image.

Upload an image URL to find visually similar fashion products across the catalog. Optionally specify a bounding box to focus on a specific item in the image, and add a text description for better matching.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[FashionImageSearchResult]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description
`bbox`	No	Crop region [x1, y1, x2, y2] in pixels to focus on a specific item in the image.
`limit`	No	Maximum number of results (1-50, default 10).
`sites`	No	Retailer domain filter. Example: ['farfetch.com'].
`brands`	No	Brand name filter. Example: ['Gucci', 'Prada'].
`offset`	No	Pagination offset (default 0).
`imageUrl`	Yes	URL of the query image. Must be HTTPS.
`priceMax`	No	Maximum price in USD.
`priceMin`	No	Minimum price in USD.
`imageDescription`	No	Optional text description to compose with the image for better matching.

Tool Definition Quality

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the read-only nature implicitly (search tool) but lacks details on authentication, rate limits, or side effects. The response schema is documented but not behavioral constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is verbose, including full response examples and schemas for both 200 and 422 status codes. The core purpose is stated concisely, but the excessive detail (e.g., meta field descriptions with ADR references) makes it less efficient. Every sentence should earn its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (9 parameters, multiple filters) and no output schema, the description provides complete coverage: it explains the search functionality, optional parameters, and response structure. The inclusion of response schemas enhances completeness, though it contributes to verbosity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema; it restates some parameter descriptions but does not provide new context. Example: bbox is described as 'Crop region' in both schema and description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Search fashion products by image similarity' and 'find visually similar fashion products', specifying the verb and resource. It distinguishes from sibling text-based search tools like openapi_v2_fashion_product_search by emphasizing visual similarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use the tool: when you have an image URL to find similar fashion products. It mentions optional bounding box and text description for better matching. However, it does not explicitly state when not to use it or compare directly with alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_fashion_product_searchAInspect

Search fashion products by text query

Search fashion products by natural-language text query.

Searches across 200M+ fashion products from major retailers. Supports brand filtering, price range, and retailer domain allowlists/denylists. Results include product title, brand, price, image, and retailer link.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[FashionProductSearchResult]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description
`topK`	No	Maximum number of results to return (1-50, default 10).
`brand`	No	Filter by brand name. Example: 'Gucci'.
`query`	Yes	Natural-language fashion search query. Examples: 'women brown suede tote under 300', 'black leather ankle boots', 'men slim fit navy blazer'.
`sites`	No	Retailer domain allowlist. Example: ['farfetch.com', 'nordstrom.com'].
`priceMax`	No	Maximum price in USD. Example: 300.00.
`priceMin`	No	Minimum price in USD. Example: 50.00.
`excludeSites`	No	Retailer domain denylist. Example: ['poshmark.com'].

Tool Definition Quality

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It describes the response metadata including credits and pagination fields, but does not disclose rate limits, authentication needs, or potential destructive behaviors. It provides some behavioral context but not comprehensively.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the purpose, but it includes a lengthy output schema example that is already present in structured form. This makes the description unnecessarily verbose and harms conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 7 parameters and no output schema in structured form, the description covers the main purpose, filters, and response structure. However, it lacks details on pagination defaults, sorting, or potential errors beyond the schema, leaving minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds contextual examples for the query parameter and explains the purpose of brand, price range, and site filters. This goes beyond the schema's basic descriptions, enhancing understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches fashion products by natural-language text query, specifies it covers 200M+ products, and supports filters. It distinguishes itself from sibling tools like openapi_v2_fashion_image_search by focusing on text-based search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for text-based fashion product searches but does not explicitly state when to use this tool versus alternatives like image search or similarity. No exclusions or alternative tool names are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_fashion_similarityAInspect

Compute text-image similarity scores for fashion products

Compute cosine similarity between text queries and product images.

Encodes texts and images into the same 768-dim space, returns a score matrix. similarityScores[i][j] = relevance of textQueries[i] to imageUrls[j]. Higher = better match. Equivalent to text-embedding + image-embedding + dot product in one call. Credits: 1 credit per request.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[FashionSimilarityResult]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`imageUrls`	Yes	Product images (HTTPS URLs or base64) to compare against text queries. Max 8.
`textQueries`	Yes	Fashion text queries to compare against images (e.g. 'red summer dress'). Max 32.

Tool Definition Quality

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It explains the operation, dimensionality, equivalence to separate embeddings, credit consumption, and response structure. However, it lacks details on potential errors or limitations beyond validation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a summary, details, and response information. It is front-loaded but somewhat lengthy due to including full response schemas; still clear and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool complexity (multimodal similarity), the description adequately explains invocation, parameters, and response. With 100% schema coverage and detailed operational description, it is sufficiently complete for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers both parameters with max/min items and examples. Description adds value by clarifying imageUrls can be URLs or base64, and explaining the output matrix structure and score interpretation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool computes text-image similarity scores for fashion products using cosine similarity, and distinguishes it from sibling embedding tools by noting it's equivalent to text-embedding + image-embedding + dot product in one call.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage as a combined similarity function but does not explicitly state when to use this vs alternatives like the separate embedding tools. No when-not-to-use or exclusion criteria are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_fashion_text_embeddingAInspect

Generate fashion text embeddings (768-dim vectors for similarity search)

Generate fashion-specific text embeddings using fine-tuned SigLIP2.

Encode fashion text into 768-dim vectors aligned with the image embedding space. Use cases: text-to-image search, semantic product matching, catalog indexing. Vectors are L2-normalized by default (dot product = cosine similarity). Credits: 1 credit per request.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[FashionTextEmbeddingResult]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`queries`	Yes	Fashion text queries to encode. Examples: product titles ('Women Red Floral Midi Dress'), search queries ('casual summer outfit'), or attributes ('cotton, v-neck, knee-length'). Max 32 per request.
`normalizeVectors`	No	L2-normalize output vectors to unit length (default true). When true, dot product = cosine similarity.

Tool Definition Quality

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses key behavioral traits: vectors are L2-normalized by default, 1 credit per request, and output is 768-dimensional. It also explains the response structure through the inline schema. However, with no annotations, it could have clarified rate limits, authentication, or error behavior beyond validation errors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is overly long, repeating extensive response schemas that could be separate. The core description is relatively clear, but the inclusion of full JSON schemas for success and error responses makes it verbose and less concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers inputs, normalization, credits, use cases, and response structure. It is fairly complete for a complex embedding tool, though it lacks details on error handling beyond validation errors and does not mention any prerequisites or limitations like model availability.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides full descriptions for both parameters, including examples for 'queries' and default value for 'normalizeVectors'. The description adds minimal extra value, only restating normalization behavior. Given 100% schema coverage, a score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool generates fashion-specific text embeddings (768-dimensional vectors) using SigLIP2, with specific use cases like text-to-image search. The tool name itself indicates 'fashion_text_embedding', and the description distinguishes it from sibling image embedding tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While the description lists use cases (text-to-image search, semantic product matching, catalog indexing), it does not explicitly state when to prefer this tool over alternatives like openapi_v2_fashion_image_embedding or when not to use it. The distinction is implied through the name and the focus on text input, but missing explicit guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_image_detectionBInspect

Detect fashion items in images

Detect fashion items in an image and return their bounding boxes.

Analyzes an image to locate fashion items such as bags, shoes, clothing, watches, glasses, and jewelry. Returns bounding box coordinates, category classification, and confidence scores for each detected item. Use the classes parameter to filter for specific fashion categories. Credits: 1 credit per request.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[ImageDetectionResult]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description
`topK`	Yes	Maximum number of detections to return.
`image`	Yes	URL of the image to analyze. Must be a publicly accessible HTTPS URL.
`classes`	No	Fashion category class IDs to detect. Omit to detect all categories. Values: 0=Bag, 1=Cap, 2=Down-Clothing, 3=Glasses, 4=Jewelry, 5=Others, 6=Shoes, 7=Sock, 8=Up-Clothing, 9=Watch.
`timeout`	No	Request timeout in seconds. The request will be aborted if the upstream service does not respond within this time.
`returnImage`	No	Whether to return the annotated image with bounding boxes drawn.

Tool Definition Quality

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden for behavioral disclosure. It mentions credit consumption (1 credit per request) and provides a response structure example. However, it does not discuss auth requirements, error handling beyond validation, or behavior on invalid images, which are gaps for a fully transparent description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with a brief summary, a detailed paragraph, and a response section with JSON examples. However, it is somewhat verbose, particularly in the response schema examples which could be streamlined. Not maximally concise but adequately organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema is provided, so the description must explain return values. It gives an example response but only fully describes 'meta' and error schemas; the actual detection results under 'data' are vaguely described as 'Response data payload'. This leaves the agent without full understanding of the output structure for detected items, making it incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema description coverage is 100% (all 5 parameters are described in the schema). The description adds context about using 'classes' for filtering and mentions output bounding boxes, but does not significantly expand on parameter semantics beyond what the schema already provides. Baseline score of 3 is appropriate given full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool detects fashion items in images, specifying the verb 'detect' and the resource 'fashion items in images'. It lists example items (bags, shoes, etc.) and output types (bounding boxes, categories, confidence scores), distinguishing it from sibling tools like embedding or search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises using the 'classes' parameter to filter categories, providing some guidance on usage. However, it does not explicitly state when to use this tool versus alternatives (e.g., fashion_image_search) or when not to use it. It lacks exclusions or comparative guidance for sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_image_embeddingBInspect

Generate fashion item embeddings from images

Generate feature embeddings for fashion items detected in an image.

Automatically detects fashion items (bags, shoes, clothing, watches, etc.) in the image and generates feature embedding vectors for each detected item. Embeddings can be used for visual similarity search, product recommendations, and image-based product matching. Optionally include fashion category tags and text-image relevance scores. Credits: 1 credit per request.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[ImageEmbeddingResult]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description
`text`	No	Text(s) for computing text-image relevance scores. Omit to skip relevance scoring.
`topK`	No	Maximum number of detected items to return. Omit to return all detections.
`image`	Yes	URL of the image to analyze. Must be a publicly accessible HTTPS URL.
`timeout`	No	Request timeout in seconds. The request will be aborted if the upstream service does not respond within this time.
`withTag`	No	Whether to include fashion category tags (e.g. Bag, Shoes, Watch) in the response.
`boundingBoxes`	No	Pre-defined bounding boxes as [[x1, y1, x2, y2], ...]. Omit for automatic detection.
`withEmbedding`	No	Whether to include feature embedding vectors in the response.

Tool Definition Quality

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the tool automatically detects fashion items, generates embeddings, optionally includes tags and relevance scores, and costs 1 credit per request. However, it does not mention auth requirements, rate limits, or behavior upon processing failure (e.g., what happens if the image URL is invalid). The response format is included, which adds value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is lengthy due to inclusion of full response examples and output schemas (though output schema is not formally present). The first paragraph is concise and informative, but the later sections are verbose. The structure is organized with headers, but overall could be more concise by omitting repetitive schema details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 7 parameters (1 required) and no formal output schema, the description covers the purpose, automatic detection, optional features, and credit cost. However, it lacks specifics about the embedding vector format (e.g., dimensions) and does not explain the timeout parameter or bounding boxes parameter in the description. The response schema is provided inline, which helps, but missing details on error handling beyond the 422 example.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, meaning all parameters are already described in the input schema. The description adds minor context by mentioning optional tags and relevance scores (mapping to withTag and text) and the maximum number of items (topK), but it largely repeats what the schema provides. No additional parameter usage details or examples are given beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with 'Generate fashion item embeddings from images' which clearly states the verb (generate) and resource (fashion item embeddings). It further explains the tool detects fashion items and generates vectors, distinguishing it from search tools like openapi_v2_fashion_image_search. However, the sibling tool 'openapi_v2_fashion_image_embedding' exists, causing potential confusion despite the description's focus on fashion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions that embeddings can be used for 'visual similarity search, product recommendations, and image-based product matching,' implying usage context. However, it does not explicitly state when to use this tool versus alternatives like openapi_v2_fashion_image_search or openapi_v2_fashion_similarity. No exclusions or when-not-to-use guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_markets_searchAInspect

Markets Search V2

Search market data by category with aggregated demand, competition, and pricing metrics.

Use this to evaluate market size and competition before entering a niche. Example: search "Pet Supplies" with sampleAvgMonthlySalesMin >= 200 to find categories with proven demand. Data is based on top-100 product samples per category from the latest daily snapshot; results paginated (max 100 per page). Related: /products/search for product-level data in a category.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "title": "Data",
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[list[Market]]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`page`	No	Page number
`topN`	No	Number of top products to analyze: '3', '5', '10', or '20'. Affects top* response fields (e.g., topAvgMonthlySales)	10
`sortBy`	No	Sort field (matches response field names)	sampleAvgMonthlyRevenue
`pageSize`	No	Page size
`dateRange`	No	Aggregation window for metrics like monthly sales, revenue, and rating count. '30d' (default) — last 30 days. 'YYYY-MM' — that calendar month, e.g. '2026-04'. Available months: '2026-02' up to the most recent completed month.	30d
`sortOrder`	No	Sort direction: asc or desc	desc
`sampleType`	No	Sampling method for market metrics: 'bySale100' = analyze top 100 products by sales volume, 'byBsr100' = top 100 by BSR rank, 'avg' = category-wide average	bySale100
`marketplace`	No	Amazon marketplace code.	US
`categoryPath`	No	Category hierarchy from root. Example: ['Electronics', 'Computers', 'Laptops'].
`topAvgBsrMax`	No	Maximum Top N average main-category BSR.
`topAvgBsrMin`	No	Minimum Top N average main-category BSR.
`categoryKeyword`	No	Filter by category name keyword (matches any level in category hierarchy, e.g., 'Electronics' or 'Laptops')
`sampleAvgBsrMax`	No	Maximum sample average main-category BSR.
`sampleAvgBsrMin`	No	Minimum sample average main-category BSR (lower = better).
`topSalesRateMax`	No	Maximum Top N sales share as decimal.
`topSalesRateMin`	No	Minimum Top N sales share as decimal. Example: 0.5 = 50%.
`newProductPeriod`	No	Define 'new product' as listed within X months: '1', '3', '6', or '12'. Affects sampleNewSku* response fields	3
`sampleAmzRateMax`	No	Maximum sample Amazon-sold product rate as decimal.
`sampleAmzRateMin`	No	Minimum sample Amazon-sold product rate as decimal.
`sampleFbaRateMax`	No	Maximum sample FBA product rate as decimal.
`sampleFbaRateMin`	No	Minimum sample FBA product rate as decimal.
`totalSkuCountMax`	No	Maximum total SKU count in category.
`totalSkuCountMin`	No	Minimum total SKU count in category.
`sampleAvgPriceMax`	No	Maximum sample average price.
`sampleAvgPriceMin`	No	Minimum sample average price. Example: 10.00.
`sampleSkuCountMax`	No	Maximum sample SKU count.
`sampleSkuCountMin`	No	Minimum sample SKU count.
`sampleAvgRatingMax`	No	Maximum sample average star rating (0.0–5.0).
`sampleAvgRatingMin`	No	Minimum sample average star rating (0.0–5.0).
`sampleBrandCountMax`	No	Maximum sample unique brand count.
`sampleBrandCountMin`	No	Minimum sample unique brand count.
`sampleNewSkuRateMax`	No	Maximum sample new product rate as decimal.
`sampleNewSkuRateMin`	No	Minimum sample new product rate as decimal.
`sampleNewSkuCountMax`	No	Maximum sample new product count.
`sampleNewSkuCountMin`	No	Minimum sample new product count.
`sampleSellerCountMax`	No	Maximum sample unique seller count.
`sampleSellerCountMin`	No	Minimum sample unique seller count.
`topBrandSalesRateMax`	No	Maximum Top N brand concentration ratio as decimal.
`topBrandSalesRateMin`	No	Minimum Top N brand concentration ratio as decimal.
`topAvgMonthlySalesMax`	No	Maximum Top N average monthly sales.
`topAvgMonthlySalesMin`	No	Minimum Top N average monthly sales. Units sold.
`topSellerSalesRateMax`	No	Maximum Top N seller concentration ratio as decimal.
`topSellerSalesRateMin`	No	Minimum Top N seller concentration ratio as decimal.
`sampleAvgRatingCountMax`	No	Maximum sample average rating count per product.
`sampleAvgRatingCountMin`	No	Minimum sample average rating count per product.
`sampleNewSkuAvgPriceMax`	No	Maximum new product average price.
`sampleNewSkuAvgPriceMin`	No	Minimum new product average price.
`topAvgMonthlyRevenueMax`	No	Maximum Top N average monthly revenue.
`topAvgMonthlyRevenueMin`	No	Minimum Top N average monthly revenue.
`sampleAvgMonthlySalesMax`	No	Maximum sample average monthly sales. Units sold.
`sampleAvgMonthlySalesMin`	No	Minimum sample average monthly sales. Units sold. Example: 100.
`sampleAvgPackageVolumeMax`	No	Maximum sample average package volume in in³.
`sampleAvgPackageVolumeMin`	No	Minimum sample average package volume in in³.
`sampleAvgPackageWeightMax`	No	Maximum sample average package weight in oz.
`sampleAvgPackageWeightMin`	No	Minimum sample average package weight in oz.
`sampleAvgMonthlyRevenueMax`	No	Maximum sample average monthly revenue.
`sampleAvgMonthlyRevenueMin`	No	Minimum sample average monthly revenue. Example: 5000.00.
`sampleNewSkuAvgMonthlySalesMax`	No	Maximum new product average monthly sales.
`sampleNewSkuAvgMonthlySalesMin`	No	Minimum new product average monthly sales.

Tool Definition Quality

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description discloses key behaviors: data is based on top-100 product samples from latest daily snapshot, results are paginated (max 100 per page). However, it does not mention authentication requirements, rate limits, or other potential side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core description is front-loaded and clear, but it is followed by verbose inline JSON schemas for responses (including both 200 and 422). This redundancy makes the description longer than necessary, though the first paragraph is concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the high parameter count (59) and lack of separate output schema, the description includes response schemas and example responses, covering meta fields and error structure. However, the data payload inside the success response is not fully detailed (just 'data' as object), leaving some ambiguity about the actual market fields returned.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by providing an example usage and explaining the dateRange parameter format in detail (e.g., '30d' or 'YYYY-MM'). This enhances understanding beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches market data by category with aggregated demand, competition, and pricing metrics. It provides a specific verb (search) and resource (markets), and distinguishes from related tool /products/search for product-level data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use this to evaluate market size and competition before entering a niche.' and gives a concrete example with 'sampleAvgMonthlySalesMin >= 200'. It also references an alternative tool for product-level data.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_products_historyAInspect

Product History V2

Get historical time-series data for a single ASIN over a date range.

Returns columnar arrays: high-frequency metrics (price, BSR, sales, rating, sellerCount) as daily arrays aligned with timestamps, and low-frequency fields (title, imageUrl, badges, inventoryStatus) as changelog entries that only record changes. Max date range: 730 days. Related: /products/search to discover ASINs first.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[ProductHistoryTimeSeriesItem]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`asin`	Yes	Amazon Standard Identification Number (10 chars)
`endDate`	Yes	End date in YYYY-MM-DD format
`startDate`	Yes	Start date in YYYY-MM-DD format
`marketplace`	No	Amazon marketplace code.	US

Tool Definition Quality

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Describes return format (columnar arrays for high-frequency metrics, changelog for low-frequency fields) and max date range, but does not disclose side effects, auth needs, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is overly long with repetitive response examples and output schemas that are not needed for tool selection. The core purpose is front-loaded but could be significantly trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Context says no output schema, but description explains response structure (columnar arrays, changelog entries) well. Covers max date range and data granularity. Lacks details on pagination or error handling beyond validation errors.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all 4 parameters. Description adds context: 'single ASIN', date range, max 730 days, and mentions marketplace unsupported values (UK), providing added value beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description explicitly states 'Get historical time-series data for a single ASIN over a date range' with verb + resource + scope. Differentiates from sibling tools like openapi_v2_products_search by noting '/products/search to discover ASINs first.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clearly indicates when to use (for historical data of a known ASIN) and provides a max date range (730 days). Mentions a related tool for discovery but does not explicitly list alternatives or when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_products_searchAInspect

Products Search V2

Search Amazon products by keyword, category, and multi-dimensional filters.

Use this to discover products in a specific niche, analyze competitor listings, or find high-demand low-competition opportunities. Example: search "yoga mat" in Sports & Outdoors with monthlySalesFloor >= 500 and price <= $30 to find proven sellers in an affordable range. Data is based on the latest daily snapshot; results are paginated (max 100 per page). Related: /products/competitors for competitor analysis, /products/history for trends.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "title": "Data",
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[list[Product]]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`page`	No	Page number
`badges`	No	Include products with these badges. Example: ['bestSeller', 'amazonChoice', 'newRelease', 'aPlus', 'video'].
`bsrMax`	No	Maximum Best Sellers Rank. Example: 100000.
`bsrMin`	No	Minimum Best Sellers Rank (lower = better). Example: 1.
`lqsMax`	No	Maximum Listing Quality Score
`lqsMin`	No	Minimum Listing Quality Score
`sortBy`	No	Sort field	monthlySalesFloor
`keyword`	No	Search keyword
`pageSize`	No	Page size
`priceMax`	No	Maximum product price. Example: 99.99.
`priceMin`	No	Minimum product price. Example: 9.99.
`dateRange`	No	Aggregation window for metrics like monthly sales, revenue, and rating count. Null or '30d' — last 30 days (default). 'YYYY-MM' — that calendar month, e.g. '2026-04'. Available months: '2026-02' up to the most recent completed month.
`fbaFeeMax`	No	Maximum FBA fee. Example: 15.00.
`fbaFeeMin`	No	Minimum FBA fee. Example: 3.00.
`ratingMax`	No	Maximum star rating (0.0-5.0). Example: 5.0.
`ratingMin`	No	Minimum star rating (0.0-5.0). Example: 4.0.
`sortOrder`	No	Sort direction: asc or desc	desc
`subBsrMax`	No	Maximum sub-category BSR. Example: 50000.
`subBsrMin`	No	Minimum sub-category BSR. Example: 1.
`listingAge`	No	Max product age: '30d', '90d', '180d', '1y', '2y'. Null = no limit.
`qaCountMax`	No	Maximum Q&A count. Example: 100.
`qaCountMin`	No	Minimum Q&A count. Example: 5.
`marketplace`	No	Amazon marketplace code	US
`categoryPath`	No	Category hierarchy from root to current level (e.g., ['Electronics', 'Computers', 'Laptops'])
`fulfillments`	No	Fulfillment filter. Example: ['FBA', 'FBM'].
`excludeBadges`	No	Exclude products with these badges. Supported: ['aPlus', 'video'].
`excludeBrands`	No	Brand names to exclude. Example: ['Generic'].
`includeBrands`	No	Brand names to include. Example: ['Apple', 'Samsung'].
`excludeSellers`	No	Seller names to exclude.
`includeSellers`	No	Seller names to include. Example: ['Apple Store'].
`ratingCountMax`	No	Maximum total rating count. Example: 10000.
`ratingCountMin`	No	Minimum total rating count. Example: 50.
`sellerCountMax`	No	Maximum number of sellers. Example: 20.
`sellerCountMin`	No	Minimum number of sellers. Example: 1.
`excludeKeywords`	No	Keywords to exclude from results. Example: ['refurbished', 'used'].
`monthlySalesMax`	No	Maximum monthly sales floor. Units sold. Example: 5000.
`monthlySalesMin`	No	Minimum monthly sales floor. Units sold. Example: 100.
`variantCountMax`	No	Maximum number of product variants. Example: 50.
`variantCountMin`	No	Minimum number of product variants. Example: 2.
`bsrGrowthRateMax`	No	Maximum BSR growth rate as decimal.
`bsrGrowthRateMin`	No	Minimum BSR growth rate as decimal. Example: -0.2 = 20% improvement.
`keywordMatchType`	No	Keyword match type: 'fuzzy', 'phrase', or 'exact'. Null = fuzzy.
`onlyCategoryRank`	No	If true, only return products ranked in their category BSR.
`monthlyRevenueMax`	No	Maximum monthly revenue floor. Example: 50000.00.
`monthlyRevenueMin`	No	Minimum monthly revenue floor. Example: 1000.00.
`ratingFilterTarget`	No	Choose whether rating-related filters apply to the current product or the most-rated variant.
`salesGrowthRateMax`	No	Maximum sales growth rate as decimal. Example: 0.5 = 50% growth.
`salesGrowthRateMin`	No	Minimum sales growth rate as decimal. Example: 0.1 = 10% growth.
`ratingToSalesRateMax`	No	Maximum rating-to-sales rate as decimal. Example: 0.5.
`ratingToSalesRateMin`	No	Minimum rating-to-sales rate as decimal. Example: 0.05.
`monthlyRatingCountMax`	No	Maximum monthly new rating count. Example: 500.
`monthlyRatingCountMin`	No	Minimum monthly new rating count. Example: 10.
`parentMonthlySalesMax`	No	Maximum parent ASIN monthly sales floor. Units sold.
`parentMonthlySalesMin`	No	Minimum parent ASIN monthly sales floor. Units sold.

Tool Definition Quality

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description proactively discloses key behaviors: 'Data is based on the latest daily snapshot; results are paginated (max 100 per page).' It also includes detailed response examples, covering success and error cases. This goes beyond minimal disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description front-loads the core purpose and usage, but it includes extensive output schema definitions (for 200 and 422 responses) that add significant length. While valuable, it could be more concise by referencing a standard schema or omitting repetitive details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 54 optional parameters and no separate output schema provided in the tool definition, the description adequately covers usage, example, pagination, data freshness, and response structure. It is sufficiently complete for an AI agent to select and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already defines each parameter. The description adds an example showcasing parameter usage (e.g., 'monthlySalesFloor >= 500 and price <= $30'), which provides practical context without duplicating schema details. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Search Amazon products by keyword, category, and multi-dimensional filters.' It differentiates from siblings by explicitly mentioning related tools for competitor analysis and trends. The purpose is unambiguous and specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit use cases: 'discover products in a specific niche, analyze competitor listings, or find high-demand low-competition opportunities.' It also gives a concrete example and mentions alternatives. However, it does not explicitly state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_realtime_productAInspect

Realtime Product V2 Legacy

[DEPRECATED] Legacy realtime product shape — use openapi_v3_realtime_product.

Returns the pre-#327 response (opaque buyboxWinner/ratingBreakdown/bestsellersRank, variants keyed by dimensions, no top-level price). Kept for backward compatibility; migrate to the v3 tool/endpoint for the typed protocol.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[RealtimeProduct]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`asin`	Yes	Amazon Standard Identification Number
`marketplace`	No	Amazon marketplace code	US

Tool Definition Quality

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses the deprecated status, details the response structure (including example and schema), and notes key behavioral differences from v3 (e.g., opaque buyboxWinner). While not explicitly stating read-only, the context implies it; a stronger statement would improve transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The main functional description is brief and front-loaded, but the inclusion of full output schema JSONs significantly lengthens the text. While structured, the verbosity reduces conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of a separate output schema, the description compensates by including the full response structure. It also provides migration guidance and explains deprecation. However, it does not cover all possible edge cases (e.g., error states beyond 422).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with clear definitions for asin and marketplace. The tool description does not add additional parameter semantics beyond what the schema already provides, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states it is a legacy realtime product shape and directs users to use openapi_v3_realtime_product. It distinguishes itself by detailing the pre-#327 response format, clearly differentiating from the v3 sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says the tool is deprecated, advises migration to v3, and explains when to use it (backward compatibility only). This provides clear guidance on when and when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_realtime_reviewsAInspect

Realtime Reviews V2

Fetch realtime reviews for a given ASIN.

Cursor-based pagination: omit cursor for the first page, then pass nextCursor from the previous response for subsequent pages. nextCursor=null means no more data. Related: /reviews/search for review data with AI tags, /reviews/analysis for aggregated insights.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[AmazonRealtimeReviews]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`asin`	Yes	Amazon Standard Identification Number — the 10-character product id from the Amazon product page URL, e.g. 'B07FR2V8SH'. Case-insensitive (normalized to uppercase).
`cursor`	No	Pagination token. Omit for the first page; for the next page, pass the `nextCursor` value from the previous response. A null `nextCursor` in the response means no more pages.
`marketplace`	No	Amazon marketplace: 'US' (amazon.com, default) or 'UK' (amazon.co.uk).	US

Tool Definition Quality

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of disclosing behavior. It describes pagination, response structure (success/error, meta with credits), and includes response schemas. However, it lacks details on authorization, rate limits, or any potential side effects. The provided info is adequate but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and pagination instructions. However, it includes verbose output schema examples that could be shortened or referenced. While structured, it contains some redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters and no structured output schema, the description provides a thorough explanation of pagination, response fields (including credits), and error handling. It references related tools and covers the essential information for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already has 100% description coverage for all three parameters. The description adds value by explaining the cursor-based pagination mechanism in prose, which synergizes with the cursor parameter's schema description. The marketplace enum is clear from the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Fetch realtime reviews for a given ASIN', providing a specific verb and resource. It also distinguishes from sibling tools by mentioning related endpoints (/reviews/search, /reviews/analysis) and their purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use this tool (for realtime reviews) and provides context for alternatives (search for AI tags, analysis for aggregated insights). It also details cursor-based pagination usage. However, it does not explicitly state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_reviews_analysisAInspect

Reviews Analyze V2

Analyze reviews by ASIN list or category to surface AI-generated sentiment, ratings, and consumer intelligence.

Use this to understand customer satisfaction and common complaints before sourcing a product. Example: pass asins=["B07FR2V8SH"] with period="6m" for 6-month review analysis. Data sourced from review analysis pipeline; ASIN mode supports max 100 ASINs. Related: /products/search to find ASINs, /categories for category paths.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[ReviewAnalysis]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`mode`	Yes	Query mode: 'asin' for ASIN-based, 'category' for category-based
`asins`	No	List of ASINs to analyze (max 100, required when mode='asin'). Example: ['B07FR2V8SH'].
`period`	No	Time period for analysis	6m
`marketplace`	No	Amazon marketplace code.	US
`categoryPath`	No	Category hierarchy from root. Example: ['Electronics', 'Computers']. Required when mode='category'.

Tool Definition Quality

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It discloses that data is sourced from a review analysis pipeline and that ASIN mode supports max 100 ASINs. However, it does not explicitly state whether the tool is read-only, require authentication, or mention rate limits. The output schema is detailed but lacks explicit read-only confirmation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and example, but includes extensive JSON schemas for responses and error details, making it verbose. While the schemas add completeness, they could be more concise or referenced externally. The structure is adequate but not optimal for quick consumption.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (5 parameters, 2 modes, enums) and lack of output schema, the description is fairly complete. It explains both modes, provides examples, mentions limitations, and links to related tools. It covers the necessary context for correct usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by providing an example (asins, period), stating max 100 ASINs for ASIN mode, and explaining mode selection. This goes beyond the schema alone, justifying a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool analyzes reviews by ASIN list or category to surface AI-generated sentiment, ratings, and consumer intelligence. It distinguishes from sibling tools like openapi_v2_reviews_search by focusing on analysis rather than raw review search, and mentions related tools for finding ASINs and categories.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear use case: 'understand customer satisfaction and common complaints before sourcing a product.' It includes an example and links to related tools (/products/search, /categories) for preparing inputs. However, it does not explicitly exclude alternatives or compare to sibling review tools, so a 4 is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_reviews_searchAInspect

Reviews Search V2

Search reviews for an ASIN with multi-dimensional filters.

Filters: star rating range, verified purchase, Vine program, helpful vote count, date range, and AI-generated tags. Results sorted by recent/rating/helpfulVoteCount. Page-based pagination (default 10 per page, max 20). Data sourced from daily BigQuery snapshot with AI-generated tags. Related: /realtime/reviews for live data, /reviews/analysis for aggregated insights.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "title": "Data",
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[list[TaggedReview]]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`asin`	Yes	Amazon Standard Identification Number
`page`	No	Page number (1-indexed).
`sortBy`	No	Sort field: 'recent' (date), 'rating' (star rating), 'helpfulVoteCount' (vote count).	recent
`dateEnd`	No	Latest review date (inclusive, YYYY-MM-DD). Example: '2026-04-01'.
`pageSize`	No	Results per page.
`vineOnly`	No	If true, only return Amazon Vine program reviews.
`dateStart`	No	Earliest review date (inclusive, YYYY-MM-DD). Example: '2025-01-01'.
`ratingMax`	No	Maximum star rating (inclusive). Example: 3 for negative reviews.
`ratingMin`	No	Minimum star rating (inclusive). Example: 1.
`sortOrder`	No	Sort direction: 'desc' or 'asc'.	desc
`verifiedOnly`	No	If true, only return verified purchase reviews.
`helpfulVoteCountMin`	No	Minimum helpful vote count. Example: 5.

Tool Definition Quality

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the data source (daily BigQuery snapshot, not real-time), pagination behavior (page-based, default 10, max 20), and mentions AI-generated tags. It does not cover rate limits or auth, but for a search tool, this is fairly transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the key purpose and filter summary, but it becomes lengthy by including full JSON response examples and output schemas inline. This clutter reduces conciseness; a separate output schema field would improve structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the parameter count of 12 and no separate output schema, the description covers all necessary context: input filters, sorting, pagination limits, data source, and full response structure (including success and error schemas). It is complete enough for an agent to understand usage and output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description groups filters (star rating, verified purchase, etc.) but does not add significant new meaning beyond the schema's parameter descriptions. It provides example values in the description, but those are already in the parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches reviews for an ASIN with multi-dimensional filters, listing specific filter types, sorting, and pagination. It also explicitly distinguishes from sibling tools like /realtime/reviews and /reviews/analysis, making the purpose well-defined and differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit related tools for live data and aggregated insights, guiding when to use this tool versus alternatives. However, it does not explicitly state when not to use this tool (e.g., if real-time data is needed), leaving some room for improvement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_tiktok_categoriesAInspect

Tiktok Categories

Query the TikTok Shop category tree by ID, path, parent, or keyword.

Use this to discover the category hierarchy for filtering in /tiktok/products/search. Example: pass parentCategoryPath=["Automotive & Motorcycle"] to enumerate its direct children. The tree is English-only and global (not region-scoped). productCount reflects the latest US-region snapshot (v1).

Query modes (mutually exclusive):

No parameters: Returns all root categories (level 1)
categoryId: Single category by ID
categoryPath: Single category by full path
parentCategoryId: Children of a parent by ID
parentCategoryPath: Children of a parent by path
categoryKeyword: Substring match on category name

Related: /tiktok/products/search accepts categoryId or categoryPath for filtering.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "title": "Data",
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[list[TikTokCategory]]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description
`categoryId`	No	Lookup a single category by ID.
`categoryPath`	No	Lookup a single category by full English path.
`categoryKeyword`	No	Case-insensitive substring search on category name (up to 100 matches).
`parentCategoryId`	No	Return all direct children of the given parent ID.
`parentCategoryPath`	No	Return all direct children of the given parent path.

Tool Definition Quality

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses important behavioral traits: English-only, global (not region-scoped), productCount reflects US-region snapshot v1, and query mode mutual exclusivity. No annotations provided, so description carries full burden. Lacks mention of authentication or rate limits, but reasonable for a read-only query tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with headings and bullets, front-loaded with purpose. However, inclusion of verbose output schema examples and long meta description adds unnecessary length. Could be trimmed without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers usage and limitations well, but lacks explanation of the response structure (what fields are in data, pagination behavior). No output schema provided, so description should describe return values; it does not. Leaves agent guessing about the actual category object fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds significant value by explaining query modes, giving an example for parentCategoryPath, and stating categoryKeyword returns up to 100 matches. Schema descriptions are adequate, so additional context earns a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it queries the TikTok Shop category tree, listing multiple query modes and explicitly ties to filtering in /tiktok/products/search. It distinguishes from siblings by being TikTok-specific and mentioning related endpoints.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear when-to-use (for category hierarchy discovery), lists query modes with mutual exclusivity, and notes global scope. However, it does not explicitly exclude when not to use, nor compare to similar sibling tools like openapi_v2_categories.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_tiktok_creators_searchAInspect

Tiktok Creators Search

Search TikTok creators by profile, category, content, and commerce signals.

Data is from the latest daily creator snapshot within the fallback window (region = US in v1). Related-product sales fields describe the overall product sales for SPUs the creator promoted, not creator-attributed GMV.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "title": "Data",
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[list[TikTokCreator]]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`page`	No	1-indexed page number.
`sortBy`	No	Sort field for creator search.	relatedProductSaleAmt30d
`keyword`	No	Case-insensitive substring match against creator handle or nickname.
`pageSize`	No	Page size, 1–100. Default 20.
`sortOrder`	No	Sort direction. Default desc.	desc
`followerCountMax`	No	Maximum follower count from the latest creator profile snapshot.
`followerCountMin`	No	Minimum follower count from the latest creator profile snapshot.
`saleCategoryPath`	No	Promoted product category path to filter creators by trailing-30-day carry categories. Supports 1 to 3 levels, e.g. ['Beauty & Personal Care', 'Skin Care', 'Face Serums'].
`carryVideo30dCountMax`	No	Maximum number of newly published carry videos over the trailing 30 days.
`carryVideo30dCountMin`	No	Minimum number of newly published carry videos over the trailing 30 days.
`carryVideoTotalCountMax`	No	Maximum total known carry-video count.
`carryVideoTotalCountMin`	No	Minimum total known carry-video count.
`follower30dDeltaCountMax`	No	Maximum follower-count change over the trailing 30 days.
`follower30dDeltaCountMin`	No	Minimum follower-count change over the trailing 30 days.
`follower30dGrowthRateMax`	No	Maximum follower growth rate over the trailing 30 days, as a decimal.
`follower30dGrowthRateMin`	No	Minimum follower growth rate over the trailing 30 days, as a decimal.
`promotedProduct30dCountMax`	No	Maximum number of products linked to newly published carry videos over the trailing 30 days.
`promotedProduct30dCountMin`	No	Minimum number of products linked to newly published carry videos over the trailing 30 days.
`relatedProductSaleAmt30dMax`	No	Maximum overall GMV over the trailing 30 days for products related to this creator, in USD. This is not creator-attributed GMV.
`relatedProductSaleAmt30dMin`	No	Minimum overall GMV over the trailing 30 days for products related to this creator, in USD. This is not creator-attributed GMV.
`relatedProductSaleCnt30dMax`	No	Maximum overall units sold over the trailing 30 days by products related to this creator. Each SPU is counted once; this is not creator-attributed sales.
`relatedProductSaleCnt30dMin`	No	Minimum overall units sold over the trailing 30 days by products related to this creator. Each SPU is counted once; this is not creator-attributed sales.
`promotedProductTotalCountMax`	No	Maximum total known promoted product count.
`promotedProductTotalCountMin`	No	Minimum total known promoted product count.
`carryVideoInteraction30dRateMax`	No	Maximum carry-video interaction rate over the trailing 30 days.
`carryVideoInteraction30dRateMin`	No	Minimum carry-video interaction rate over the trailing 30 days.
`carryVideoPlay30dIncrementCountMax`	No	Maximum play-count increment across carry videos over the trailing 30 days.
`carryVideoPlay30dIncrementCountMin`	No	Minimum play-count increment across carry videos over the trailing 30 days.

Tool Definition Quality

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description discloses data freshness (daily snapshot), regional limitation (US in v1), and clarifies that related-product sales are not creator-attributed. This provides useful behavioral context beyond search functionality.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description includes extensive output schema text, making it lengthy. However, it is well-structured with headings and code blocks, though not concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 28 parameters and no structured annotations or output schema, the description covers data freshness, regional constraints, sales semantics, and response structure. It is complete enough for a search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed parameter descriptions already present. The tool description adds no additional meaning beyond the schema, maintaining the baseline score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches TikTok creators by profile, category, content, and commerce signals. It distinguishes from sibling tools like openapi_v2_tiktok_products_search which search products.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use vs alternatives. The purpose is implied (search creators), but no exclusionary context or alternative tool mentions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_tiktok_products_searchAInspect

Tiktok Products Search

Search TikTok Shop products by keyword, category, and multi-dimensional filters.

Use this to discover top-selling SPUs in a niche, narrow by category and price / shipping signals, or surface fast-growing products by 30-day sales growth. Example: categoryPath=["Automotive & Motorcycle"] with categoryRankMax=100 returns the category's top 100 sellers.

Data is from the latest daily snapshot (region = US in v1). Results are paginated (max 100 per page).

Metric coverage today includes saleCnt*, saleAmt*, regionRank, categoryRank, price / RRP, rating / review count, SKU details, and populated shop flags.

Related: /tiktok/categories for category tree discovery.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "title": "Data",
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[list[TikTokProduct]]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`page`	No	1-indexed page number.
`sortBy`	No	Sort field. One of: ``saleCnt30d``, ``saleAmt30d``, ``saleCnt7d``, ``saleAmt7d``, ``saleCntTotal``, ``saleAmtTotal``, ``categoryRank``, ``regionRank``, ``price``, ``rating``, ``reviewCount``.	saleCnt30d
`keyword`	No	Substring match against product title (case-insensitive).
`hasVideo`	No	Filter to products with a description video. Omit for any.
`pageSize`	No	Page size, 1–100. Default 20.
`priceMax`	No	Maximum SPU price (USD).
`priceMin`	No	Minimum SPU price (USD).
`ratingMax`	No	Maximum SPU rating, 0–5.
`ratingMin`	No	Minimum SPU rating, 0–5.
`sortOrder`	No	Sort direction: ``asc`` or ``desc``. Default ``desc``.	desc
`categoryId`	No	TikTok category ID — matches against levels 1-7 of the SPU's category path.
`categoryPath`	No	Full category path, e.g. ['Automotive & Motorcycle', 'Car Exterior Accessories']. Must contain 1 to 7 segments (TikTok's max category depth) — deeper paths are rejected.
`regionRankMax`	No	Upper bound on region rank — e.g. set to 1000 for top-1000 in the region.
`regionRankMin`	No	Lower bound on region rank (lower number = better seller).
`revenue90dMax`	No	Maximum revenue over the trailing 90 days (USD). Matches response field ``revenue90d``.
`revenue90dMin`	No	Minimum revenue over the trailing 90 days (USD). Matches response field ``revenue90d``.
`isFreeShipping`	No	Filter to products that ship free. Omit for any.
`ratingCountMax`	No	Maximum cumulative review count.
`ratingCountMin`	No	Minimum cumulative review count.
`categoryRankMax`	No	Upper bound on category rank — e.g. set to 100 for top-100 of the L3 category.
`categoryRankMin`	No	Lower bound on category rank (lower number = better seller).
`excludeKeywords`	No	Substrings to exclude from product title (case-insensitive). Each up to 100 chars; max 300 entries.
`monthlySalesMax`	No	Maximum units sold in the trailing 30 days.
`monthlySalesMin`	No	Minimum units sold in the trailing 30 days.
`weeklyRevenueMax`	No	Maximum revenue in the trailing 7 days (USD).
`weeklyRevenueMin`	No	Minimum revenue in the trailing 7 days (USD).
`monthlyRevenueMax`	No	Maximum revenue in the trailing 30 days (USD).
`monthlyRevenueMin`	No	Minimum revenue in the trailing 30 days (USD).
`salesGrowthRateMax`	No	Maximum 30-day sales growth rate as decimal (e.g. 1.0 = +100%). Can be negative.
`salesGrowthRateMin`	No	Minimum 30-day sales growth rate as decimal (e.g. 0.1 = +10%). Can be negative.

Tool Definition Quality

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden. It discloses data freshness (latest daily snapshot, US region), pagination (max 100 per page), and metric coverage. It also explains response meta credit fields. Missing error behaviors beyond validation and rate limits, but covers key aspects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is informative but lengthy due to response examples and detailed output schema. It is well-structured with sections, but could be more concise. Several sentences are dedicated to credit fields and TODO notes that may be better placed elsewhere.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with 30 parameters, no output schema, and no annotations, the description covers purpose, usage, behavior, and examples reasonably well. It lacks explicit error handling guidance beyond validation but is fairly complete for a search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% coverage with descriptions for all 30 parameters. The description adds value with a usage example and metric list but doesn't provide additional meaning beyond the schema. Baseline 3 is appropriate as schema already does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches TikTok Shop products by keyword, category, and multi-dimensional filters. It differentiates from sibling tools like openapi_v2_tiktok_categories by mentioning it for category tree discovery, and from openapi_v2_tiktok_videos_search by focusing on products.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides concrete examples (e.g., categoryPath with categoryRankMax) and suggests use cases like 'discover top-selling SPUs in a niche'. Mentions related tool for categories. However, it lacks explicit when-not-to-use guidance or comparisons with other search tools like openapi_v2_products_search.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_tiktok_realtime_productAInspect

Tiktok Realtime Product

Get realtime TikTok Shop product detail for a single product (SPU) ID.

Use this when you need the product's current state rather than daily-updated values: current price, rating, units sold, inventory, shipping options, SKU variants (selectedOptions), and shop details. Data is collected on demand, so latency is higher than the daily-updated endpoints (typically 2-5 seconds). Only the US marketplace is available currently. Related: /tiktok/products/search for daily-updated data across many products.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[TikTokRealtimeProduct]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`productId`	Yes	TikTok Shop product (SPU) identifier — the digits in the product page URL, e.g. '1729456281219469588'.
`marketplace`	No	TikTok Shop marketplace. Only 'US' is available currently.	US

Tool Definition Quality

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that data is collected on-demand with 2-5 second latency and that only the US marketplace is available. It does not mention read-only nature explicitly, but the context implies it's a read operation. The description also explains the response meta object's credit fields in detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear hierarchy: purpose, usage guidance, then response details. However, it is somewhat lengthy, including full response schemas that could be summarized. The key information is front-loaded, but there is some redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there is no output schema (context indicates false), the description provides a sample response and meta object details. However, it lacks a description of the actual product data structure (the 'data' field), which is critical for an agent to interpret the response. This gap limits completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already describes both parameters well. The main description adds little beyond what the schema provides, except for noting the productId as an example. The description does not significantly enhance parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get realtime TikTok Shop product detail for a single product (SPU) ID.' It uses a specific verb ('Get'), resource ('realtime TikTok Shop product detail'), and scope ('single product'), effectively distinguishing it from sibling tools like the daily-updated search endpoint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear guidance on when to use this tool ('when you need the product's current state') versus the alternative daily-updated endpoint, and mentions latency and marketplace limitations. However, it does not explicitly state when not to use it, missing an opportunity for stronger contrast.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_tiktok_videos_searchAInspect

Tiktok Videos Search

Search daily-updated TikTok videos by engagement, creator, and commerce signals.

Filter by play and like counts, interaction rate, creator follower count, publish date, whether the video carries a shoppable product, and the product's category (by id or path). Each video also returns the primary product's category id and path. Data is from the latest daily video collection within the fallback window. Interaction rate is (likes + comments + shares + saves) / plays, as a decimal; it is computed per video, so filtering by it narrows the result set but does not reduce query time. Related: /tiktok/creators/search and /tiktok/products/search.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "title": "Data",
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[list[TikTokVideo]]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`page`	No	1-indexed page number.
`sortBy`	No	Sort field for video search.	playCount
`videoId`	No	Exact TikTok video ID to look up.
`pageSize`	No	Page size, 1–100. Default 20.
`sortOrder`	No	Sort direction. Default desc.	desc
`categoryId`	No	TikTok category ID — matches videos whose primary product anchor category has this id at any of the 7 hierarchy levels.
`hasProduct`	No	Filter by whether the video carries a shoppable product. True: the video has a TikTok Shop product anchor; False: it has none. Omit to include both.
`categoryPath`	No	Category path names, root → leaf, e.g. ['Home Improvement', 'Bathroom Fixtures']. Subtree match: the video's first N category level names must equal the N supplied segments in order; deeper levels (if any) are unconstrained. A partial path matches the whole subtree below it; supply the full leaf path to narrow to that single node. Must contain 1 to 7 segments (TikTok's max category depth) — deeper paths are rejected.
`diggCountMax`	No	Maximum like count.
`diggCountMin`	No	Minimum like count.
`playCountMax`	No	Maximum play (view) count.
`playCountMin`	No	Minimum play (view) count.
`shareCountMax`	No	Maximum share count.
`shareCountMin`	No	Minimum share count.
`publishedAtMax`	No	Latest publish date (inclusive), as YYYY-MM-DD in UTC, e.g. 2026-06-30.
`publishedAtMin`	No	Earliest publish date (inclusive), as YYYY-MM-DD in UTC, e.g. 2026-06-01.
`repostCountMax`	No	Maximum on-platform repost count.
`repostCountMin`	No	Minimum on-platform repost count.
`collectCountMax`	No	Maximum save/collect count.
`collectCountMin`	No	Minimum save/collect count.
`commentCountMax`	No	Maximum comment count.
`commentCountMin`	No	Minimum comment count.
`interactionRateMax`	No	Maximum interaction rate, as a decimal. Interaction rate = (likes + comments + shares + saves) / plays.
`interactionRateMin`	No	Minimum interaction rate, as a decimal. Interaction rate = (likes + comments + shares + saves) / plays.
`creatorFollowerCountMax`	No	Maximum follower count of the video's creator.
`creatorFollowerCountMin`	No	Minimum follower count of the video's creator.

Tool Definition Quality

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description covers important behaviors: data freshness (daily updates, fallback window), interaction rate computation and performance impact, and return of product category info. However, it omits pagination behavior and authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core description is front-loaded, but the inclusion of detailed response examples and schemas adds unnecessary verbosity for an AI agent's needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 26 parameters and no output schema, the description covers the tool's purpose, key behaviors, and parameter semantics well, but could provide more detail on the response structure beyond the example.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the description adds value by explaining the interaction rate formula, category path matching semantics, and the behavior of the hasProduct filter, which go beyond the schema definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Search' and the resource 'TikTok videos', and explicitly mentions related sibling tools (creators/search, products/search) for differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions related tools but does not provide explicit guidance on when to use this tool versus alternatives (e.g., when to search videos vs creators or products).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_webtools_crawl_statusAInspect

Poll a crawl job

Poll a crawl job's status. data[] contains already-scraped pages.

Paginate with the skip / limit query params when data[] grows large. Returns 404 when the job id is unknown or belongs to a different tenant — the two cases are deliberately indistinguishable so job-id existence does not leak across tenants.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[CrawlerCrawlStatus]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description
`skip`	No	Pagination offset over completed pages.
`limit`	No	Pagination size.
`job_id`	Yes	Crawl job id.

Tool Definition Quality

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses the 404 security measure (indistinguishable for unknown job or different tenant), pagination with skip/limit, and that data[] contains scraped pages. It does not mention rate limits or response times, but the key behavioral traits are covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core description (before response schemas) is front-loaded and concise, using three sentences to cover purpose, pagination, and security. The first two sentences are slightly redundant ('Poll a crawl job' followed by 'Poll a crawl job's status'), but overall it is well-structured and not overly verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description provides a detailed output schema as part of the description, including example responses and field explanations. It covers pagination, security behavior, and return structure comprehensively, making the tool fully understandable for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% coverage, so the description adds little beyond what the schema already provides. It mentions pagination with skip/limit in the narrative, but the schema descriptions already explain these. No additional parameter details are given beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool polls a crawl job's status, using specific verb 'Poll' and resource 'crawl job status'. It differentiates from siblings like openapi_v2_webtools_crawl_submit by focusing on status checking, and mentions data[] containing scraped pages, making purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage after submitting a crawl job and explains pagination when data grows large. It also discloses the 404 behavior for security. However, it lacks explicit comparison to sibling tools or when not to use this tool (e.g., for real-time updates), but the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_webtools_crawl_submitAInspect

Submit a crawl job

Submit an async recursive crawl job.

Returns an opaque id; poll GET /webtools/crawl/{id} for status and finished pages. robots.txt is always honored; external-domain links are not followed. limit defaults to 100 pages (cap 10000) — set it explicitly when crawling a larger site. The returned id is bound to the calling tenant: polling from a different API key returns 404.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[CrawlerCrawlSubmit]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`url`	Yes	Seed URL to start crawling from.
`limit`	No	Maximum pages to crawl. Defaults to 100; hard cap 10000.
`maxDepth`	No	Maximum link depth to traverse from the seed.
`sitemapMode`	No	How the site's sitemap is used for discovery. ``include`` (default) combines the sitemap with link following — the most complete coverage; ``only`` crawls sitemap URLs exclusively (fastest, but misses pages not in the sitemap); ``skip`` ignores the sitemap and discovers by following links only (misses pages that are in the sitemap but not linked, e.g. orphan/deep pages — useful when the sitemap is stale or inaccurate).	include
`excludePaths`	No	Path regex blacklist (max 50 patterns, each ≤500 chars).
`includePaths`	No	Path regex whitelist (max 50 patterns, each ≤500 chars).
`allowSubdomains`	No	Follow links to subdomains of the seed host.
`crawlEntireDomain`	No	Crawl the whole domain rather than only paths nested under the seed URL. By default a seed like ``example.com/blog`` stays under ``/blog``; set ``true`` to also follow sibling/parent paths across the domain.
`ignoreQueryParameters`	No	Treat URLs that differ only by query string as the same page, so they are crawled once. Useful on sites with tracking/pagination params (``?utm=``, ``?page=``) to avoid spending the page budget on near-duplicates.

Tool Definition Quality

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It discloses key behaviors: async execution, tenant binding (separate API key returns 404), robots.txt always honored, external-domain links not followed, limit default and cap, and sitemap mode options. This provides sufficient transparency for an agent to understand side effects and constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: begins with a clear one-sentence purpose, then bullet-like details about behavior, and includes response examples and schemas. It is somewhat lengthy due to the embedded response schemas, but the essential information is front-loaded and not verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the async nature, polling mechanism, tenant binding, and key constraints (robots.txt, external links, limit). It includes output schema examples for success and validation errors. However, it does not mention rate limits or concurrency, which would be helpful for complex use cases, but the provided information is sufficient for typical usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage with detailed parameter descriptions. The main description adds context about the limit default and cap, but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate since schema already does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Submit an async recursive crawl job' with specific behaviors (honors robots.txt, does not follow external-domain links, returns opaque id for polling). It distinguishes itself from sibling tools like crawl_status and scrape by indicating that it submits a crawl job and returns an id for polling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains how to use the returned id for polling (GET /webtools/crawl/{id}) and advises setting the limit explicitly for large sites. It implies when to use this tool (for async recursive crawling) versus other tools (e.g., scrape for single pages, crawl_status for polling). However, it does not explicitly exclude alternatives like map or search.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_webtools_mapAInspect

Discover URLs on a website

Discover URLs from a website via sitemap and on-page link discovery.

Returns a flat, relevance-ordered list of links (each with optional title / description). Use search to rank links by keyword relevance; sitemapMode to control sitemap usage (include / only / skip); includePaths / excludePaths to filter by URL path regex (≤50 patterns, ≤500 chars each); and limit (1-100000, default 5000) to cap results.

Subdomains of the seed host are included by default; set includeSubdomains to false to lock discovery to the exact seed host. URLs that differ only by query string are collapsed by default (ignoreQueryParameters = true); set false to keep query-string variants as distinct URLs.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[CrawlerMap]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`url`	Yes	Seed URL to discover links from.
`limit`	No	Maximum number of URLs to return (1-100000). Default 5000.
`search`	No	Keyword filter; discovered URLs are ranked by relevance to this term.
`sitemapMode`	No	How the site's sitemap is used for discovery. ``include`` (default) combines the sitemap with on-page link discovery — the most complete coverage; ``only`` returns sitemap URLs exclusively (fastest, but misses pages not in the sitemap); ``skip`` ignores the sitemap and discovers by link crawling only (misses pages that are in the sitemap but not linked, e.g. orphan/deep pages — useful when the sitemap is stale or inaccurate).	include
`excludePaths`	No	Drop URLs whose path matches one of these regex patterns (e.g. ``/admin/.*``). Max 50 patterns, each ≤500 chars.
`includePaths`	No	Only return URLs whose path matches one of these regex patterns (e.g. ``/blog/.*``). Max 50 patterns, each ≤500 chars.
`includeSubdomains`	No	Include subdomains of the seed host (e.g. blog.example.com when mapping example.com). Defaults to ``true``; set ``false`` to lock discovery to the exact seed host.
`ignoreQueryParameters`	No	Collapse URLs that differ only by query string so each page is returned once. Defaults to ``true`` (recommended for discovery — avoids near-duplicate ``?utm=``/``?page=`` URLs). Set ``false`` to keep query-string variants as distinct URLs.

Tool Definition Quality

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses key behaviors: returns a flat relevance-ordered list, includes subdomains by default, collapses query strings, and explains sitemap modes (include/only/skip). Missing details on rate limits, authentication, or data retention, but covers the core discovery behavior well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear summary line, followed by parameter explanations and response details. It is somewhat lengthy due to the included response schema section, but each sentence serves a purpose and the structure aids readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the tool's purpose, all parameters with usage notes, and provides response structure examples. It lacks explicit return value documentation beyond the schema snippet, but given the tool's nature (returning a list of links), the context is sufficient for an agent to understand expected output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds significant value: explains sitemapMode options with practical examples (combines sitemap with on-page discovery for most complete coverage), clarifies path regex patterns, and illustrates default behaviors for includeSubdomains and ignoreQueryParameters with real-world scenarios.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Discover URLs on a website' and elaborates on the method (sitemap and on-page link discovery). It distinguishes itself from sibling tools by focusing on bulk URL discovery rather than scraping individual pages or searching.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides detailed guidance on parameter usage including search, sitemapMode, path filters, subdomain control, and query parameter handling. However, it does not explicitly contrast with sibling tools (e.g., when to use this vs. crawl_submit or scrape), leaving the agent to infer usage context from purpose alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_webtools_scrapeAInspect

Scrape a single URL

Scrape a single URL and return clean content.

Specify one or more of markdown / json / rawHtml in formats. json returns a structured page summary (title, page_type, key facts, main entities, etc.) — the extraction schema is built in, so you don't need to define one in your request.

Response meta carries the target page's HTTP status code, title, canonical URL, description, and detected language. Always check meta.statusCode before trusting the content body: a 4xx/5xx (e.g. 404 or a 5xx) usually means the content is an error page, not the real page.

A page that refuses the request (HTTP 401/403/429/451/503, or one the upstream flags as blocked) returns success:false with an error.code of ACCESS_DENIED (blocked) / RATE_LIMITED (429) / UNREACHABLE (host didn't resolve) / TIMEOUT / CONTENT_UNAVAILABLE (generic), plus error.details (targetStatusCode / upstreamCode / blockSignal). Refused requests are not billed and never carry a content body.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[CrawlerScrape]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`url`	Yes	URL to scrape
`formats`	No	Output formats. Order in the response matches the input order.

Tool Definition Quality

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotates response behavior (success/false, error details, not billed on refusal) but does not disclose rate limits, permissions, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with sections and examples, but includes extensive output schema details that could be trimmed; slightly verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers error handling, response meta, credit fields, and return values comprehensively without a formal output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema already describes both parameters well; description adds value by explaining format options and built-in extraction for json format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it scrapes a single URL and returns clean content in specified formats. Distinguishes from siblings by emphasizing 'single URL' and separate interactive tool exists.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides post-request handling guidance (check meta.statusCode, error codes) but lacks explicit comparison to alternative tools like crawl or interactive scrape.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_webtools_scrape_interactiveAInspect

Scrape a page after running browser actions

Scrape after executing a sequence of browser actions.

Supports seven action types: wait, click, write, press, scroll, scrape, executeJavascript. (screenshot and pdf are intentionally excluded — their artifacts have no place in the markdown/json/raw_html response surface.) Cumulative wait time across all actions is capped at 60 seconds; over-cap requests are rejected with HTTP 422.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[CrawlerScrape]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description
`url`	Yes	URL to scrape
`actions`	Yes	Sequential browser actions to perform before scraping.
`formats`	No

Tool Definition Quality

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses action types, excluded actions with rationale, wait cap error code (422), and includes full output schema. No annotations, so description carries full burden; missing explicit mention of side effects but scraping is read-only.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear sections but overly verbose due to inclusion of full output schema and response examples. Front-loaded with purpose, but volume may overwhelm an AI agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers action types, constraints, and output structure. Lacks comparison with sibling tool and prerequisites (e.g., URL accessibility, auth). Otherwise complete for the complexity level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds context beyond schema: wait cap, excluded actions, and action type descriptions. Schema already defines parameters well, but description enriches with constraints and rationale.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it scrapes a page after running browser actions, lists seven action types, and explicitly excludes screenshot/pdf actions. Differentiates from sibling 'scrape' by focusing on interactive behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides context for when to use (interactive scraping), includes wait cap (60s) and action count limit (50). Does not explicitly compare to non-interactive sibling but the interactive nature is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v2_webtools_searchAInspect

Search the web

Search the web and return each result page as Markdown.

query is compatible with common Google search-operator syntax, so operators work inline: site:, intitle:, filetype:, "exact phrase", -exclude. To filter by whole domains, prefer the structured includeDomains / excludeDomains — they are folded into the matching site: / -site: operators for you (and may be combined, e.g. include a parent domain while excluding one subdomain).

Use sources to pick the result bucket — "web" (default), "news", or "images" (combinable); tbs for a time filter (qdr:d / qdr:w / qdr:m / qdr:y); limit (1-20, default 10) to cap results.

Each result page is then fetched and returned as markdown under each result; meta.statusCode is the fetched page's HTTP status. Results that can't be fetched within the request budget are dropped from the response, so every returned result carries markdown (the response may hold fewer than limit results). Billing scales with the number of results returned, with a minimum of 1 credit per call (an empty result set still bills the minimum).

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[CrawlerSearch]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description
`tbs`	No	Time-based result filter using the ``qdr:`` syntax: ``qdr:d`` (past day), ``qdr:w`` (week), ``qdr:m`` (month), ``qdr:y`` (year). Omit for no time restriction.
`limit`	No	Maximum number of results to return (1-20). Default 10.
`query`	Yes	Search query. Compatible with common Google search-operator syntax, inline: ``site:`` (domain), ``intitle:``, ``filetype:``, ``"exact phrase"``, ``-exclude``. To filter by whole domains, prefer ``includeDomains`` / ``excludeDomains`` instead of hand-writing ``site:``.
`sources`	No	Result bucket(s). Allowed values: ``"web"``, ``"news"``, ``"images"``. Defaults to ``["web"]``; combine multiple buckets in one call to merge their results.
`excludeDomains`	No	Exclude results from these domains (bare hostnames only, e.g. ``pinterest.com``). Folded into ``-site:`` operators. May be combined with ``includeDomains``. Max 20.
`includeDomains`	No	Restrict results to these domains (bare hostnames only, e.g. ``github.com``). Folded into ``site:`` operators; multiple domains are OR-combined. May be used together with ``excludeDomains`` (e.g. include a parent domain, exclude one subdomain). Max 20.

Tool Definition Quality

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that each result page is fetched and returned as Markdown, unfetched results are dropped, billing scales with returned results, and minimum 1 credit per call. It does not mention rate limits or auth, but the described behaviors are sufficient for safe usage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is somewhat lengthy but well-structured with sections, code blocks for examples, and clear parameter explanations. Every sentence adds value, though the inclusion of full output schema examples might be slightly redundant but helpful. Overall appropriate for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema or annotations, the description covers all essential aspects: purpose, parameter details, behavior (including edge cases like dropped results), billing information, and example responses. It is complete for an agent to correctly select and invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, but the description adds value beyond the schema by explaining how includeDomains/excludeDomains are folded into site: operators, how sources can be combined, and the tbs format. This provides clearer semantics than the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Search the web' and elaborates that it returns each result page as Markdown. This distinguishes it from sibling tools like product searches or TikTok searches, which have different scopes. The verb 'Search' and resource 'web' are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides detailed guidance on parameter usage, including search operators, filters, and sources. However, it does not explicitly state when to use this tool over alternatives (e.g., when to prefer this over openapi_v2_webtools_scrape). The context is clear but lacks explicit exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openapi_v3_realtime_productAInspect

Realtime Product V3

Get realtime product data for a given ASIN.

Use this when you need the product's current state rather than daily-updated values. Example: pass asin="B07FR2V8SH" to get the current price, rating, review count, Best Sellers Rank, inventory, variants (selectedOptions), and Buy Box offer. Data is collected on demand, so latency is higher than the daily-updated endpoints (typically 2-5 seconds). Related: /products/search for daily-updated catalog data, /products/history for trend analysis.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[AmazonRealtimeProduct]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`asin`	Yes	Amazon Standard Identification Number — the 10-character product id from the Amazon product page URL, e.g. 'B07FR2V8SH'. Case-insensitive (normalized to uppercase).
`marketplace`	No	Amazon marketplace: 'US' (amazon.com, default) or 'UK' (amazon.co.uk).	US

Tool Definition Quality

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It explains that data is collected on demand, latency is higher, and details the response structure (including credit fields). While not explicitly stating it's read-only, the context implies no side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is comprehensive but verbose, including full response schemas and example JSON that could be summarized. It is front-loaded with the main purpose but loses conciseness with extensive output documentation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the context indicating no output schema, the description includes detailed response schemas for 200 and 422 status codes, covering all necessary information. It also explains the difference from daily-updated endpoints, making the tool self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with both parameters documented. The description adds value by including an example call with ASIN 'B07FR2V8SH' and listing the data fields obtained, going beyond the schema's descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves realtime product data for a given ASIN, listing specific fields (price, rating, review count, BSR, etc.) and explicitly distinguishes it from sibling tools like /products/search (daily-updated) and /products/history (trend analysis).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises using this tool when the product's current state is needed rather than daily-updated values, and provides related endpoints for catalog data and trend analysis. It also notes the higher latency (2-5 seconds) due to on-demand data collection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

poll_video_taskAInspect

Poll a video generation task

Retrieve the status and result of a video generation task.

Call with the taskId returned by the submit endpoint and poll periodically (e.g. every 5-10 seconds) until status is terminal. On succeeded, output.video_url holds the generated video; on failed, error holds the reason.

Available to CONTRACT-tier API keys only. The first poll that observes succeeded charges the task cost in USD from the account wallet and returns the provider token usage in meta.tokensUsage. Polls of an already-terminal task return the cached result and are not charged. The per-call response carries no USD amount — derive cost from meta.tokensUsage and the published video pricing, or call GET /openapi/v2/account/balance.

Path parameter:

task_id (string, required): the taskId from the submit call. Returns 404 if it does not exist or belongs to another account.

Response data:

taskId (string): the polled task id.
status (string): one of pending, running, succeeded, failed, cancelled. The last three are terminal.
output (object | null): on succeeded, an object with video_url plus any additional provider fields; null otherwise.
error (object | null): on failed, a {code, message} object with the provider failure reason; null otherwise.

Response meta:

tokensUsage (object | null): provider token usage (completionTokens, totalTokens, ...) on any terminal poll; null while pending / running.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[VideoTaskData]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`task_id`	Yes

Tool Definition Quality

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description provides detailed behavioral traits: cost charging on first 'succeeded' poll, cached responses on subsequent polls, error handling (404 for missing task), response structure with `status`, `output`, `error`, and `meta.tokensUsage`. No annotations, so the description carries full burden and fulfills it thoroughly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with headings, bullet points, and sections for response details. It's slightly long but every section adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the entire polling lifecycle, charging behavior, response fields, error conditions, and API tier restrictions. Given the tool's complexity (state transitions, cost implications), the description is fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has only `task_id` with 0% description coverage. The description adds meaning by explaining it's the `taskId` from submit and mentioning 404 errors for missing or unauthorized tasks. This significantly compensates for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Poll a video generation task' and distinguishes from sibling tools like 'submit_video_generation' by specifying its role in retrieving status. It's a specific verb+resource pair.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly directs to use the `taskId` from the submit endpoint, recommends polling every 5-10 seconds, and notes that it's only for CONTRACT-tier API keys. Could be more explicit about when NOT to use (e.g., not for initial submission), but the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

submit_video_generationAInspect

Submit a video generation task

Submit an asynchronous video generation task.

Starts a Seedance generation job — text-to-video, image-to-video, or video-to-video depending on content — and returns a taskId immediately; the video is produced in the background. Poll GET /openapi/v2/model/video/tasks/{task_id} with the returned id until status is terminal to obtain the video URL.

Available to CONTRACT-tier API keys only. The task cost is charged in USD from the account wallet on the first successful poll, not at submit time. At submit time the wallet balance is checked against an upper-bound cost estimate; an insufficient balance returns 402 with X-Usd-Required-* headers and no task is created.

Request body:

model (string, required): seedance-2.0 or seedance-2.0-fast.
content (array, required, >= 1 item): generation inputs as an OpenAI-style content array. Must include at least one text item {"type": "text", "text": "<prompt>"}. May also include reference media items such as {"type": "image_url", "image_url": {"url": "https://..."}, "role": "reference_image"} (and likewise video_url / audio_url), capped at 9 image, 3 video, and 3 audio items. role is one of first_frame, last_frame, reference_image, reference_video, reference_audio. Reference URLs must be publicly reachable.
resolution (string, optional, default 720p): 480p, 720p, or 1080p. 1080p is not supported by seedance-2.0-fast. Also the billing tier.
duration (integer, required): output length in seconds, 4-15.
ratio (string, optional): output aspect ratio — 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, or adaptive.
generate_audio (boolean, optional): generate an audio track.
watermark (boolean, optional): overlay the provider watermark.
service_tier (string, optional): flex for cheaper offline inference.
return_last_frame (boolean, optional): also return the video's last frame on output. Any further unrecognized top-level fields are forwarded to the generation provider unchanged.

Response data:

taskId (string): identifier to poll, format task_video_<id>.
status (string): always pending immediately after submit.

Responses:

200: Successful Response (Success Response) Content-Type: application/json

Example Response:

{
  "success": true,
  "meta": {
    "requestId": "Requestid",
    "timestamp": "Timestamp"
  }
}

Output Schema:

{
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the request was successful",
      "default": true
    },
    "data": {
      "description": "Response data payload"
    },
    "error": {
      "description": "Error details if request failed"
    },
    "meta": {
      "description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n  to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n  precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
      "properties": {
        "requestId": {
          "type": "string",
          "title": "Requestid",
          "description": "Unique request identifier"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "description": "Response timestamp in ISO 8601 format"
        },
        "total": {
          "title": "Total",
          "description": "Total number of records"
        },
        "page": {
          "title": "Page",
          "description": "Current page number"
        },
        "pageSize": {
          "title": "Pagesize",
          "description": "Number of records per page"
        },
        "totalPages": {
          "title": "Totalpages",
          "description": "Total number of pages"
        },
        "creditsRemaining": {
          "title": "Creditsremaining",
          "description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
        },
        "creditsConsumed": {
          "title": "Creditsconsumed",
          "description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
        },
        "creditsRemainingExact": {
          "title": "Creditsremainingexact",
          "description": "Remaining API credits, precise to 1 decimal place"
        },
        "creditsConsumedExact": {
          "title": "Creditsconsumedexact",
          "description": "Credits consumed by this request, precise to 1 decimal place"
        },
        "tokensUsage": {
          "description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
        }
      },
      "type": "object",
      "required": [
        "requestId",
        "timestamp"
      ],
      "title": "ResponseMeta"
    }
  },
  "type": "object",
  "required": [
    "meta"
  ],
  "title": "OpenApiResponse[VideoGenerationSubmitData]",
  "examples": []
}

422: Validation Error Content-Type: application/json

Example Response:

{
  "detail": [
    {
      "loc": [],
      "msg": "Message",
      "type": "Error Type",
      "ctx": {}
    }
  ]
}

Output Schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {},
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

ParametersJSON Schema

Name	Required	Description	Default
`model`	Yes	Generation model. One of `seedance-2.0` (supports `480p` / `720p` / `1080p`) or `seedance-2.0-fast` (faster and lower cost, supports `480p` / `720p` only).
`ratio`	No	Output aspect ratio. Known values: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `adaptive`. Optional — the provider picks a default when omitted. Does not affect billing.
`content`	Yes	OpenAI-style content array describing the generation inputs. Must contain at least one `type=text` item (the prompt). May also include reference media, capped per kind: up to 9 `image_url`, 3 `video_url`, and 3 `audio_url` items. Including a `video_url` item makes this a video-to-video request and is priced accordingly.
`duration`	Yes	Output video length in seconds.
`watermark`	No	Whether to overlay the provider watermark on the output. Optional; the provider default applies when omitted.
`resolution`	No	Output video resolution — one of `480p`, `720p`, `1080p`. Optional; defaults to `720p`. `1080p` is not supported by `seedance-2.0-fast`. This is also the billing tier: cost is priced per (model, resolution, input-video) combination.	720p
`service_tier`	No	Inference tier. `flex` selects cheaper offline/async inference. Optional; omit for standard online inference.
`generate_audio`	No	Whether to generate an audio track for the video. Optional; the provider default applies when omitted.
`return_last_frame`	No	Whether the provider should also return the generated video's last frame (surfaces as an extra field on `output`). Optional.

Tool Definition Quality

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Since no annotations are provided, the description bears full responsibility for behavioral disclosure. It thoroughly covers the async nature, polling requirement, cost model (charged on first poll, not submit), wallet check, and implications for different content types. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is lengthy but well-structured with sections (overview, request body, response). Every sentence adds meaningful context, though some repetition exists (e.g., mentions of publicly reachable URLs in multiple places). Front-loading is effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of the tool (9 parameters, async behavior, multiple generation modes), the description covers all necessary aspects: parameter details, limits, cost model, polling instructions, and response format. The lack of an output schema is compensated by the detailed response description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides 100% description coverage for all 9 parameters, so the baseline is 3. The description adds significant value beyond the schema by explaining caps (9 images, 3 videos, 3 audio), role semantics, resolution/model compatibility, and billing implications, justifying a score of 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a clear verb-resource pair ('Submit a video generation task') and immediately distinguishes the three modes (text-to-video, image-to-video, video-to-video) based on the `content` parameter. It differentiates from sibling tools like `poll_video_task` by explaining the asynchronous pattern.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly states the API is only for CONTRACT-tier keys and explains the wallet balance check and cost behavior. However, it does not explicitly provide when-to-use vs. when-not-to-use guidance or name alternative tools for other scenarios (e.g., using `create_video_asset` for asset management).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:

{
  "$schema": "https://glama.ai/mcp/schemas/connector.json",
  "maintainers": [{ "email": "your-email@example.com" }]
}

The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.

Discussions

No comments yet. Be the first to start the discussion!

Try in Browser

Your Connectors

Resources

Need Help?