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.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
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.
Average 4/5 across 49 of 49 tools scored. Lowest: 2.9/5.
Several tools have unclear boundaries, most notably openapi_v2_competitor_product_keywords and openapi_v2_product_traffic_terms, which have identical descriptions. The deprecated openapi_v2_realtime_product duplicates openapi_v3_realtime_product, and openapi_v2_image_embedding overlaps heavily with openapi_v2_fashion_image_embedding.
Naming is inconsistent: a few tools follow a clean verb_noun pattern (create_video_asset, list_video_assets, poll_video_task), while the vast majority are prefixed with openapi_v2_/openapi_v3_ followed by nouns or mixed verbs. The route-style prefix is not a meaningful verb and creates an arbitrary split across the tool set.
49 tools is far beyond the well-scoped range and spans multiple unrelated domains (Amazon product data, TikTok commerce, fashion vision, web scraping, video generation, billing). The server appears to be an entire REST API surface exposed wholesale rather than a curated set of capabilities.
Each domain is individually fairly complete (Amazon search/reviews/keywords/VoC, TikTok search, web tools, video generation), but there are notable gaps: video assets lack update/delete, video tasks lack cancel/list, and there is no singular 'get daily product by ASIN' alongside the realtime variants. The broad scope makes it hard to verify full lifecycle coverage across all domains.
create_video_assetAInspectRegister a public URL as a video-generation asset
Register a publicly-reachable URL as an asset for use in video generation.
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.
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"
}| Name | Required | Description | Default |
|---|---|---|---|
| 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`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and delivers exceptionally: it discloses asynchronous downloading, Processing→Active status transitions, polling endpoint, retry/fail-fast behavior, CONTRACT-tier restriction, and free-of-charge nature. It also includes response examples and error schema, making behavior highly predictable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The prose is well-structured and front-loaded with the purpose, followed by lifecycle detail and availability. The response section includes large embedded JSON schemas which add length but are useful given no separate output schema. Overall, the content earns its place, though it is longer than minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the absence of formal output schema and annotations, the description is remarkably complete: it covers use case, lifecycle, polling, error handling, tier access, and includes response examples and validation error schema. Nothing essential seems missing for an agent to invoke this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100% and the schema itself is richly descriptive (URL reachability/auth requirements, name being bookkeeping-only, assetType enum). The description adds no parameter-specific meaning beyond what the schema already states; it mentions the assetId return and usage context rather than param details. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Register a public URL as a video-generation asset' and repeats a clear, specific action. It explicitly distinguishes this from sibling read/list/generation tools by framing it as the registration step for video generation, and it explains the asset:// reference format that ties it to generation requests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes when to use this tool: before submitting a video generation request with an external URL, and how to check readiness via polling. It does not explicitly name sibling alternatives or say when not to use it, but the workflow context is clear and practical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_account_balanceAInspectGet 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).
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"
}| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It reveals tier-dependent response views, the uniqueness of this endpoint for USD balance observation, and the ADR-0003 parallel-fields strategy including exact vs rounded credit fields and a deprecation timeline. This is rich disclosure beyond what annotations would typically provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core description is only three sentences and front-loaded with the essential purpose and usage. However, the inline response schemas and ADR citations make the overall description lengthy, though they add necessary context for response handling.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's behavior, tier-specific responses, field semantics, and error responses (422) with full inline schemas. It addresses authentication implicitly and includes a deprecation timeline, leaving no significant gaps for a zero-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there is nothing to document. The description confirms the tool takes no arguments, making parameter semantics trivially complete (baseline 4 for zero params).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the authenticated user's billing balance, differentiating between CONTRACT-tier (USD) and other tiers (credits). It stands apart from sibling tools like video generation and keyword search, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this endpoint: CONTRACT-tier customers must poll this endpoint to observe USD balance because other endpoints intentionally omit balance fields. This provides clear exclusionary guidance, though it does not name specific sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_video_assetAInspectGet 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.
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"
}| Name | Required | Description | Default |
|---|---|---|---|
| asset_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses important behaviors: 404 for non-existent or cross-tenant assets to avoid leaking existence, and a CONTRACT-tier restriction. It also includes response schemas and credit field details, adding context beyond the minimal purpose. Slightly less rich because it doesn't describe the 'data' payload structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening paragraphs are concise and front-loaded, but the description then includes lengthy response schema blocks (especially the meta section with ADR-0003 migration details and TODOs) that are tangential for tool selection. While structured, it is bloated and not every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-param tool with no annotations and no output schema, the description gives purpose and some error semantics, but it omits the structure of the actual asset data (the 'data' field in the response). The 200 response example only shows meta, not the asset metadata/live status fields the tool is supposed to retrieve, leaving an incomplete picture of what the caller will receive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the sole parameter asset_id has no schema description. The description only says 'by id,' which adds virtually no semantic detail beyond the parameter name. It does not specify format, constraints, or examples, failing to compensate for the complete lack of schema-level parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get a video-generation asset by id' and 'Fetch a single asset's metadata and live status.' This is a specific verb+resource combination with a clear scope (by id), and it distinguishes from siblings like create_video_asset, list_video_assets, and poll_video_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have an asset ID and need its metadata/live status, and it adds a clear constraint ('Available to CONTRACT-tier API keys only'). However, it does not explicitly state when to prefer this over list_video_assets or poll_video_task, nor does it provide exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_video_assetsAInspectList 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.
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"
}| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, 1-indexed. | |
| pageSize | No | Items per page (max 100). | |
| assetType | No | Optional filter by modality. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly: it discloses that items omit the `status` field, that listing is served from a local registry without live provider status, and that the tool is restricted to CONTRACT-tier keys. No annotation contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening prose is front-loaded and useful, but the description is bloated by a massive inline response schema, error schema, and examples, including internal TODOs and credit-field details. The first sentence is also redundantly restated in the second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite verbosity, the description is highly complete: it covers behavior, ordering, auth requirements, the absence of status fields, how to get live status, and even includes the full response and error schemas. No important aspect of tool selection or invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers 100% of parameters (page, pageSize, assetType) with clear descriptions, so the description adds no parameter-specific meaning. The baseline of 3 applies because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description immediately states 'List your video-generation assets' and clarifies 'List the calling customer's assets, newest first.' It clearly identifies the verb, resource, and scope, distinguishing it from single-asset retrieval tools like 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains when to use this tool for fast/cheap listing and when not to: 'call GET /openapi/v2/model/video/assets/{assetId} when you need the current status of a specific asset.' It also discloses the CONTRACT-tier API key restriction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_categoriesAInspectCategories 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.
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"
}| Name | Required | Description | Default |
|---|---|---|---|
| categoryId | No | Category identifier | |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden and does so by detailing the six query modes, default root-return behavior, mutual exclusivity, and the 'US only' marketplace constraint. It also documents response codes and includes an example, though it does not detail the exact category object shape returned in data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthier than a minimal tool doc, but it is well organized with a purpose statement, bulleted query modes, examples, and response sections. The main overhead is the embedded output schemas and credit-metadata detail, which are useful but not essential for selecting or invoking the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given six optional parameters, no structured output schema, and no annotations, the description fully covers how to invoke each mode, what the empty-parameter call returns, how to use results in related endpoints, and what response/error shapes to expect. The inclusion of response examples and related tool references makes it complete for safe and correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, so the baseline is 3, but the description adds meaning by explaining that query modes are mutually exclusive, that omitting all parameters returns root categories, and by giving concrete examples like categoryKeyword='yoga' and parentCategoryPath=['Sports & Outdoors']. This goes meaningfully beyond the schema's generic property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Query Amazon category hierarchy by ID, path, parent, or keyword,' a specific verb and resource that immediately identifies the tool's function. It also states the purpose ('discover category structure for filtering in other endpoints') and distinguishes it from sibling category tools by specifying Amazon, not TikTok.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly says 'Use this to discover category structure for filtering in other endpoints' and documents mutually exclusive query modes with a no-parameters root behavior. It points to related endpoints that accept categoryPath, but it does not explicitly list exclusions or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_competitor_product_keywordsBInspectGet competitor product keywords
Return factual keyword coverage for a competitor ASIN in the selected day/week/month period, including impressions, placements, traffic share, estimated keyword search count, and ABA rank.
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[AsinKeywordsData]",
"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"
}| Name | Required | Description | Default |
|---|---|---|---|
| asin | Yes | Amazon Standard Identification Number (10-character alphanumeric). | |
| date | Yes | Lookup date in YYYY-MM-DD format. The response returns the latest snapshot on or before this date. | |
| page | No | Page number. | |
| sortBy | No | Sort field. | trafficShare |
| pageSize | No | Page size. | |
| sortOrder | No | Sort direction. | desc |
| granularity | No | Period granularity. Supports `day`, `week`, and `month`. | week |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | US |
| exploreTypes | No | Optional placement filter. Empty means all result types. Allowed values: ORG/SP/SB/SBV/SPR. | |
| keywordContains | No | Optional substring filter for returned keywords. | |
| keywordAbaRankMax | No | Maximum numeric keyword ABA rank. | |
| keywordAbaRankMin | No | Minimum numeric keyword ABA rank. | |
| keywordEstimateSearchCountMax | No | Maximum estimated keyword search count. | |
| keywordEstimateSearchCountMin | No | Minimum estimated keyword search count. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the main output fields and period granularity, which is helpful. However, with no annotations provided, it lacks important details such as authentication requirements, error conditions, or behavior when no data is available. It is accurate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a crisp two-sentence summary that front-loads the purpose. It is free of fluff and immediately orients the agent on what the tool does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 14 parameters and an output schema, the description gives a high-level overview but lacks guidance on common combinations of filters (e.g., keywordContains, rank bounds) and pagination behavior. It is adequate but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides complete coverage of all 14 parameters with descriptions. The tool description adds minimal extra semantic value beyond what the schema already states, essentially confirming the meaning of 'day/week/month' granularity. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as returning keyword coverage data for a competitor ASIN, listing specific output attributes (impressions, placements, traffic share, etc.). It is specific enough to distinguish it from many siblings though it does not explicitly name alternative tools or contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool instead of similar ones, nor does it mention exclusions or alternatives. It is a plain functional statement without contextual direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_competitorsAInspectCompetitor 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.
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"
}| 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. Only 'US' is currently supported. | 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. |
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 mentions pagination ('results are paginated (max 100 per page)') and data freshness ('Data is based on the latest daily snapshot'), which is useful. However, it does not explicitly disclose whether the operation is read-only or any side effects, though that is implied by 'search'. Given search tools typically don't have hidden destructive behavior, the disclosure is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening description is concise (four sentences), but the overall description field includes large response schemas and examples that significantly bulk it up. While the response schemas are potentially useful, they are verbose and could distract from the core usage guidance. The key information is front-loaded, but the length beyond that reduces its conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential context: what the tool does, when to use it, an example, pagination details, and related tools. It mentions the daily snapshot and pagination limits. The output schema is provided (though not as a separate field, it is embedded in the description), which helps the agent understand the response. Given the high complexity (22 parameters) the description does reasonably well, but it could also mention constraints like the US marketplace or required vs optional, but those are already in the schema. Overall, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema description coverage is 100%, meaning each of the 22 parameters is already documented in the schema. The description does not add much beyond what the schema provides—it mentions the general search dimensions (keyword, brand, ASIN, category) and gives an example with 'asin', but does not elaborate on meaning of individual filters. Since the schema already covers the semantics, this scores at the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search competitor products by keyword, brand, ASIN, or category with filters.' It provides a concrete example with an ASIN and distinguishes itself from the sibling/search tool by mentioning 'Related: /products/search for broader keyword discovery.' This is a specific verb+resource, well-scoped, and clearly differentiates from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use it: 'Use this to identify competing products around a specific listing or brand.' It also gives an example (pass asin=...) and mentions the alternative for broader discovery ('Related: /products/search for broader keyword discovery'), which is good contextual direction, though it doesn't 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_ecommerce_rerankAInspectRerank 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.
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"
}| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the transparency burden. It discloses the scoring mechanism, the underlying model, and credit costs, but it also contains a misleading phrase: 'shared list of product documents' while the input schema requires a list of document lists per query. This inconsistency undermines the agent's understanding of actual behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The main human-readable description is concise and front-loaded with a clear one-liner followed by essential details and credit information. However, the inclusion of a large, redundant response schema block (which does not even detail the 'data' payload) makes the overall description longer than necessary without adding much actionable value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is moderately complex with multiple queries and document lists, and no annotations are present. While the input schema is thorough and the response schema is included, the description fails to clarify the exact structure of the 'data' field (the actual reranked results), and the 'shared list' misstatement leaves the usage ambiguous. More examples or a clearer description of the output would be needed for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, so the baseline is 3. The description adds some context (documents can be titles, descriptions, or attributes) and explains credit costs, but it doesn't compensate for the schema's clarity because it introduces the contradictory 'shared list' notion. The schema's own descriptions are more precise.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Rerank documents for ecommerce search queries') and clearly states its purpose: to improve product search result ordering. It distinguishes itself from sibling search tools by focusing on reranking an existing list of product documents, not searching from scratch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this to improve product search result ordering,' providing clear context for when to invoke this tool. It also explains how to use it (pass queries and documents), but it does not mention alternative tools or when not to use it, stopping short of a full usage guideline.
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_embeddingAInspectGenerate 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.
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"
}| 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. |
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 model (fine-tuned SigLIP2), output dimensionality (768), default L2 normalization (and that it can be disabled), accepted input formats (HTTPS/base64/WebP/JPEG/PNG), and credit usage (1 per request). It also includes a detailed response schema with meta and credit fields. It omits rate limits and error handling beyond 422, but for a read-only embedding generator this is substantial transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening description is concise and front-loaded with the essential info. However, the Responses section includes a full JSON schema with internal ADR-0003 discussions, deprecation TODOs, and repeated example/output schema, adding irrelevant bloat that an agent does not need for tool selection or invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is functionally complete for an agent: it covers what the tool does, how to call it (input constraints, normalization default), what it returns (detailed embedded output schema), and costs (1 credit). The embedded output schema compensates for the missing structured output schema. The internal TODOs degrade readability slightly, preventing a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both imageUrls and normalizeVectors are fully described). The description restates the input formats and default normalization but adds little beyond the schema. It mentions the vectors align with text embedding space, which is output-oriented, not param-specific. The baseline of 3 applies because the schema already carries the parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs: 'Generate fashion image embeddings (768-dim vectors for similarity search)' and 'Encode product images into 768-dim vectors aligned with the text embedding space.' It identifies the resource (fashion product images) and output (768-dim vectors), and distinguishes from siblings like openapi_v2_fashion_image_search and openapi_v2_fashion_text_embedding by emphasizing fashion-specific image embeddings aligned with text space.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases ('visual similarity search, image-to-text matching, duplicate detection, catalog indexing') and clarifies input constraints (HTTPS URLs or base64, max 8 per request, supported formats). It also notes the credit cost. However, it does not explicitly compare with sibling tools or state when not to use this tool, which would make it a 5.
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_searchBInspectSearch 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.
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"
}| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It includes response schemas for success and validation errors, plus metadata like pagination and credit fields, which offers some insight into behavior. However, it does not disclose explicit side effects, permissions, or rate limits, so transparency is partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core description is concise, but it starts with two nearly identical sentences ('Search fashion products by image similarity' and 'Search fashion products by visual similarity to a query image'). The lengthy output schema includes internal TODOs and ADR references ('TODO(2026-11, ADR-0003 §8 +6mo)') that are irrelevant for tool selection and add noise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main usage, optional parameters, and error handling, but does not explain the contents of the 'data' payload beyond the schema's generic 'Response data payload.' It also leaves prerequisites like HTTPS requirement to the schema text. Overall, it is adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description's mention of 'bounding box to focus' and 'text description for better matching' paraphrases the schema field descriptions without adding new meaning beyond what is already in the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Search fashion products by image similarity' and 'Search fashion products by visual similarity to a query image,' clearly specifying the verb (search), resource (fashion products), and method (image similarity). However, it does not explicitly differentiate this from sibling tools like openapi_v2_fashion_similarity or openapi_v2_fashion_product_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: 'Upload an image URL to find visually similar fashion products across the catalog. Optionally specify a bounding box... and add a text description for better matching.' This implies when to use the tool, but does not mention alternatives or say when not to use it, so it falls short of a 5.
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_searchAInspectSearch 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.
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"
}| Name | Required | Description | Default |
|---|---|---|---|
| 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']. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that the search covers 200M+ fashion products and that results include title, brand, price, image, and retailer link. It does not mention rate limits, auth requirements, pagination behavior, or a read-only guarantee, but the nature of a search tool implies read-only. This is moderate transparency, not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The first two sentences are concise and front-loaded with the essential purpose. However, the description is flooded with a large 'Responses' section containing example JSON and an output schema, including verbose metadata about credit fields, ADR-0003, and TODOs unrelated to the search functionality. This boilerplate adds significant noise and does not earn its place for an agent selecting the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core aspects: what the tool does, scale, filters, and result fields. It omits details like result ordering, no-result behavior, and page-size semantics, though the topK parameter is defined in the schema. The huge response schema provides generic metadata but not a complete data structure for search results, so the description is moderately complete for a search tool with well-documented parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions cover 100% of parameters (query, brand, priceMin/Max, sites/excludeSites, topK). The description adds a high-level summary of filtering capabilities ('brand filtering, price range, and retailer domain allowlists/denylists') that maps to the parameters but does not introduce any new meaning beyond the existing schema examples. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search fashion products by text query' and elaborates as 'natural-language text query' and 'Searches across 200M+ fashion products from major retailers.' This clearly specifies the verb (search), resource (fashion products), and scope (text-based, 200M+ products). It distinguishes from sibling image/similarity search tools by emphasizing the text-query nature and fashion focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it supports brand filtering, price range, and retailer domain allowlists/denylists, and returns product title, brand, price, image, and retailer link. However, it does not explicitly state when to prefer this tool over alternatives like openapi_v2_products_search or openapi_v2_fashion_image_search, so no exclusion or alternative guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_fashion_similarityAInspectCompute 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.
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"
}| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description fully discloses behavior: 768-dim encoding, the output score matrix semantics, higher-is-better interpretation, and per-request credit consumption. It also includes the full response schema and error examples, far exceeding bare functionality statements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core explanation is concise and front-loaded, but the description is then padded with extensive response documentation, including ADR-0003 policy details and TODO comments that are irrelevant for tool selection and invocation. This extra verbosity reduces the overall conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a stateless compute tool with two inputs, the description provides complete context: the formula, input constraints via the schema, output format with an example, error responses, and cost. Even though no formal output schema is attached, the description includes the output schema in text, making the context fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are already well-documented in the input schema with 100% coverage, so the baseline is 3. The description reinforces the text-to-image pairing via the similarityScores[i][j] formula but does not add meaningful new parameter-level details beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Compute text-image similarity scores for fashion products', a specific verb+resource statement. It then details the cosine similarity computation and the score matrix semantics (similarityScores[i][j]), making it clearly distinct from sibling embedding and search tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'Equivalent to text-embedding + image-embedding + dot product in one call', which implicitly tells an agent when to use this combined tool rather than composing separate embedding calls. It also notes the 1-credit cost, but does not explicitly name alternatives or state exclusions, preventing a full 5.
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_embeddingAInspectGenerate 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.
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"
}| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It discloses key traits: output dimensionality (768-dim), default L2 normalization (dot product = cosine similarity), alignment with image embeddings, and a fixed credit cost of 1 per request. It does not describe response data fields in detail, but the core compute behavior is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening prose is concise and front-loaded, but the description becomes bloated by embedding a large OpenAPI response block with generic metadata, credit-field deprecation TODOs, and ADR references that are irrelevant to selecting or invoking this tool. Much of this content does not earn its place and obscures the actual result payload.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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, parameters, normalization behavior, and credit cost, and the schema covers parameter constraints. However, there is no actual output schema and the response section only shows a generic wrapper with 'data' as an undefined payload, leaving the embedding result structure undocumented. This is a clear gap for an embedding API.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100% with detailed descriptions for both parameters. The description adds extra meaning by explaining that vectors are 768-dim and aligned with the image embedding space, which clarifies why queries are text strings and reinforces the normalizeVectors default. This goes slightly beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Generate fashion text embeddings' and 'Encode fashion text into 768-dim vectors', clearly distinguishing it from sibling image-embedding tools (e.g., openapi_v2_fashion_image_embedding). It also names concrete use cases (text-to-image search, semantic product matching, catalog indexing), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use cases and context: it is for fashion-specific text aligned with the image embedding space, and mentions 768-dim vectors for similarity search. It does not explicitly name alternative tools or state when not to use it, but the positioning against image embeddings and sibling names is sufficient for most selection decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_image_detectionAInspectDetect 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.
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"
}| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
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 does disclose the credit cost ('Credits: 1 credit per request') and the return structure (bounding boxes, categories, confidence), but it does not mention potential side effects, data retention, or authorization requirements. The embedded output schema adds some transparency but is mostly auto-generated boilerplate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core description is only a few sentences, but it is followed by an extensive inline output schema and response examples that are better placed in a dedicated output schema. This makes the description overly long and violates conciseness. The essential information is front-loaded, but the bulk is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the verbosity, the description covers the key aspects: what the tool returns, the input parameter types (via schema), and the response structure including error cases. It even includes credit-related fields. The lack of annotations is partially compensated by the detailed response schema, though alternative tool selection guidance is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 only reiterates the classes parameter ('Use the classes parameter to filter for specific fashion categories') which is already fully explained in the schema. No additional semantic value is added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 and returns bounding boxes, category classification, and confidence scores. This specific verb+resource+output distinguishes it from sibling tools like openapi_v2_fashion_image_search or openapi_v2_image_embedding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied through 'Detect fashion items in an image and return their bounding boxes' and the note to use the classes parameter for filtering. However, there is no explicit comparison or guidance on when to choose this tool over similar fashion-related siblings, nor any 'when not to use' exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_image_embeddingBInspectGenerate 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.
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"
}| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral details. It discloses the credit cost ('1 credit per request') and that it automatically detects fashion items, which is useful. However, it does not describe side effects, rate limits, or error handling beyond the response schemas. Adds some context but remains incomplete for a complex image-processing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core description is front-loaded and concise, but the overall field includes extensive response documentation with JSON schemas for 200 and 422, making it verbose. While these may be standard for OpenAPI, the volume of redundant schema details (e.g., full meta schema) dilutes the description's focus. The essential content is efficient, but the overall structure is not.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is moderately complex with 7 parameters, but the description lacks details about the shape of the data payload. The output schema for 'data' is not provided (only meta is described), so the agent cannot anticipate the structure of embeddings or tags. The description does not cover error scenarios beyond a generic 422. Missing critical context for interpreting results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all 7 parameters with clear descriptions, and schema coverage is 100%. The description adds minimal extra value by mentioning optional tag inclusion and relevance scores, aligning with withTag and text. It does not elaborate on parameter usage beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Generate fashion item embeddings from images' and elaborates on detecting fashion items and producing embeddings for similarity search, recommendations, etc. It is specific and concrete. However, it does not differentiate from the near-identical sibling 'openapi_v2_fashion_image_embedding', missing the chance to distinguish between them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage by mentioning use cases such as 'visual similarity search, product recommendations, and image-based product matching,' which indicates when the tool might be appropriate. It does not explicitly state when not to use it or alternative tools, especially the similar sibling. Lacks clear decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_keyword_detailBInspectGet keyword detail
Agent-only batch response contract. Return core search, competition, and advertising metrics for one or more keywords on a specific snapshot date; single-keyword requests also return data.context + data.items[].
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[KeywordDetailData]",
"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"
}| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Lookup date in YYYY-MM-DD format. Returns the latest weekly snapshot on or before this date. | |
| keyword | No | Keyword to look up. | |
| keywords | No | Keywords to look up in batch, up to 20. | |
| granularity | No | Time granularity. Keyword detail currently supports `week` only. | week |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | US |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No behavioral traits are disclosed. There is no mention of side effects, permissions, rate limits, or data retention. The phrase 'Agent-only' is vague. With no annotations to supplement, this score is low.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core description is concise but is buried under extensive response schema documentation and examples. The lengthy JSON blocks are not necessary for understanding the tool's purpose and make the description overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides response structure and highlights batch vs. single-keyword differences, which is helpful. However, it omits context like error handling details (beyond 422) and does not mention any prerequisites or limitations beyond the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters with detailed descriptions, so the baseline is 3. The description does not add any additional meaning beyond what is already in the schema, such as clarifying the 'core metrics' or how the date is used.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns keyword detail metrics (search, competition, advertising) for one or more keywords on a specific date. It distinguishes between batch and single-keyword responses, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Agent-only' and the ability to request data for a snapshot date, but does not explicitly compare to sibling tools like keyword_trend or keyword_market_profile. It implies use for detailed metrics but lacks clear 'when to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_keyword_extendsBInspectGet keyword expansions
Return expanded keywords related to the seed keyword with search volume, rank, and relevance metrics. Supports phrase and fuzzy expansion.
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[KeywordExtendsData]",
"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"
}| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number. | |
| query | Yes | Seed keyword. | |
| sortBy | No | Sort field. | relevanceScore |
| pageSize | No | Page size. | |
| queryType | No | Keyword expansion mode. Supports `phrase` and `fuzzy`; `exact` is not supported. | phrase |
| sortOrder | No | Sort direction. | desc |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | US |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are not provided, so the description carries the burden. It discloses that 'exact' is not supported (though that's in the schema) and mentions expansions return metrics. It doesn't disclose pagination behavior, rate limits, or auth requirements. The description largely reiterates schema details (like queryType enums) without adding deeper behavioral context. It does provide response examples but those are part of the spec, not behavior. Given no annotations, it's acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively compact but includes a large output schema block and extensive response documentation, which is verbose and not front-loaded. The first sentence is clear, but the description could be more concise by removing the full OpenAPI response examples, which are redundant with the output schema. It's adequately sized but not tightly optimized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 7 parameters, 3 with enums, and no annotations. The description covers the core purpose and mentions the main modes, but does not explain sorting options, pagination behavior, or the meaning of metrics like 'abaRank' or 'estimateSearchCount' beyond what the schema says. The output schema is embedded, so return format is explained, but completeness could be improved with brief usage guidance or examples.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds minimal extra meaning: it says 'expanded keywords related to the seed keyword' and mentions 'phrase' and 'fuzzy' expansion, but doesn't go beyond what the schema provides (e.g., 'Seed keyword.', 'Keyword expansion mode.'). Baseline 3 is appropriate since the description doesn't add significant semantics not already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get keyword expansions' and explains it returns expanded keywords related to the seed keyword with search volume, rank, and relevance metrics. This is a specific verb+resource. However, it doesn't strongly differentiate from sibling tools like openapi_v2_keyword_detail or openapi_v2_keyword_market_profile, though 'extends' is distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions supports 'phrase' and 'fuzzy' expansion, implying when to choose these modes, but does not explicitly state when to use this tool versus alternatives like keyword_detail or keyword_market_profile. It lacks clear guidance on use cases or exclusions, but the sibling tools are numerous and related, so more explicit differentiation would help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_keyword_market_profileBInspectGet keyword market profile
Get multidimensional keyword profile metrics for one or more keywords on a specific snapshot date, including demand scale, Top 3 concentration, ad activity, organic entry difficulty, supply saturation, brand structure, and organic product benchmarks. Results are returned in request keyword order; single-keyword requests also return data.context + data.items[]. Batch requests are ultimately billed by the number of keywords with status=ok, and the actual charge is returned in meta.creditsConsumed.
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[KeywordMarketProfileData]",
"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"
}| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Lookup date in YYYY-MM-DD format. Returns the latest weekly snapshot on or before this date. | |
| keyword | No | Keyword to look up. | |
| keywords | No | Keywords to look up in batch, up to 20. | |
| granularity | No | Time granularity. Keyword detail currently supports `week` only. | week |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | US |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does a good job: it discloses that results are returned in request keyword order, single-keyword requests return additional data.context/data.items, and batch billing depends on keywords with status=ok with actual charges in meta.creditsConsumed. This goes beyond a generic 'get' and reveals meaningful runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening paragraph is concise and useful, but the description is heavily padded with auto-generated OpenAPI response schemas, including internal ADR references and TODO deprecation timelines that are irrelevant to tool selection or invocation. This bloat hurts scannability and violates concise documentation principles.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (5 params, batch mode, billing behavior), the description covers purpose, parameter usage, return order, and billing semantics. It lacks a detailed schema for data.items and explicit usage guidance, but for a read-only market-profile lookup it is largely sufficient to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, and each parameter already has a clear description (date format, keyword, keywords batch limit, granularity, marketplace). The tool description does not add significant semantic detail beyond the schema, but it reinforces that one or more keywords can be queried. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and the resource ('keyword market profile'), then elaborates with specific metric categories (demand scale, Top 3 concentration, ad activity, etc.). It is unambiguous and distinct from sibling tools like keyword_trend or keyword_detail, though it does not explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but provides no guidance on when to choose it over the many sibling keyword tools (e.g., keyword_trend_profile, keyword_extends). There are no usage conditions, prerequisites, or explicit exclusions, so an agent is left to infer its place among alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_keyword_search_resultsAInspectGet keyword search results
Return factual product listings and absolute ranking positions for a keyword in the selected day/week/month period, with optional placement filtering. SERP aggregates and keyword market metrics are intentionally excluded and provided by dedicated metric endpoints.
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[KeywordSearchResultsData]",
"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"
}| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Lookup date in YYYY-MM-DD format. The response returns the latest snapshot on or before this date. | |
| page | No | Page number. | |
| sortBy | No | Sort field. | absolutePosition |
| keyword | Yes | Keyword to search. | |
| pageSize | No | Page size. | |
| sortOrder | No | Sort direction. The default `absolutePosition asc` returns the lowest rank numbers first. | asc |
| granularity | No | Period granularity. Supports `day`, `week`, and `month`. | week |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | US |
| exploreTypes | No | Optional placement filter. Empty means all result types. Allowed values: ORG/SP/SB/SBV/SPR. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the full burden. It explicitly discloses a key behavior: 'SERP aggregates and keyword market metrics are intentionally excluded,' preventing the agent from expecting those results. It also mentions 'factual product listings and absolute ranking positions,' setting accurate expectations. However, it does not address typical behavioral aspects like idempotency, rate limits, or whether the operation modifies data (though 'get' implies read-only). The exclusion note is valuable and earns a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core description is two sentences, front-loaded with the action verb 'Get' and immediately clarifying the scope and exclusions. Every word earns its place. It does not repeat schema fields or over-explain. This is a model of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters and 2 required, the description covers the main purpose, exclusions, and time/placement flexibility. It could also mention the marketplace constraint (US-only) in prose, but that is available in the schema. The provided response schemas include extensive metadata (credits, pagination), so the agent has enough context to invoke the tool correctly. A 4 reflects that it is complete but could be slightly more explicit about constraints like marketplace support.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 per the rubric. The prose 'optional placement filtering' adds a tiny bit of context for `exploreTypes`, but the parameter descriptions in the schema are already comprehensive (e.g., date, sortBy, exploreTypes). The description does not significantly enhance understanding beyond what the schema provides, so a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Get keyword search results' and immediately specifies 'Return factual product listings and absolute ranking positions for a keyword in the selected day/week/month period, with optional placement filtering.' This clearly states the verb, resource, and key scoping (time period, placement). It also distinguishes itself from siblings by explicitly excluding SERP aggregates and market metrics, which are handled by dedicated endpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear 'when not to use' hint: 'SERP aggregates and keyword market metrics are intentionally excluded and provided by dedicated metric endpoints.' This tells the agent that for such data, other tools should be used, though it does not name the specific sibling tools. It does not explicitly say 'use this for X' or give a when-to-use, so it misses a perfect score but is quite clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_keyword_trendAInspectGet keyword trend
Agent-only batch response contract. Return weekly time-series trend metrics for one or more keywords, including snapshot data between dateFrom and dateTo; single-keyword requests also return data.context + data.items[].series[]. The date range cannot exceed 93 days; split longer history into multiple requests.
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[KeywordTrendData]",
"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"
}| Name | Required | Description | Default |
|---|---|---|---|
| dateTo | Yes | Trend end date in YYYY-MM-DD format. The response contains weekly snapshots within the requested date range. | |
| keyword | No | Keyword to look up. | |
| dateFrom | Yes | Trend start date in YYYY-MM-DD format. The response contains weekly snapshots within the requested date range. | |
| keywords | No | Keywords to look up in batch, up to 20. | |
| granularity | No | Time granularity. Keyword trend currently supports `week` only. | week |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | US |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden. It transparently covers the 93-day limit, single vs batch response differences, and the deposit notation about exact credits. It doesn't detail pagination or token usage behavior, but the rich schema already specifies response fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then provides operational rules, structured logically (batch response contract, date limit, responses). The only clutter is the verbose API-response documentation with redundant example JSON and credit ADR details, which could be trimmed, but the essential guidance is concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity (6 params, 2 required, no enums) and no output schema, so the description must cover response shape. It explains the weekly snapshot behavior and single vs batch outputs, but does not list possible error conditions other than validation 422, nor does it mention marketplace limitations beyond 'US'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter coverage with descriptions including formats and constraints (e.g., date format, max 20 keywords, only 'week' and 'US'). The description adds nuanced semantics: the 93-day split guidance and clarified that 'keyword' vs 'keywords' are exclusive modes, which goes beyond schema basics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns weekly time-series trend metrics for keywords, specifying response granularity and date-range constraints. It distinguishes itself from sibling tools like keyword_detail and keyword_trend_profile by focusing on time-series trend data, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit operational constraints (93-day max range, splitting longer history) and indicates batch vs single-keyword behavior, giving clear context for when to call it repeatedly. However, it doesn't contrast with sibling trend-related tools (keyword_trend_profile) to guide alternative selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_keyword_trend_profileCInspectGet keyword trend profile
Return precomputed trend profiles for one or more keywords over fixed 4, 8, 12, or 26-period windows, preserving keyword and requested-window order. A keyword is billed once when at least one window profile is available.
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[KeywordTrendProfileData]",
"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"
}| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Lookup date in YYYY-MM-DD format. Returns the latest weekly snapshot on or before this date. | |
| keyword | No | Keyword to look up. | |
| keywords | No | Keywords to look up in batch, up to 20. | |
| granularity | No | Time granularity. Keyword detail currently supports `week` only. | week |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | US |
| windowPeriods | Yes | Fixed period counts for the analysis windows. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It reveals useful behavioral details: data is 'precomputed', keyword/window order is preserved, and billing happens once per keyword if at least one window profile is available. However, it omits what happens when no data exists for a keyword/window, whether responses only include successful windows, or any rate-limit/error handling beyond the generic 422 validation response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core functional description is appropriately short and front-loaded: two sentences covering the essential behavior and billing. However, the description field is padded with an extensive output schema dump containing irrelevant details like ADR-0003 credit field deprecation TODOs and a note that tokensUsage is populated only on 'terminal video polls'. This boilerplate detracts from conciseness and does not help tool selection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is moderately complex with 6 parameters, batch capabilities, and multiple window options, yet the description never explains what a 'trend profile' actually contains or how the returned data is structured. The provided output schema only documents the generic response wrapper (meta, success, error), not the KeywordTrendProfileData payload. There is also no guidance on keyword vs. keywords usage or how missing profiles are represented, making the description incomplete for an agent to fully understand the response and limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 adds a few helpful semantics, especially the date parameter's 'latest weekly snapshot on or before this date' and the explicit window set. However, it does not clarify the relationship between 'keyword' and 'keywords' (e.g., whether both can be supplied, which takes precedence, or expected mutual exclusion), which is a notable semantic gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'Get keyword trend profile' and explains that it returns 'precomputed trend profiles for one or more keywords over fixed 4, 8, 12, or 26-period windows'. This is a specific verb + resource + scope, and the 'precomputed' and fixed-window framing implicitly distinguishes it from sibling tools like keyword_trend or keyword_detail, though no explicit sibling comparison is made.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as openapi_v2_keyword_trend or openapi_v2_keyword_detail. It does not state whether this profile endpoint should be preferred for batch/historical analysis, nor does it mention any conditions or exclusions. The only context clues are the billing note and fixed windows, which relate to behavior rather than usage selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_markets_searchAInspectMarkets 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.
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"
}| 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. Only 'US' is currently supported. | 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries behavioral burden. It discloses data source (top-100 sample), recency (daily snapshot), and pagination (max 100/page). However, it omits critical behavioral constraints like unsupported `sampleType` values (byBsr100, avg) and that marketplace only supports 'US' — both known from schema but not highlighted in prose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with purpose, then usage, then data facts. No fluff; each sentence adds value. Response schemas are provided separately and do not bloat the textual description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 59 parameters and no annotations, the description offers a use case, data scope, and pagination info, and includes response schemas. However, it fails to caution about unsupported parameter values (sampleType) or the US-only marketplace, which are critical for correct invocation. It also doesn't explain the overall filter semantics beyond the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all 59 params have descriptions). The description adds a usage example referencing `sampleAvgMonthlySalesMin`, but does not provide additional semantics beyond the schema's already detailed parameter descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Search market data by category with aggregated demand, competition, and pricing metrics' — specific verb and resource. It distinguishes from sibling `/products/search` by pointing to 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use for evaluating market size/competition before entering a niche, provides an example with a concrete filter, and names a related endpoint for alternative data. Clear when-to-use guidance with a concrete scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_products_historyAInspectProduct 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.
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"
}| 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. Only 'US' is currently supported. | US |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full disclosure burden, and it delivers: it reveals non-obvious behaviors like high-frequency metrics 'as daily arrays aligned with timestamps' and low-frequency fields 'as changelog entries that only record changes,' plus the maximum range cap. This is genuinely behavior-revealing detail an agent couldn't infer elsewhere. No annotations exist to be contradicted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four dense, purposeful sentences, front-loaded with purpose and ending with a useful related-endpoint pointer. Each sentence earns its place. Slight deduction because the overall tool entry is bloated by the extensive generic response output schema (credits, pagination), though that padding lives outside the description itself.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter read endpoint with fully documented schema, the description is largely complete: it covers input semantics, output shape, critical constraints (730-day ceiling), and next steps. The most notable gap is ignoring the pagination/credits fields in the meta block (page, pageSize, tokensUsage) that appear in the response schema but are never addressed—leaving ambiguity about whether this endpoint paginates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema description coverage is 100%, so the baseline is 3 per the rubric. The description reinforces param intent ('single ASIN,' 'date range,' '730 days') but adds little beyond the schema's existing per-parameter descriptions. No deduction needed, but the description earns no credit for compensating since no gap exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource+scope: 'Get historical time-series data for a single ASIN over a date range.' The description adds strong specifics about return format (columnar arrays, changelog entries) not visible in the schema. It stops short of a 5 because it doesn't explicitly contrast itself with the closely-related sibling openapi_v2_realtime_product, which would fully disambiguate it among the 50+ siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description references '/products/search to discover ASINs first,' establishing a sensible prerequisite workflow, and notes the 730-day max range. However, it never explicitly states when to choose this over the realtime product or search siblings—it only implies the historical-vs-realtime distinction. Useful context, but no explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_products_leaderboardAInspectProducts Leaderboard V2
Return a product-level Top-N leaderboard for a category.
sales ranks by monthly sales, surging by sales growth, and
newRelease ranks Amazon New Release products by monthly sales.
Related: /products/search for custom filters and sorting.
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"
}| Name | Required | Description | Default |
|---|---|---|---|
| pageSize | No | Number of ranked products to return. | |
| rankType | Yes | Leaderboard type: sales, surging sales, or Amazon New Release products. | |
| dateRange | No | Null or '30d' for the latest snapshot, or an available YYYY-MM month. | |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | US |
| categoryPath | Yes | Category hierarchy from root to the target category. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is transparent about the operation being a read-only query (no side effects mentioned). It does not hide any potential costs or limitations beyond what is inherent in the request. Since no annotations are provided, the description carries the burden, and it does not mislead.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it starts with the core purpose, then details the rank types in a bullet-like style, and ends with a related tool reference. No redundant or vague phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential context: what the tool does, how rank types differ, and a pointer to an alternative. It does not explicitly mention pagination or the output structure, but the input schema already includes pageSize and the output schema is provided in the response section. This is sufficient for a simple read endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have descriptions in the schema, and the tool description adds extra clarity, especially for the rankType parameter by explaining what each enum value means in business terms. This goes beyond the schema's basic description, providing full semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Return a product-level Top-N leaderboard for a category.' It also specifies the different rank types (sales, surging, newRelease) with their meanings, distinguishing it from other product-related tools like search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on when to use this tool versus alternatives by mentioning 'Related: /products/search for custom filters and sorting.' This implies that the leaderboard is for predefined ranking types, while search is for custom queries. However, it doesn't explicitly state conditions for choosing one over the other, so a small deduction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_products_searchAInspectProducts 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.
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"
}| 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. Only 'US' is currently supported. | 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that data is a daily snapshot and results are paginated with a max of 100 per page. It also embeds the response schema (showing pagination metadata and credits), though it does not discuss rate limits or explicitly state read-only behavior. The prose adds meaningful behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The prose is concise and front-loaded, but the description includes a massive '### Responses' section with full response schemas, ADR credit details, and TODO comments. This bloat detracts from conciseness. Every sentence and line does not earn its place; much of the response schema is unnecessary for tool selection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (54 parameters, no annotations, no output schema), the description covers purpose, usage, data freshness, pagination, and related tools. It includes response schemas to compensate for the missing output schema. Minor gaps exist (e.g., whether keyword is required), but overall it is quite complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 adds a concrete example using monthlySalesFloor and price, which maps to monthlySalesMin and priceMax, but it does not explain any parameters beyond what the schema already provides. No new semantic meaning is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Products Search V2' and a clear verb-resource-scope statement: 'Search Amazon products by keyword, category, and multi-dimensional filters.' It distinguishes the tool from siblings by naming related endpoints for competitors and history, and the use cases (niche discovery, competitor listing analysis, opportunity finding) give specific context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('Use this to discover products in a specific niche, analyze competitor listings, or find high-demand low-competition opportunities') and provides a concrete filter example. It also mentions related endpoints for competitor analysis and trends, but stops short of explicitly saying 'do not use this for X; use Y instead.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_product_traffic_termsBInspectGet product traffic terms
Return factual keyword coverage for an ASIN in the selected day/week/month period, including impressions, placements, traffic share, estimated keyword search count, and ABA rank.
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[AsinKeywordsData]",
"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"
}| Name | Required | Description | Default |
|---|---|---|---|
| asin | Yes | Amazon Standard Identification Number (10-character alphanumeric). | |
| date | Yes | Lookup date in YYYY-MM-DD format. The response returns the latest snapshot on or before this date. | |
| page | No | Page number. | |
| sortBy | No | Sort field. | trafficShare |
| pageSize | No | Page size. | |
| sortOrder | No | Sort direction. | desc |
| granularity | No | Period granularity. Supports `day`, `week`, and `month`. | week |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | US |
| exploreTypes | No | Optional placement filter. Empty means all result types. Allowed values: ORG/SP/SB/SBV/SPR. | |
| keywordContains | No | Optional substring filter for returned keywords. | |
| keywordAbaRankMax | No | Maximum numeric keyword ABA rank. | |
| keywordAbaRankMin | No | Minimum numeric keyword ABA rank. | |
| keywordEstimateSearchCountMax | No | Maximum estimated keyword search count. | |
| keywordEstimateSearchCountMin | No | Minimum estimated keyword search count. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must bear the full burden. It only mentions the date lookup behavior ('latest snapshot on or before this date') and lists metrics. It does not disclose read-only nature, rate limits, pagination handling, or any potential side effects. The extensive meta schema about credits is present but that is structured output, not behavioral transparency for invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core description is only two sentences, but the overall text is bloated with extensive response examples and output schemas, including a highly verbose metadata section about ADR-0003 credit fields and deprecation TODOs. This adds noise and reduces conciseness. The structure is organized with headers, but the volume of boilerplate outweighs the useful content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 14 parameters, the description attempts to provide response examples and output schemas, but the key 'data' payload remains undefined ('Response data payload'), leaving agents uncertain about the actual response structure. It also lacks error handling details beyond a generic 422 example. The mention of returned metrics helps, but completeness is hampered by incomplete data schema and excessive unrelated metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The tool description text adds no parameter-level semantics beyond what the input schema already provides. The date parameter description includes the 'latest snapshot' nuance, but that is part of the schema, not the tool description. No additional context is provided for filters or sort options.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get product traffic terms' and elaborates with 'Return factual keyword coverage for an ASIN in the selected day/week/month period, including impressions, placements, traffic share, estimated keyword search count, and ABA rank.' This is a specific verb+resource with explicit output metrics, effectively distinguishing it from sibling tools like profile/timeline variants by its focus on keyword-level traffic data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention scenarios, exclusions, or compare with sibling tools such as product_traffic_terms_profile or timeline. The context signals list many siblings, but the description offers no decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_product_traffic_terms_profileBInspectGet product traffic terms profile
Return current-versus-previous weekly traffic profiles for up to 20 ASINs, including traffic scale, explore-type structure, first-three-page organic structure, and Top 10 change drivers. Only items with status=ok are charged.
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[ProductTrafficTermsProfileData]",
"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"
}| Name | Required | Description | Default |
|---|---|---|---|
| asin | No | Single ASIN; mutually exclusive with asins. | |
| date | Yes | Lookup date in YYYY-MM-DD format. | |
| asins | No | ASIN batch; mutually exclusive with asin, up to 20. | |
| granularity | No | Time granularity. Currently only week is supported. | week |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | US |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Important behavioral detail: 'Only items with status=ok are charged' – this clarifies billing, which is useful. However, the description does not disclose other aspects such as whether the tool is read-only, expectations on the status field, or that it may return nulls/errors. Since annotations are completely absent, the description carries the full burden, and it only partially delivers. No contradiction, but significant gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise: the core behavioral text is two sentences, then it embeds the entire output schema as JSON blocks. This bloats the token count significantly, but the structure is clear and front-loaded with the purpose. The embedded schema redundancy is acceptable given API documentation conventions, but it is verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (5 parameters, with mutual exclusivity constraints), the description is sufficient for basic usage. It mentions the limit of 20 ASINs and the chargable status. However, it lacks guidance on error handling or edge cases (e.g., what happens when asin and asins are both given). Since the output schema covers return fields, that part is complete, but a 4 is appropriate as there is minor room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter-specific details beyond the schema, but schema coverage is 100% with descriptive text for each parameter (e.g., 'mutually exclusive with asins', 'up to 20'). The context signals confirm high coverage, so the baseline of 3 is appropriate. The description does not need to repeat schema, and it doesn't.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get product traffic terms profile' and specifies the resource (ASINs), the data (traffic profiles), and the temporal scope (current-versus-previous weekly). It also lists concrete data products (traffic scale, explore-type structure, first-three-page organic structure, Top 10 change drivers), which distinguishes it from sibling tools like openapi_v2_product_traffic_terms and openapi_v2_product_traffic_terms_timeline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells what the tool does but does not provide explicit instructions on when to use it versus alternatives. It mentions a limit of 20 ASINs and that only items with status=ok are charged, but does not state when to prefer this over the timeline or the base terms tool. No exclusion conditions or alternative tool names are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_product_traffic_terms_timelineAInspectGet product traffic-term timeline
Return the factual product traffic-term timeline for an ASIN and up to 20 keywords. The sparse day/week/month series contains periods matched by the TVF, with keyword estimated search count and ABA rank, product snapshots, plus impression, position, and ad-activity evidence split by ORG/SP/SB/SBV/SPR. Range limits are 93 days, 26 weeks, and 12 months respectively. Only items with status=ok are charged.
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[ProductTrafficTermsTimelineData]",
"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"
}| Name | Required | Description | Default |
|---|---|---|---|
| asin | Yes | Amazon Standard Identification Number (10-character alphanumeric). | |
| dateTo | Yes | End date in YYYY-MM-DD format. | |
| keyword | No | Exact keyword to query. Mutually exclusive with `keywords`. | |
| dateFrom | Yes | Start date in YYYY-MM-DD format. | |
| keywords | No | Keywords to query for the same ASIN in batch, up to 20. Mutually exclusive with `keyword`. | |
| granularity | No | Period granularity. Supports `day`, `week`, and `month`. | week |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | US |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses charging behavior (only status=ok charged), range limits, and the factual nature of data. It does not mention pagination, but the output schema shows pagination metadata fields, which partially covers that. The metadata block is extensive but is auto-generated response schema, not behavioral transparency. Overall, good disclosure of key cost and scope traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a concise summary, but then includes a large auto-generated response schema block that adds no direct value beyond what the agent can derive from the schema. The description's value is concentrated in the first two sentences; the rest is boilerplate. This is acceptable but not lean.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Considering the tool is a read-only query with rich output schema (in description), 7 params, and no annotations, the description is complete enough. It specifies range limits, charging policy, and data components. The output schema includes pagination and credit fields, so return values are covered. Minor gap: no explicit mention of sorting or rate limits, but that's minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% per context signals, so baseline is 3. The description adds value by explaining keyword limit (20), mutual exclusivity of keyword vs keywords (though this is also in schema), and granularity options with range limits. It does not add syntax details for date format since schema already specifies YYYY-MM-DD, and schema covers all params. Given near-100% coverage, the minor added value justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the 'product traffic-term timeline' for an ASIN and up to 20 keywords, with specific data components (keyword search counts, ABA rank, product snapshots, impression/position/ad-activity evidence). This distinguishes it from siblings like openapi_v2_product_traffic_terms and openapi_v2_product_traffic_terms_profile, which likely return different views of similar data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: it returns 'factual' timeline data with range limits (93 days, 26 weeks, 12 months) and identifies that only items with status=ok are charged. It doesn't explicitly state when not to use it or name alternatives, but the scope and limitations are clear, and the sibling names imply alternatives for static traffic terms.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_realtime_productAInspectRealtime 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.
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"
}| Name | Required | Description | Default |
|---|---|---|---|
| asin | Yes | Amazon Standard Identification Number | |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | US |
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 legacy response shape, the deprecation status, and includes extensive response schemas with details like credits fields and tokensUsage behavior. It does not mention permissions or side effects, but as a read-only product fetch, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening sentences are concise and front-loaded with the deprecation notice and migration path. However, the embedded response schemas make the description quite long. The structure is logical with clear headings, and every section provides useful information, but it could have been trimmed if output schemas were stored separately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is fully complete for a simple 2-parameter tool. It covers the deprecation, legacy shape, response examples, and full output schemas. The alternative v3 tool is named, and the input schema is already self-documenting. There is no missing context for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 parameter-specific semantics beyond what the schema already provides—no additional explanation of asin or marketplace is given. The legacy shape note references response structure, not input semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this is the legacy realtime product tool returning the pre-#327 response shape, and explicitly distinguishes it from the v3 sibling. It names the alternative tool (openapi_v3_realtime_product) and explains the key differences (opaque fields, variants keyed by dimensions, no top-level price).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says the tool is deprecated and points to openapi_v3_realtime_product as the replacement. It explains the tool is kept for backward compatibility and advises migration, giving clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_realtime_reviewsAInspectRealtime 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, /voc/analysis for aggregated insights.
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"
}| 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 code. Only 'US' is currently supported. | US |
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 pagination contract and the real-time nature of the data, but does not mention prerequisites, rate limits, authentication, or side effects. The detailed output schema (credits, metadata) is embedded but not explained as behavioral traits. This is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The narrative part is concise and front-loaded with purpose and pagination. The appended responses and output schemas are lengthy but necessary because there is no separate output schema field. The structure is clear, with a logical flow from purpose to usage to responses.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential aspects: purpose, pagination, related endpoints, and response formats including error handling. It lacks comparison to other realtime tools like openapi_v2_realtime_product, but the mention of two key alternatives is sufficient. Given the tool's moderate complexity, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter already having descriptive text. The description repeats the cursor usage guidance from the schema but adds no new meaning for asin or marketplace. Since the schema already carries the weight, and the description provides minimal additive detail, 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch realtime reviews for a given ASIN' with a specific verb and resource. It also distinguishes from related tools by naming /reviews/search and /voc/analysis, and explicitly labels it as version V2, providing differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit pagination instructions: omit cursor for first page, pass nextCursor for subsequent pages, and nextCursor=null indicates no more data. It also names alternative endpoints for different use cases (AI tags and aggregated insights), giving clear guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_reviews_searchAInspectReviews 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, /voc/analysis for aggregated insights.
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"
}| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses data source, pagination, sorting, and detailed response metadata including credit fields. However, it lists 'AI-generated tags' as a filter even though no corresponding parameter exists in the input schema, which could mislead an agent. With no annotations provided, the description carries the full burden but this inconsistency reduces transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description opens with a concise summary and then provides extensive response documentation including example payloads and output schemas. While long, it is organized and front-loaded with key information. Some ADR/TODO details are tangential but do not significantly hurt usability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter search tool with no structured output schema, the description covers data source, filters, sorting, pagination, related tools, and error formats. It would be more complete if it clarified the AI-generated tags filter or omitted it, but overall it provides sufficient context for a typical agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 12 parameters have descriptions in the input schema (100% coverage), so the baseline is 3. The description reiterates the filter categories (star rating range, date range, etc.) but doesn't add meaning beyond the schema. The mention of AI-generated tags is not backed by a parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search reviews for an ASIN with multi-dimensional filters' in the first lines, with a specific verb, resource, and scope. It also lists filter categories and distinguishes this tool from realtime and VOC analysis via the 'Related' line.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description names two related tools ('/realtime/reviews for live data, /voc/analysis for aggregated insights') and notes that data comes from a daily BigQuery snapshot, indicating this is for historical/filtered review data. While not phrased as 'use instead', it provides enough context for appropriate selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_tiktok_categoriesAInspectTiktok 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.
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"
}| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It delivers several important traits: query modes are 'mutually exclusive,' the tree is 'English-only and global (not region-scoped),' and 'productCount reflects the latest US-region snapshot (v1).' It also states that no parameters returns all root categories and that categoryKeyword does substring matching. These go beyond the basic purpose and help the agent invoke the tool correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core description is well-structured with a clear first sentence, bulleted query modes, and a related-usage note. However, it is significantly bloated by a lengthy response schema section that includes internal TODOs about credit deprecation (ADR-0003). This material is not directly relevant to selecting or invoking the tool and makes the description overly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is fairly complete for a query tool: it covers all five parameters, mutual exclusivity, expected response behavior (e.g., no-param returns roots), and a related endpoint. Though the structured output schema is absent, the description includes an output schema with meta fields. It lacks explicit pagination details (e.g., whether results are paginated) but the response schema includes page/pageSize fields, so the agent has enough context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 adds valuable meaning beyond the schema by explaining that query modes are mutually exclusive and providing an explicit example: passing `parentCategoryPath=["Automotive & Motorcycle"]` to enumerate direct children. It also clarifies the no-parameter mode (returns all root categories), which is not obvious from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Query the TikTok Shop category tree by ID, path, parent, or keyword.' It specifies the resource (TikTok Shop category tree), the verb (query), and the various lookup modes. It also distinguishes itself from the sibling 'openapi_v2_categories' by explicitly targeting TikTok Shop and connecting to '/tiktok/products/search'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use-case context: 'Use this to discover the category hierarchy for filtering in /tiktok/products/search.' It also notes related usage with '/tiktok/products/search accepts categoryId or categoryPath for filtering.' However, it does not explicitly mention when to avoid this tool or name alternatives (e.g., openapi_v2_categories for non-TikTok contexts), so it falls short of a 5.
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_searchAInspectTiktok 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. carryVideoSales30d / carryVideoRevenue30d are creator-attributed lower bounds (only carry videos with at least 500 plays are counted) and are available as sortBy values; results sort by relatedProductSaleAmt30d descending unless sortBy is set.
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"
}| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-indexed page number. | |
| sortBy | No | Sort field for creator search, e.g. carryVideoRevenue30d / carryVideoSales30d for creator-attributed carry performance. Default relatedProductSaleAmt30d. | 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. | |
| carryVideoSales30dMax | No | Maximum units sold over the trailing 30 days attributed to this creator's carry videos. Creator-attributed lower bound; counts only carry videos with at least 500 plays. | |
| carryVideoSales30dMin | No | Minimum units sold over the trailing 30 days attributed to this creator's carry videos. Creator-attributed lower bound; counts only carry videos with at least 500 plays. | |
| carryVideoRevenue30dMax | No | Maximum GMV over the trailing 30 days attributed to this creator's carry videos, in USD. Creator-attributed lower bound; counts only carry videos with at least 500 plays. | |
| carryVideoRevenue30dMin | No | Minimum GMV over the trailing 30 days attributed to this creator's carry videos, in USD. Creator-attributed lower bound; counts only carry videos with at least 500 plays. | |
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses important behavioral traits: data is from a daily snapshot, related-product sales are not creator-attributed, carryVideoSales30d/Revenue30d are lower bounds with a 500-play threshold, and default sorting behavior. This adds significant value beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise, with a clear opening sentence and a focused paragraph on data semantics. It front-loads the purpose and then adds important caveats. The response examples are verbose but are part of the schema, not the description itself. Slightly long but justified by the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (32 parameters, no annotations, no output schema), the description covers key behavioral nuances: data freshness, attribution differences, sorting defaults, and region. It doesn't explain return value structure, but the output schema is provided in the description, so that's covered. It's complete enough for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 32 parameters. The description adds context for key parameters like carryVideoSales30d and relatedProductSaleAmt30d, clarifying attribution semantics, but most parameter meaning is already in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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, which is a specific verb+resource. It distinguishes from sibling tools like openapi_v2_tiktok_products_search and openapi_v2_tiktok_videos_search by focusing on creators, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching creators with various filters and sorting, but does not explicitly state when to use this tool versus alternatives or provide exclusions. It mentions data freshness and region (US in v1), which gives some context, but lacks explicit guidance on 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_tiktok_products_searchAInspectTiktok 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.
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"
}| 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. |
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 data freshness ('latest daily snapshot'), regional scope ('region = US in v1'), pagination limits ('max 100 per page'), and metric coverage. It does not mention rate limits or required filter combinations, but it goes well beyond the schema in operational transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening paragraphs are front-loaded and useful, but the description becomes bloated with a long 'Responses' section containing an embedded schema and a verbose 'meta' field that discusses ADR-0003 credit deprecation timelines and TODOs. This irrelevant detail fails the 'every sentence earns its place' test.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 30-parameter tool with no annotations, the description covers key context: use cases, a concrete example, snapshot timing, pagination, available metrics, and related category discovery. However, it does not state whether at least one filter is required, and because there is no output schema, the product response fields are only partially described via the metric coverage list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 30 parameters, so the baseline is 3. The description adds a small amount of extra meaning through the categoryPath/categoryRankMax example and the metric coverage list, but it does not explain individual parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'Search TikTok Shop products by keyword, category, and multi-dimensional filters,' which states a specific verb ('Search') and resource ('TikTok Shop products') with clear filter scope. The TikTok Shop qualifier and mention of top-selling SPUs differentiates it from sibling tools like openapi_v2_products_search and openapi_v2_fashion_product_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'discover top-selling SPUs in a niche, narrow by category and price / shipping signals, or surface fast-growing products by 30-day sales growth.' It also includes a concrete example and points to a related tool ('/tiktok/categories for category tree discovery'), but it does not state when to prefer this over other product-search siblings or mention exclusions.
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_productAInspectTiktok 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.
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"
}| 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It discloses on-demand data collection and higher latency (2-5 seconds), and lists the specific current-state fields returned (price, rating, units sold, inventory, etc.). It also embeds response schemas and error codes, adding useful behavioral context beyond a simple GET, though it omits potential auth or rate-limit considerations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core narrative is front-loaded and concise, but the response section adds large OpenAPI schemas and boilerplate that is only loosely relevant to tool selection/invocation. The example response shows only the generic envelope (success/meta) rather than product-level data, and the meta schema includes detailed credit-decimal TODOs that are extraneous. This heavy tail reduces overall scanning efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives a complete picture: purpose, usage context, latency, marketplace constraint, and related tools. It lists the key product data fields in the narrative, even if the embedded output schema only covers the generic response envelope. The 422 validation schema and the explicit US-only note handle common edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% parameter coverage with descriptions for productId and marketplace. The description supplements this with a concrete example productId and explains it is the digits from the product page URL. For marketplace, it reinforces that only 'US' is available, matching the schema's const value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get realtime TikTok Shop product detail for a single product (SPU) ID', which is a specific verb+resource+scope statement. It also distinguishes this tool from sibling endpoints by naming '/tiktok/products/search' for daily-updated data across many products, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states 'Use this when you need the product's current state rather than daily-updated values' and points to the alternative search endpoint for daily-updated data. It also notes the current US-only marketplace availability, which is a critical constraint for choosing 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_tiktok_videos_searchAInspectTiktok 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.
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"
}| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses meaningful traits: data is from the latest daily collection within a fallback window, interaction rate is computed per video and filtering does not reduce query time, and each result includes the primary product's category id/path. It doesn't mention auth or rate limits, but for a search tool this is strong behavioral coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The text is front-loaded with the core search purpose, followed by filter capabilities and a behavioral note. The extensive response schemas add length but are justified since no dedicated output schema field exists. Overall it is well-structured and each section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 26 parameters, no annotations, and no output schema, the description compensates well: it covers data source, filter semantics, interaction rate calculation, related tools, and response formats. It lacks explicit error-handling beyond 422 and auth notes, but those are not essential for a search tool with this level of schema documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented with meaningful descriptions. The main description adds a high-level summary of filter types and the interaction rate formula, but it restates, rather than extends, what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search daily-updated TikTok videos by engagement, creator, and commerce signals', which clearly states a specific verb and resource. It distinguishes itself from sibling tools by listing related searches (/tiktok/creators/search and /tiktok/products/search), making its scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool—when searching TikTok videos with engagement, creator, and commerce filters. It names related tools but does not explicitly state exclusions (e.g., 'for creators, use /tiktok/creators/search instead'), so it stops short of full when/not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_voc_analysisAInspectVoc Analyze V2
Voice-of-Customer analysis by ASIN list or category: aggregated sentiment, ratings, and consumer intelligence.
Returns aggregate insights only — sentiment distribution, rating breakdown, pain points, buying factors, usage scenarios, and consumer profiles. No individual review text or reviewer identity is included. Example: pass asins=["B07FR2V8SH"] with period="6m" for a 6-month VoC profile. ASIN mode supports max 100 ASINs. Related: /products/search to find ASINs, /categories for category paths, /reviews/search for per-review data with AI tags.
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"
}| 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. Only 'US' is currently supported. | US |
| categoryPath | No | Category hierarchy from root. Example: ['Electronics', 'Computers']. Required when mode='category'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it returns only aggregate insights and excludes individual review text or reviewer identity, which is key behavioral context. It also notes the ASIN limit of 100. With no annotations provided, the description carries the transparency burden but addresses core privacy and scope adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening is concise and front-loaded, but the description becomes verbose by embedding full output schemas and error response examples. While structured with headings, the extensive schema blocks make it longer than necessary, especially since these might be redundant with an output schema field.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no separate output schema, the description compensates by including response schemas and error handling details. It covers purpose, usage, limits, and related tools. Minor gaps include lack of pagination explanation for request parameters and no mention of authentication or rate limits, but these are not critical for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although input schema has 100% coverage, the description adds value by including a usage example ('pass asins=[...] with period="6m"') and clarifies conditional requirements (e.g., asins required when mode='asin', categoryPath when mode='category'). It also specifies the max ASIN count, enhancing schema meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Voice-of-Customer analysis by ASIN list or category' and lists specific outputs like sentiment distribution, rating breakdown, pain points, buying factors, usage scenarios, and consumer profiles. It also distinguishes from siblings by mentioning 'Reviews/search for per-review data' and 'Products/search to find ASINs'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names alternative endpoints: 'Related: /products/search to find ASINs, /categories for category paths, /reviews/search for per-review data with AI tags.' Also provides a concrete usage example and states the ASIN mode max of 100, giving clear context for when 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_voc_watchlist_addAInspectAdd an ASIN to your review watchlist
Save an ASIN to your review watchlist — the shortlist of products you monitor for customer feedback.
Once an ASIN is on the list, analyze it any time with /voc/analysis (aggregated Voice-of-Customer insights) or /reviews/search (per-review data). Idempotent: adding an ASIN already on the list is a no-op and does not count against the cap. Up to 100 ASINs per account, shared across the Web Console and the API. Free of charge. Related: /voc/analysis, /reviews/search.
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[WatchlistMutationDTO]",
"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"
}| Name | Required | Description | Default |
|---|---|---|---|
| asin | Yes | Amazon Standard Identification Number — 10-character product id, e.g. 'B07FR2V8SH'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses idempotency ('adding an ASIN already on the list is a no-op'), capacity limits (100 ASINs), shared scope across Web Console and API, and cost (free). It stops short of detailing side effects or failure modes, but covers key behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary action, uses bullet points for key facts, and includes a clear 'Related' section. The additional response schema is verbose but embedded in structured format; the prose portion is efficient. Slight deduction for the lengthy output schema embedded in the description, though it's structured and not prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a simple single-parameter mutation tool with clear schema and no output schema, the description is complete. It explains the tool's purpose, related tools, limits, idempotency, and cost. The absence of an output schema in the tool definition is compensated by the example response in the description. It lacks explicit error scenarios beyond 422 validation, but is otherwise sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single 'asin' parameter, including format and example. The description adds context by explaining how the parameter is used (saving to watchlist, analyzing later) but doesn't need to add much beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Add an ASIN to your review watchlist' and explains what the watchlist is ('the shortlist of products you monitor for customer feedback'). It distinguishes this from siblings like openapi_v2_voc_watchlist_list and openapi_v2_voc_watchlist_remove by the action 'add' and the specific behavior described.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'analyze it any time with /voc/analysis ... or /reviews/search'. It also explains when adding is a no-op and doesn't count against the cap, plus the 100-ASIN limit and free-of-charge note. This gives clear context on when to use this tool and related alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_voc_watchlist_listAInspectList the ASINs in your review watchlist
List the ASINs on your review watchlist, newest first.
Use this to see which products you're monitoring, then drive Voice-of-Customer analysis over them with /voc/analysis. Shared with the Web Console. Free of charge. Related: /voc/analysis.
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[WatchlistListDTO]",
"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"
}| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavioral traits. It adds useful details like 'newest first' ordering, 'Shared with the Web Console,' and 'Free of charge.' However, it does not mention authentication requirements, rate limits, or explicitly confirm that the operation is read-only (though 'List' implies it). The response schema heavy with credit metadata adds context but does not address these gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core description is front-loaded and clear: the first sentence states the purpose, followed by the use case and related tool. However, the description bloats with a large embedded output schema and detailed credit metadata (e.g., ADR-0003, deprecated field timelines) that is not essential for selecting or invoking the tool. This reduces conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-parameter list endpoint, the description is quite complete: it explains what is listed, the ordering, the use case, related tools, and cost. The response schema in the description shows pagination fields, though it does not clearly define the data payload structure for ASINs. Still, the description suffices for an agent to select and call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is empty and schema coverage is 100%. According to the rubric, 0 parameters earns a baseline of 4. The description adds no parameter-specific details, which is appropriate because there is nothing to clarify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with specific verb and resource: 'List the ASINs in your review watchlist' and 'List the ASINs on your review watchlist, newest first.' This unambiguously distinguishes it from sibling tools like watchlist add/remove and analysis, all of which have different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: 'Use this to see which products you're monitoring.' It also points to the alternative next step, '/voc/analysis', for further analysis. However, it does not explicitly state when not to use it (e.g., for adding/removing watchlist items), though this is implied by the sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_voc_watchlist_removeAInspectRemove an ASIN from your review watchlist
Remove an ASIN from your review watchlist.
Drops the product from your monitored shortlist. Free of charge.
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[WatchlistMutationDTO]",
"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"
}| Name | Required | Description | Default |
|---|---|---|---|
| asin | Yes | Amazon Standard Identification Number — 10-character product id, e.g. 'B07FR2V8SH'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It discloses that the operation is free of charge and removes the product from the monitored shortlist, but it does not mention potential side effects (e.g., idempotency, reversibility) or requirements (e.g., the ASIN must already be on the watchlist). The response schemas at the end add some transparency but they are structured data rather than prose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening sentence is repeated verbatim twice, which is redundant. The response schemas are long but structured and informative. The overall description would be more concise with a single statement of purpose followed directly by response details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple one-parameter tool with a clear description and embedded response examples (200 and 422). The description plus schema provides enough context for an agent to use it correctly. Minor gaps, like what happens when removing a non-existent ASIN, are not addressed, but the richness of the provided response details makes it fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the only parameter 'asin' with its format, length constraints, and an example. The description itself adds no extra parameter details, so with 100% schema coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific language: 'Remove an ASIN from your review watchlist' and 'Drops the product from your monitored shortlist.' This clearly identifies the action (remove) and the resource (watchlist), and it distinguishes from sibling tools like add and list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: you use this when you want to remove an ASIN from the watchlist. However, it does not explicitly mention alternatives (e.g., openapi_v2_voc_watchlist_add) or when not to use it. 'Free of charge' is a minor usage note but not a full guideline.
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_statusAInspectPoll 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.
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"
}| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Pagination offset over completed pages. | |
| limit | No | Pagination size. | |
| job_id | Yes | Crawl job id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for disclosing behavior. It explains that data[] contains already-scraped pages, that skip/limit are for pagination, and importantly discloses the 404 behavior for unknown or cross-tenant job IDs, deliberately indistinguishable to prevent tenant data leakage. This is a significant behavioral trait beyond simple API mechanics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core description is concise and front-loaded with the purpose. The response schemas add length but are structured and informative, justifying their inclusion. However, the response section is quite verbose, especially the ADR-0003 details within meta, which may be excessive for quick understanding. Still, the main sentences earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is comprehensive for a polling tool: it covers purpose, pagination behavior, error semantics, and includes detailed response schemas embedded in the description. It addresses edge cases like tenant isolation and gives examples. Given the tool's simplicity (3 params, no output schema field), the description is more than sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has a 100% description coverage, so the baseline is 3. The description adds value by explaining that pagination is needed 'when data[] grows large,' and by providing context on the job_id's 404 behavior for security. This enhances the semantic understanding of the parameters beyond their schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Poll a crawl job' and immediately clarifies it polls the job's status. This clearly identifies the verb (poll) and the resource (crawl job status), distinguishing it from sibling tools like openapi_v2_webtools_crawl_submit. The mention that data[] contains already-scraped pages further clarifies the tool's role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: after a crawl job is submitted, to poll its status. It also gives pagination guidance for large data[] results. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.
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_submitAInspectSubmit 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.
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"
}| 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. |
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 several important behaviors: robots.txt is always honored, external-domain links are not followed, limit defaults to 100 with a cap of 10000, and the returned id is tenant-bound (polling with a different API key returns 404). This is rich, non-obvious behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the essential purpose and key constraints, followed by structured response schemas. It is somewhat lengthy due to the embedded output schemas, but each section serves a reference purpose. There is minor redundancy with the limit information already present in the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex async crawl tool with 9 parameters, the description covers submission, polling, constraints (robots.txt, external links), pagination limits, tenant binding, and response handling. It explains edge cases and provides example responses, making it comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage; every parameter already includes an explanatory description. The main description repeats the limit default/cap but adds little beyond the schema's own parameter documentation, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Submit a crawl job' and 'Submit an async recursive crawl job,' clearly identifying the verb and resource. It distinguishes from sibling tools by explaining the async nature, the returned opaque id, and the polling endpoint (GET /webtools/crawl/{id}).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it is for submitting an async crawl, and explicitly directs the user to poll GET /webtools/crawl/{id} for status. However, it does not explicitly name sibling tools like crawl_status as alternatives, so the guidance is implied rather than fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_webtools_mapAInspectDiscover 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.
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"
}| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly. It explains sitemap modes (include/only/skip), subdomain handling, query parameter collapsing, and limit semantics. It also includes specific behavioral details like 'relevance-ordered list' and default recommendations, giving agents a clear model of expected behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core functional description is well-structured and front-loaded, but the description field is bloated by a full response schema and example for both 200 and 422 statuses, plus extensive metadata credit field details. This goes well beyond what's needed and detracts from conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all 8 parameters, key edge cases (subdomains, query params, sitemap modes), and includes response examples. It lacks explicit guidance on when to use this tool over sibling tools, but otherwise provides a complete operational picture for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since the input schema already provides 100% parameter coverage, the baseline is 3. The description adds value beyond the schema by explaining why certain defaults are recommended (e.g., 'recommended for discovery — avoids near-duplicate ?utm=/?page= URLs') and by summarizing parameter interrelationships like 'Use search to rank links by keyword relevance.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Discover URLs from a website via sitemap and on-page link discovery.' This is a specific verb+resource combination that immediately distinguishes it from sibling tools like scrape, search, or crawl_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly compare this tool to alternatives or provide when-to-use vs. when-not-to-use guidance. Usage is implied by the tool's obvious mapping purpose, but there are no exclusions or alternative recommendations, so it earns a mid-range score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_webtools_scrapeAInspectScrape 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/451/503, or one the
upstream flags as blocked) returns success:false with an error.code
of ACCESS_DENIED plus a customer-facing error.message directing
the caller to support — these domains stay refused under retry, so the
response is actionable rather than transient. A 429 returns RATE_LIMITED
with a generic retry message; UNREACHABLE / TIMEOUT /
CONTENT_UNAVAILABLE cover host/network/extraction failures. The
error.details payload is reserved for future structured attribution and
is currently always null; callers should branch on error.code and
surface error.message to end users. Refused requests are not billed
and never carry a content body.
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"
}| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to scrape | |
| formats | No | Output formats. Order in the response matches the input order. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral transparency burden. It thoroughly covers response meta, the need to check `meta.statusCode`, specific error codes (ACCESS_DENIED, RATE_LIMITED, UNREACHABLE, etc.), retry implications, the `error.details` null behavior, and billing consequences—far beyond what any annotation would provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core explanation is front-loaded and well structured, with a clear distinction between normal response handling and error cases. It is longer than necessary because it includes full response schemas and examples, but the prose is dense and avoids redundancy, so the length is largely justified by the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema being formally declared, the description provides an in-depth explanation of the response envelope, meta fields, error taxonomy, and retry behavior. Together with the 100% parameter schema coverage, this gives an LLM agent everything needed to invoke the tool correctly and interpret its results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes both `url` and `formats` fully (100% coverage), so the baseline is 3. The description adds meaningful context about what each format returns, particularly that `json` triggers a structured page summary with a built-in schema, which is not fully evident from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Scrape a single URL and return clean content,' which clearly states the action and resource. By specifying 'single URL,' it distinguishes itself from sibling crawl/submit tools, and the rest of the description reinforces this singular scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear guidance on when to use this tool (single-URL scraping) and how to use formats, especially explaining that `json` uses a built-in extraction schema. It does not explicitly mention alternatives like crawl for multi-page or interactive scraping, but the 'single URL' framing implies the distinction.
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_interactiveAInspectScrape 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.
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"
}| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to scrape | |
| actions | Yes | Sequential browser actions to perform before scraping. | |
| formats | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses meaningful behavioral details: the 60-second cumulative wait cap, HTTP 422 rejection for over-cap, the seven supported action types, and intentional exclusions. It stops short of explaining session/cookie behavior or the exact shape of the scraped data payload, so it loses a point.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening paragraph is crisp and useful, but the description becomes bloated with an entire OpenAPI response schema, ADR-0003 credit field explanations, TODOs, and metadata details that are irrelevant to selecting or invoking the tool. This over-specification detracts from readability and focus.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the bloat, the description does cover the core action system, constraints, and error behavior, which is essential for correct invocation. However, it lacks explicit guidance on when to prefer this over the simple scrape sibling, and the response schema is incomplete for the actual scraped content, leaving some ambiguity about what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides solid descriptions for url and actions, and item-level descriptions for formats. The tool description adds only indirect value by mentioning the markdown/json/raw_html response surface, but does not explain parameter semantics beyond the schema. When schema coverage is moderate (67%), a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+scope: "Scrape a page after running browser actions." It then enumerates the seven supported action types, clearly distinguishing this tool from the sibling openapi_v2_webtools_scrape by emphasizing the interactive/browser-action aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for pages requiring interaction before scraping, but it never explicitly contrasts with alternatives or states when to choose this tool over openapi_v2_webtools_scrape. The exclusions for screenshot/pdf are about output surface, not about when to use alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v2_webtools_searchAInspectSearch the web
Search the web. Two modes governed by scrapeOptions.
Omit scrapeOptions → SERP-only: returns the search engine's raw
snippets (url + meta with title / description /
source / publishedAt / imageUrl*). No per-page fetch, fast
and cheap.
Pass scrapeOptions: {} → deep-scrape every result, return
page-faithful Markdown under markdown.
Pass scrapeOptions: {"format": "json"} → deep-scrape every
result, return the structured page summary under json (same shape as
/webtools/scrape's json field).
In deep-scrape mode, results where the chosen format produced no content
are dropped from the response, so the response may hold fewer than
limit results. meta.statusCode carries the fetched page's HTTP
status when deep-scraped.
query is compatible with common Google search-operator syntax:
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 (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.
Billing scales with the number of results returned, with a minimum of 1 credit per call (an empty result set still bills the minimum).
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"
}| Name | Required | Description | Default |
|---|---|---|---|
| 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. | |
| scrapeOptions | No | Deep-scrape options. Omit (or pass ``null``) to return **SERP results only** (fast, no per-page fetch — useful when you only need the result list). Pass ``{}`` to deep-scrape every result with default ``format=markdown``. Pass ``{"format": "json"}`` to deep-scrape with structured extraction. | |
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description carries the full burden and does so thoroughly: it discloses dropped results in deep-scrape mode when content is absent, meta.statusCode behavior, minimum 1-credit billing even for empty results, and folding of domain filters into site: operators. These are meaningful behavioral traits beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core narrative is front-loaded and uses clear bullet points, making it scannable. However, the embedded response schema — including the verbose ADR-0003 credit-field explanation and TODOs — lengthens the overall definition beyond what is needed for selection and invocation, even though it is relevant context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, nested objects, no annotations, and no formal output schema on the MCP side, the description fully covers all parameters, return shapes, error handling, billing, and mode-specific behavior. An agent can correctly select and invoke this tool without needing additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds substantial semantic value: it explains how scrapeOptions presence triggers deep-scrape, what each format returns, how query operators interoperate with includeDomains/excludeDomains, and how dropped results interact with limit. This far exceeds the schema's own parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search the web' — a specific verb and resource — and immediately distinguishes itself from sibling tools by detailing two modes governed by scrapeOptions. It clearly scopes the tool to web search (SERP or deep-scrape) as opposed to webtools_map, webtools_scrape, or video assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance for SERP-only vs deep-scrape modes, when to prefer includeDomains/excludeDomains over manual site: operators, and how to configure sources, tbs, and limit. It also hints at alternatives (e.g., rawHtml is not supported on search, referencing /webtools/scrape for the json shape), though it never names a specific sibling as a substitute for a given scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openapi_v3_realtime_productAInspectRealtime 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.
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"
}| 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 code. Only 'US' is currently supported. | US |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It discloses on-demand data collection, higher latency, and the specific fields returned (price, rating, BSR, etc.). It implies a read-only action via 'Get' but does not explicitly state no side effects. Still, it covers key behavioral traits beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The first paragraph is concise and front-loaded, stating purpose, usage, latency, and alternatives within five sentences. The remainder is a structured response schema section, which is not verbose prose but necessary given no separate output schema. The information is well-organized, though the overall length is high due to schema blocks.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, when to use, alternatives, latency, example usage, and the returned fields. It includes full response schemas (200 and 422) that detail the meta structure, pagination, and error format, providing complete context for an agent to invoke the tool and interpret responses. No significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters, with detailed descriptions in the input schema (e.g., ASIN format, marketplace constraint). The tool description only repeats an example ASIN and does not add meaning beyond the schema. Baseline of 3 applies because the schema fully documents the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get realtime product data') and the specific resource (a given ASIN). It distinguishes from siblings by naming related endpoints (/products/search, /products/history) and explicitly contrasting realtime vs. daily-updated values. The verb+resource+scope is precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use this when you need the product's current state rather than daily-updated values' and provides alternatives with related endpoints. It also notes higher latency (2-5 seconds), giving the agent a decision factor. This is exemplary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
poll_video_taskAInspectPoll 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.
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"
}| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses billing side effects: first successful poll charges the wallet, terminal polls are cached and free. It also explains 404 behavior for nonexistent or foreign task IDs, no per-call cost in response, and token usage details. This comprehensively covers critical behavioral traits beyond a basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with headings and front-loaded usage details, making key information easy to find. However, it includes extensive OpenAPI response schemas and examples that add notable length, though they are relevant and organized. Every few sentences, but some redundancy exists in the raw schema dumps.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all necessary aspects for polling: statuses (including terminal states), result fields (output/error), token usage, billing behavior, access restrictions, and error responses. It also provides both 200 and 422 response schemas. Given the tool has no output schema and no annotations, the description is exceptionally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only defines task_id as a required string with no description. The description adds crucial meaning: it is the taskId from the submit call and returns 404 if invalid or belongs to another account. This fully compensates for the 0% schema coverage and gives the parameter clear semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it polls a video generation task to retrieve status and result. It distinguishes itself from sibling tools like submit_video_generation by explicitly referencing the taskId from the submit endpoint and focusing on status retrieval. The verb 'poll' and resource 'video generation task' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage context: call with taskId, poll every 5-10 seconds until terminal status, and notes CONTRACT-tier key restriction. It also offers an alternative for cost checking (account/balance endpoint). However, it does not explicitly state when not to use it versus alternatives like get_video_asset, so it lacks a clear exclusion statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
submit_video_generationAInspectSubmit 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.
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"
}| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for disclosing behavior. It does so thoroughly: async execution, immediate taskId return, polling endpoint, terminal status requirements, billing on first successful poll, wallet balance check, 402 error with X-Usd-Required-* headers, and no task creation on insufficient balance. This goes well beyond a simple 'submit' label.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized: a concise high-level summary, then a structured parameter list, then response details. It duplicates some schema information, but the added context (e.g., billing behavior, polling instructions) justifies the length. The key async behavior is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, async workflow, special billing rules), the description is highly complete. It covers all major aspects: request shape, parameter constraints, response fields (taskId, status), error scenarios (402, 422), polling endpoint, and security/availability requirements. It also includes an example response and output schema, leaving little ambiguity for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, so baseline is 3. The description adds meaningful operational semantics beyond the schema: it explains the OpenAI-style content array structure with role values, per-kind item caps (9/3/3), public URL requirement, forwarding of unknown fields to the provider, and the billing-tier meaning of resolution. These details enhance the agent's ability to construct valid requests.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb phrase 'Submit a video generation task' and specifies the resource (video generation via Seedance). It clearly distinguishes the tool from siblings like poll_video_task by emphasizing the asynchronous submission behavior that returns a taskId for later polling. The scope (text-to-video, image-to-video, video-to-video) is also explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 the tool: for submitting any Seedance video generation job, with details on the async flow and polling. It does not explicitly name alternatives (e.g., poll_video_task) or state when NOT to use it, but it implies the follow-up polling step and includes constraints like CONTRACT-tier keys and wallet balance checks.
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.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
