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.
Scored across 51 tools
Most tools are clearly separated by domain and resource, and the descriptions do a good job of distinguishing similar endpoints. However, the set includes a deprecated realtime product tool that duplicates the v3 version, and image_embedding vs fashion_image_embedding are easy to confuse despite their descriptions.
The tool names are internally inconsistent: a few use clean verb_noun names like create_video_asset and poll_video_task, while the vast majority use an opaque openapi_v2_ prefix with actions placed inconsistently (e.g. products_search vs voc_watchlist_add vs webtools_crawl_submit). The openapi_v3_realtime_product outlier further breaks any coherent pattern.
With 51 tools, this set is far beyond the threshold where an agent can reliably select among them. While the tools span several legitimate domains, the server is effectively an entire API gateway surface exposed as one MCP server, which is an extreme count mismatch for a coherent tool set.
Each major domain is fairly well covered: product search/history/traffic/keywords, reviews and VoC, TikTok discovery, web scraping/search/crawl, video generation, and account balance. Minor gaps exist, such as no cancel for video tasks, no delete for video assets, and a deprecated legacy product endpoint still being exposed, but core workflows have no dead ends.
Register 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 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 — plus a usd block with the granted/topped_up wallet split when the account owns a USD wallet (self-serve top-up).
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, CreditAccountBalanceWithUsd, 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 provided, the description carries the full burden. It discloses that responses vary by customer tier, includes both legacy and exact credit fields (ADR-0003), and notes the polling uniqueness. It does not mention authentication or rate limits, but as a read operation the risk is low. The description adds substantial behavioral context beyond the tool name.
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 lengthy, including extensive output schema blocks, example JSON, and ADR references with TODO comments. While the lead sentence is concise, the body is dense and could overwhelm an agent. Some details (e.g., TODO timestamps) are not essential for invocation, but the length is partly justified by the lack of a formal output 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?
The description covers the success and validation responses, tier-specific behaviors, the polling uniqueness for CONTRACT-tier, and the parallel credit fields strategy. It gives example output and details on error structure. For a no-param tool with no separate output schema, this is sufficient for an agent to call it and interpret results 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 baseline of 4 applies. The schema is empty and requires no explanation; the description adds no parameter info because none is needed.
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[s] account billing balance' and then explains the tier-specific views (usd vs credits), making the purpose unambiguous. It distinguishes itself from siblings by focusing on billing balance, though it doesn't name alternatives explicitly.
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 a concrete 'when to use' scenario: for CONTRACT-tier customers to observe USD balance, noting this endpoint is the only way. It doesn't explicitly mention alternatives or when not to use, but the billing context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a video-generation asset by id
Fetch a single asset's metadata and live status.
Returns 404 if the asset doesn't exist or belongs to another customer (we deliberately do not distinguish to avoid leaking asset-id existence across tenant boundaries).
Available to CONTRACT-tier API keys only.
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 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.
Categories V2
Query Amazon category hierarchy by ID, path, parent, or keyword.
Use this to discover category structure for filtering in other endpoints. Example: pass categoryKeyword="yoga" to find matching categories, or parentCategoryPath=["Sports & Outdoors"] to list child categories.
Query modes (mutually exclusive):
No parameters: Returns all root categories
categoryId: Get specific category by ID
categoryPath: Get specific category by path
parentCategoryId: Get children of parent category by ID
parentCategoryPath: Get children of parent category by path
categoryKeyword: Search categories by keyword
Related: /products/search and /markets/search accept categoryPath for filtering.
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.
Competitor Lookup V2
Search competitor products by keyword, brand, ASIN, or category with filters.
Use this to identify competing products around a specific listing or brand. Example: pass asin="B07FR2V8SH" to find all products competing in the same keywords and category. Data is based on the latest daily snapshot; results are paginated (max 100 per page). Related: /products/search for broader keyword discovery.
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.
Rerank documents for ecommerce search queries
Rerank a list of product documents by relevance to ecommerce search queries.
Use this to improve product search result ordering. Pass one or more search queries and a shared list of product documents (titles, descriptions, or concatenated attributes). The model scores each document against each query and returns them sorted by relevance. Powered by a fine-tuned Qwen3-Reranker model optimized for ecommerce product matching.
Credits: 1 credit per query in the batch. A request with 3 queries costs 3 credits.
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.
Generate fashion image embeddings (768-dim vectors for similarity search)
Generate fashion-specific image embeddings using fine-tuned SigLIP2.
Encode product images into 768-dim vectors aligned with the text embedding space. Use cases: visual similarity search, image-to-text matching, duplicate detection, catalog indexing. Accepts HTTPS URLs or base64-encoded images. Vectors are L2-normalized by default. Credits: 1 credit per request.
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.
Search fashion products by image similarity
Search fashion products by visual similarity to a query image.
Upload an image URL to find visually similar fashion products across the catalog. Optionally specify a bounding box to focus on a specific item in the image, and add a text description for better matching.
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.
Search fashion products by text query
Search fashion products by natural-language text query.
Searches across 200M+ fashion products from major retailers. Supports brand filtering, price range, and retailer domain allowlists/denylists. Results include product title, brand, price, image, and retailer link.
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.
Compute text-image similarity scores for fashion products
Compute cosine similarity between text queries and product images.
Encodes texts and images into the same 768-dim space, returns a score matrix. similarityScores[i][j] = relevance of textQueries[i] to imageUrls[j]. Higher = better match. Equivalent to text-embedding + image-embedding + dot product in one call. Credits: 1 credit per request.
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.
Generate fashion text embeddings (768-dim vectors for similarity search)
Generate fashion-specific text embeddings using fine-tuned SigLIP2.
Encode fashion text into 768-dim vectors aligned with the image embedding space. Use cases: text-to-image search, semantic product matching, catalog indexing. Vectors are L2-normalized by default (dot product = cosine similarity). Credits: 1 credit per request.
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.
Detect fashion items in images
Detect fashion items in an image and return their bounding boxes.
Analyzes an image to locate fashion items such as bags, shoes, clothing, watches, glasses, and jewelry. Returns bounding box coordinates, category classification, and confidence scores for each detected item. Use the classes parameter to filter for specific fashion categories. Credits: 1 credit per request.
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.
Generate fashion item embeddings from images
Generate feature embeddings for fashion items detected in an image.
Automatically detects fashion items (bags, shoes, clothing, watches, etc.) in the image and generates feature embedding vectors for each detected item. Embeddings can be used for visual similarity search, product recommendations, and image-based product matching. Optionally include fashion category tags and text-image relevance scores. Credits: 1 credit per request.
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 carry the burden. It discloses that the tool automatically detects fashion items (not requiring pre-defined bounding boxes), mentions credit cost (1 credit per request), and notes optional parameters affecting response content. However, it does not disclose any rate limits, authentication requirements, or what happens when no items are detected. The response schema is provided separately but the description does not summarize return structure beyond the example.
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 sized but front-loaded with a clear purpose sentence. It includes useful information about credits and optional features Human. However, a significant portion is dedicated to a response example and a verbose description of the meta.credits fields (ADR-0003, TODO items) that is unrelated to the tool's core functionality and should be simplified or moved. The structure would benefit from trimming irrelevant 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?
Given the complexity (7 parameters, many optional), the description covers the core functionality but misses some practical details: no mention of image size limits, supported formats, or behavior when no fashion items are detected. With no annotations and no output schema in the structured input (though included in description), the description should more explicitly state common pitfalls (e.g., image URL accessibility) and error scenarios. The credit cost is mentioned but not the exact behavior of partial 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?
Schema description coverage is 100%, so the schema already documents all 7 parameters clearly (text, topK, image, timeout, withTag, boundingBoxes, withEmbedding). The description adds context about the purpose of embeddings and credits, but does not add additional meaning beyond the schema's descriptions. Since the schema is comprehensive, a 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 states the tool's purpose: generating feature embeddings for fashion items detected in an image. It lists example item types (bags, shoes, clothing, watches) and mentions optional tags and text-image relevance scores. This distinguishes it from siblings like openapi_v2_fashion_image_search (which likely focuses on search) and openapi_v2_image_detection (which likely focuses on detection only).
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 context for computer-vision-based embedding generation and mentions optional parameters (withTag, text for relevance scoring). It does not explicitly state when to prefer this tool over alternatives like openapi_v2_fashion_text_embedding or openapi_v2_image_detection. No exclusion criteria or explicit alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get keyword detail
Function
Return a single-week raw statistical snapshot for one or more keywords: search demand, competition and advertising metrics from the latest available week on or before date. The observed period is reported in context.dataWindow; resolvedDate is the actual snapshot date. Both single and batch requests return data.context + data.items[]. This is snapshot data, not a scored market assessment.
Use cases
Use detail to compare current raw metrics when screening candidate keywords. Use market-profile for market scores, levels and interpretations; use trend for raw weekly history.
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 (YYYY-MM-DD). Returns the latest snapshot on or before this date; actual date is `resolvedDate`. | |
| keyword | No | Single keyword; mutually exclusive with `keywords`. Surrounding whitespace is trimmed; letter case is accepted. | |
| keywords | No | Keyword list, up to 20; mutually exclusive with `keyword`. Must equal `LOWER(TRIM(value))`; uppercase letters and surrounding whitespace are rejected. Duplicate keywords are rejected. | |
| granularity | No | Data period granularity. Only `week` is currently 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?
With no annotations, the description carries the full burden and meets it: it discloses snapshot semantics, date resolution behavior via resolvedDate/dataWindow, the fact that both single and batch requests return data.context + data.items[], and that results are raw rather than scored. It also provides response schemas for 200 and 422.
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 with numbered Function and Use cases sections, and the core behavior is front-loaded. The embedded response schemas are verbose and include irrelevant ADR/credit details, which prevents a perfect score, but the overall organization is clear and efficient.
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 five-parameter endpoint with no annotations, the description, input schema, and embedded response schemas together cover invocation semantics, parameter constraints, response shape, and error handling. Nothing an agent needs to correctly select and call the tool 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 has 100% description coverage and already documents date format, mutual exclusivity, constraints, defaults, and whitespace/case rules. The prose description adds contextual value about output metrics but does not materially enhance parameter semantics beyond what the schema provides, 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 a specific verb and resource and immediately defines the tool as a single-week raw statistical snapshot for keywords, including the exact metric categories and date behavior. It also distinguishes itself from sibling tools by noting it is snapshot data, not a scored market assessment.
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 detail ('compare current raw metrics when screening candidate keywords') and when to use alternatives ('market-profile for market scores, levels and interpretations; trend for raw weekly history'). This is direct when/when-not guidance rather than leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get keyword expansions
Function
Return expanded keywords related to the seed keyword with search volume, rank, and relevance metrics. Supports phrase and fuzzy expansion.
Use cases
Build candidate keyword lists for further research, listing content or advertising evaluation. Use detail or market-profile to assess the returned candidates.
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, starting at 1. | |
| query | Yes | Seed keyword. | |
| sortBy | No | Sort field: relevanceScore=expansion relevance; estimateSearchCount=estimated searches; abaRank=numeric ABA rank; keyword=lexical order. | relevanceScore |
| pageSize | No | Items per page; 1 to 100. | |
| queryType | No | Keyword expansion match mode. | phrase |
| sortOrder | No | Sort direction. | desc |
| granularity | No | Data period granularity. Only `week` is currently 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?
With no annotations, the description must carry the behavioral disclosure. It states the operation returns data (implies read-only) and includes the full response schema with pagination and credit fields. It does not explicitly mention side effects, auth requirements, or limitations (e.g., only US marketplace, week granularity – though those appear in the input schema). The response schema provides useful transparency, but the description omits deeper behavior like sorting defaults or rate limits. Adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core description is concise and structured with '1. Function' and '2. Use cases', front-loading the purpose. However, the description string includes very long response schemas (200 and 422) that, while informative, bloat the overall description. The prose is efficient, but the inclusion of detailed schemas makes the whole description lengthy. A more balanced approach would move schemas to a separate output schema field, but given the current format, it is acceptable.
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, use cases, and directs to subsequent tools. The input schema documents all parameters and constraints (e.g., only week granularity, US marketplace). The response schema explains the return format, including pagination and credit metadata. It lacks explicit alternatives comparison (e.g., vs. keyword_search_results) but the workflow guidance is clear. For a keyword expansion tool, this is nearly 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?
All 8 parameters have descriptions in the input schema, so the baseline is 3. The description adds no new parameter-level semantics; it mentions 'search volume, rank, and relevance metrics' which map to sortBy enum values, and 'phrase/fuzzy' which is already in queryType. No additional context beyond the schema, 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 starts with 'Get keyword expansions' and immediately clarifies the resource: 'Return expanded keywords related to the seed keyword with search volume, rank, and relevance metrics.' It distinguishes from siblings by naming the expansion modes ('phrase' and 'fuzzy') and the use case (building candidate keyword lists), which separates it from detail, trend, 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?
Provides an explicit use case: 'Build candidate keyword lists for further research, listing content or advertising evaluation.' It also directs to alternative tools for the next step: 'Use detail or market-profile to assess the returned candidates.' It does not explicitly say when not to use this tool, but the workflow guidance is clear and sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get keyword market profile
Function
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.
Use cases
Assess market entry conditions and compare demand, concentration, brand structure and organic benchmarks across candidate keywords. Use detail for the underlying snapshot metrics.
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 (YYYY-MM-DD). Returns the latest profile on or before this date; actual date is `resolvedDate`. | |
| keyword | No | Single keyword; mutually exclusive with `keywords`. Surrounding whitespace is trimmed; letter case is accepted. | |
| keywords | No | Keyword list, up to 20; mutually exclusive with `keyword`. Must equal `LOWER(TRIM(value))`; uppercase letters and surrounding whitespace are rejected. Duplicate keywords are rejected. | |
| granularity | No | Data period granularity. Only `week` is currently 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?
With no annotations provided, the description carries the behavioral burden. It adds non-obvious useful details: results come back in request keyword order, single-keyword requests also return data.context + data.items, and batch requests are billed by the number of keywords with status=ok, with the charge surfaced in meta.creditsConsumed. It stops short of describing failure modes, rate limits, or authentication expectations, so 4 is appropriate.
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 Function and Use cases sections are short and front-loaded, but the description then includes long response examples, an embedded output schema, and ADR/timeline details about deprecated credit fields. Most of that inline schema boilerplate is irrelevant to correct tool selection or invocation, making the overall description much larger than needed.
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's function, input semantics, and billing behavior are well covered, but the actual returned data shape is only vaguely described — 'data.context' and 'data.items' are mentioned without explaining the structure of the profile items. It is adequate for selecting the tool, but not fully complete for understanding what the response contains when calling it.
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 input schema already documents date behavior, keyword/keywords mutual exclusivity, whitespace and uppercase constraints, max length, and const values. The description adds only broad context such as 'one or more keywords' and 'snapshot date', not meaningful new parameter semantics beyond the schema. Baseline 3 is therefore 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 states a specific verb and resource — getting the keyword market profile — and enumerates the specific metrics included, which makes the tool's purpose unambiguous. It does not explicitly compare against close siblings like keyword_detail or keyword_trend, so it earns strong clarity but not full sibling 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?
The 'Use cases' section explains when to use the tool: assessing market entry conditions and comparing candidate keywords. It also points to 'detail' for underlying snapshot metrics, which acts as an alternative, though it doesn't explicitly describe when not to use this tool or name the exact sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get keyword search results
Function
Return factual product listings and absolute ranking positions for a keyword in the weekly period, with optional placement filtering. SERP aggregates and keyword market metrics are intentionally excluded and provided by dedicated metric endpoints.
Use cases
Inspect which products, brands and placements appear for a keyword, and compare their ranking positions. Use market-profile for market-level assessments.
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 (YYYY-MM-DD). Returns the latest snapshot on or before this date; actual date is `resolvedDate`. | |
| page | No | Page number, starting at 1. | |
| sortBy | No | Sort field: absolutePosition=SERP position; estimateImpressionPoint=estimated impressions; latestObservedAt=latest observation; price, rating, ratingCount, and recentSales use their named product metrics; asin and title use lexical order. | absolutePosition |
| keyword | Yes | Keyword to search. | |
| pageSize | No | Items per page; 1 to 100. | |
| sortOrder | No | Sort direction. The default `absolutePosition asc` returns the lowest rank numbers first. | asc |
| granularity | No | Data period granularity. Only `week` is currently supported. | 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?
No annotations are provided, so the description itself carries the behavioral disclosure burden. It says the tool returns factual product data and positions rather than market metrics, that the period is weekly, and that results can be placement-filtered. It also documents success, validation-error, and metadata behavior. Auth or rate-limit details are not covered, but the practical behavior for an agent is adequately transparent.
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 and front-loaded with 'Function' and 'Use cases,' which is helpful. However, it is padded with large response schemas, ADR credit-migration notes, and TODO details that an agent needs less for tool selection and invocation. It is readable, but 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 9-parameter read-style query tool, this is largely complete: the description explains what type of data is returned, what is excluded, when to use it versus market-profile, and the response/error envelope. Item-level response fields are not fully expanded, but the sortBy enum implies the product fields, so an agent can safely invoke the 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 already documents all params with 100% description coverage, including formats, defaults, enum meanings, and constraints. The description contributes only high-level context like 'weekly period' and 'optional placement filtering.' Since the schema does the heavy lifting, a 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 a specific verb and resource: 'Return factual product listings and absolute ranking positions for a keyword in the weekly period,' and adds the optional placement-filtering behavior. It also distinguishes itself from sibling endpoints by stating that SERP aggregates and keyword market metrics are intentionally excluded and provided by dedicated metric 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 'Use cases' section clearly tells an agent when to use this tool: to inspect which products, brands, and placements appear for a keyword and compare ranking positions. It also points to 'market-profile' for market-level assessments, giving an explicit alternative. It does not enumerate every sibling exclusion, so it stops 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.
Get keyword trend
Function
Return raw weekly time-series data for one or more keywords between dateFrom and dateTo, not precomputed trend conclusions. Both single and batch requests return data.context + data.items[].series[]. The date range cannot exceed 93 days; split longer history into multiple requests.
Use cases
Use trend to plot weekly search demand and ranking history or inspect when changes occurred. Use trend-profile for precomputed direction, volatility and supporting evidence over fixed windows selected by date + windowPeriods.
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 (YYYY-MM-DD); on or after `dateFrom`, with a maximum 93-day range. Actual range is `resolvedDateFrom` through `resolvedDateTo`. | |
| keyword | No | Single keyword to look up; mutually exclusive with `keywords`. Surrounding whitespace is trimmed; letter case is accepted. | |
| dateFrom | Yes | Trend start date (YYYY-MM-DD). | |
| keywords | No | Keywords to look up in batch, up to 20; mutually exclusive with `keyword`. Must equal `LOWER(TRIM(value))`; uppercase letters and surrounding whitespace are rejected. Duplicate keywords are rejected. | |
| granularity | No | Data period granularity. Only `week` is currently 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?
With no annotations provided, the description must carry the burden of behavior disclosure. It does mention the data return format (data.context + data.items[].series[]), the 93-day range limit, and that batch and single requests return the same structure. However, it does not explicitly state whether the operation is read-only (destructive hint absent), authentication requirements, or any rate limits. Given the tool is likely a read operation, some behavioral context is missing but the description is not misleading.
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 numbered sections ('1. Function', '2. Use cases') that front-load the core purpose and key constraint. It is concise, with no redundant filler, and the sibling comparison is included in the use cases. The inclusion of full response schemas in the description is necessary for completeness but is external to the description text itself. Minor redundancy exists with the schema (e.g., 93-day limit repeated), but overall it is efficient.
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 input schema is detailed and complete (100% coverage, clear constraints), and the output schema is provided in the description, the description covers what the tool does, when to use it, the data shape, and the key limitation (93-day range). It lacks explicit mention of pagination (though output schema includes page/pageSize), but this is covered by the output schema. The description is complete enough for an agent to call the tool correctly without additional 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 schema thoroughly documents each parameter: dateFrom/dateTo formats and constraints, keyword vs keywords mutual exclusivity, max items, case sensitivity, and granularity/marketplace consts. The description adds minimal value beyond mentioning the 93-day limit (already in schema) and the data return shape. Baseline 3 is appropriate because the schema is doing 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 clearly states the tool returns raw weekly time-series data for keywords over a date range, with 'not precomputed trend conclusions' explicitly distinguishing it from trend-profile. It explicitly names the sibling tool trend-profile for precomputed conclusions, making it easy for an agent to choose the correct tool.
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 when to use this tool (plotting weekly search demand/ranking history, inspecting changes) and when to use trend-profile instead (precomputed direction/volatility over fixed windows). It does not explicitly mention exclusions for other siblings like keyword_detail or keyword_search_results, but the use-case guidance is clear and actionable for the most relevant alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get keyword trend profile
Function
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. Read trend for search-demand and ABA-rank direction, and trendEvidence for supporting metrics. These are observed conclusions, not forecasts or causal explanations.
Use cases
Summarize observed search-demand and ABA-rank direction over a supported window. Use trend to inspect the weekly data behind a conclusion.
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 (YYYY-MM-DD). Returns the latest profile on or before this date; actual date is `resolvedDate`. | |
| keyword | No | Single keyword; mutually exclusive with `keywords`. Surrounding whitespace is trimmed; letter case is accepted. | |
| keywords | No | Keyword list, up to 20; mutually exclusive with `keyword`. Must equal `LOWER(TRIM(value))`; uppercase letters and surrounding whitespace are rejected. Duplicate keywords are rejected. | |
| granularity | No | Data period granularity. Only `week` is currently supported. | 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 and delivers substantial behavioral disclosure: the data is precomputed (not live), output preserves keyword/window order, billing occurs once per keyword with at least one window profile, and results are observed conclusions, not forecasts or causal explanations. These traits go well beyond anything the schema states.
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 tight and front-loaded: Function, then Use cases, with the loaded facts (precomputed, window sizes, order preservation, billing, non-forecast) in the first short paragraph. Minor redundancy — the heading repeats the phrase 'Get keyword trend profile' — but no filler or irrelevant detail.
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 (6 params, a oneOf keyword/keywords gate, no output schema, no annotations), and the description compensates well by teaching how to read the response ('Read trend for search-demand and ABA-rank direction, and trendEvidence for supporting metrics'). It could have given a data-shape example, but the field-level guidance covers the essential interpretation need.
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, and the schema documents each parameter thoroughly (date lookback, mutual exclusivity, LOWER(TRIM(value)) constraints, window enums). The description adds meaning beyond the schema: ordering of results preserves keyword/requested-window order, and the billing-per-keyword semantic tying windows to a single charge, which are not visible 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?
States a specific verb and resource: 'Return precomputed trend profiles for one or more keywords over fixed 4, 8, 12, or 26-period windows.' The 'precomputed profile' framing differentiates it from the raw sibling openapi_v2_keyword_trend, and the 'observed conclusions, not forecasts' clause scopes its semantics. An agent can tell this from sibling trend tools without opening either schema.
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?
Gives explicit use-case context: 'Summarize observed search-demand and ABA-rank direction over a supported window.' It names the alternative directly — 'Use trend to inspect the weekly data behind a conclusion' — routing the agent to the sibling raw-trend tool when detail is needed. This is explicit when-to-use and when-to-prefer-alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Markets Search V2
Search market data by category with aggregated demand, competition, and pricing metrics.
Use this to evaluate market size and competition before entering a niche. Example: search "Pet Supplies" with sampleAvgMonthlySalesMin >= 200 to find categories with proven demand. Data is based on top-100 product samples per category from the latest daily snapshot; results paginated (max 100 per page). Related: /products/search for product-level data in a category.
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.
Product History V2
Get historical time-series data for a single ASIN over a date range.
Returns columnar arrays: high-frequency metrics (price, BSR, sales, rating, sellerCount) as daily arrays aligned with timestamps, and low-frequency fields (title, imageUrl, badges, inventoryStatus) as changelog entries that only record changes. Max date range: 730 days. Related: /products/search to discover ASINs first.
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.
Products 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.
Products Search V2
Search Amazon products by keyword, category, and multi-dimensional filters.
Use this to discover products in a specific niche, analyze competitor listings, or find high-demand low-competition opportunities. Example: search "yoga mat" in Sports & Outdoors with monthlySalesFloor >= 500 and price <= $30 to find proven sellers in an affordable range. Data is based on the latest daily snapshot; results are paginated (max 100 per page). Related: /products/competitors for competitor analysis, /products/history for trends.
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.
Get product traffic structure profile
Function
ASIN traffic structure and change drivers comparing the current week with the previous week; not a multi-week trend profile. Return current- and previous-week traffic profiles for up to 20 ASINs; the actual date is resolvedDate, and only status=ok items are charged.
Use cases
Investigate week-over-week traffic changes using placement structure and keyword contributions. Use product-traffic-trend-profile for precomputed four-week conclusions or product-traffic-trend for weekly raw data.
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 (YYYY-MM-DD). Returns the latest profile on or before this date; actual date is `resolvedDate`. | |
| asins | No | ASIN batch; mutually exclusive with asin, up to 20. Duplicates after normalization are rejected. | |
| granularity | No | Data period granularity. Only `week` is currently 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?
With no annotations provided, the description carries full behavioral disclosure responsibility. It meaningfully discloses that this is a week-over-week comparison, not a multi-week trend, that the actual lookup date is `resolvedDate`, and that only `status=ok` items are charged. This is strong context, though it could go further on read-only safety or output shape.
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 portion is well-structured and front-loaded, with a brief 'Function' section followed by a concise 'Use cases' section. The embedded response schemas add length, but they provide useful structured detail given the lack of a formal output schema. No redundant filler in the explanatory text.
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 complete enough for an agent to decide when and how to call this tool: it explains the comparison window, payload limits, charge behavior, and alternatives. It does not fully describe the data payload's internal structure, but the use cases and generic response schema give adequate invocation 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?
Input schema description coverage is 100%, so the schema already documents all parameters. The description adds some operational context, such as the 20-ASIN cap and the resolved-date behavior, but does not significantly enrich parameter meaning beyond what the schema 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 a specific verb and resource, then clearly states what the tool does: ASIN traffic structure and change drivers comparing the current week with the previous week, returning profiles for up to 20 ASINs. It explicitly distinguishes itself from multi-week trend tools and names related 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 'Use cases' section explicitly states when to use this tool: to investigate week-over-week traffic changes via placement structure and keyword contributions. It also names the exact alternatives, product-traffic-trend-profile and product-traffic-trend, and their different purposes, so an agent can choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get product traffic terms
Function
Return the target ASIN's traffic-keyword list for a single weekly snapshot, with filtering, sorting and pagination. Includes impression points, positions, traffic shares, estimated searches and ABA ranks; resolvedDate is the actual snapshot date. This is current-period discovery data, not a trend or time-series endpoint.
Use cases
Discover the target ASIN's current traffic-driving keywords, for either your own product or a competitor. Then pass selected keywords to product-traffic-terms-trend for their weekly history, or use product-traffic-trend for ASIN-level weekly totals.
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 (YYYY-MM-DD). Returns the latest snapshot on or before this date; actual date is `resolvedDate`. | |
| page | No | Page number, starting at 1. | |
| sortBy | No | Sort field: trafficShare=ASIN keyword-traffic share; estimateImpressionPoint=estimated impressions; absolutePosition=SERP position; avgPosition=average position; latestObservedAt=latest observation; keywordEstimateSearchCount=estimated searches; keywordAbaRank=numeric ABA rank; keyword=lexical order. | trafficShare |
| pageSize | No | Items per page; 1 to 100. | |
| sortOrder | No | Sort direction. | desc |
| granularity | No | Data period granularity. Only `week` is currently supported. | 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 | Non-empty substring filter for returned keywords; omit to disable this filter. | |
| keywordAbaRankMax | No | Maximum numeric keyword ABA rank; must not be below keywordAbaRankMin. | |
| keywordAbaRankMin | No | Minimum numeric keyword ABA rank; must not exceed keywordAbaRankMax. | |
| keywordEstimateSearchCountMax | No | Maximum estimated keyword search count; must not be below keywordEstimateSearchCountMin. | |
| keywordEstimateSearchCountMin | No | Minimum estimated keyword search count; must not exceed keywordEstimateSearchCountMax. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the disclosure burden. It clarifies the snapshot nature (single weekly resolved date vs trend), lists returned fields (impressions, positions, estimated searches, ABA rank), and flags the granularity constraint. It does not disclose auth requirements, rate limits, empty-result behavior, or whether results for a brand-new ASIN may be absent — modest but not severe 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?
Compact two-section layout (Function / Use cases) with a short rationale sentence. The embedded response example and schema are relevant. It stays readable and avoids boilerplate, though a couple of lines are spent restating generic wrapper fields.
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?
Covers the resource, the snapshot-vs-trend distinction, the resolved date concept, filtering/sorting/pagination, and follow-on usage. Notable gap: the required 'target ASIN' and 'date' inputs are not visible in the given schema, and the response example omits the data payload — but the surrounding text still conveys the essentials for a correct call.
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 per-parameter descriptions and constraints. The description adds context by mentioning filtering, sorting, and pagination, but the parameter meanings largely come from the schema. No penalty for duplication, but no added semantic value beyond the schema either.
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?
States a precise verb+resource+mode: returns the target ASIN's traffic keywords for a single weekly snapshot, with sorting/filter/pagination, and explicitly says it is not a trend/time-series endpoint. Names the exact sibling (product_traffic_terms_trend) it is not, so there is no ambiguity.
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 a dedicated 'Use cases' section: tells the agent to use it for current-period traffic keywords, and routes to product_traffic_terms_trend for per-keyword history or product_traffic_trend for weekly totals. It does not list prerequisites (e.g. required asin/date), but the when-to-use guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get product traffic-term trend
Function
Per-keyword weekly traffic data for one ASIN; not ASIN-level aggregate traffic. Return weekly traffic-term timelines for an ASIN and up to 20 keywords, with a maximum 26-week range; the actual end date is resolvedDateTo. Results split impressions, positions, and ad activity by ORG/SP/SB/SBV/SPR; only status=ok items are charged.
Use cases
Inspect when selected keywords gained or lost traffic for one ASIN and compare placements and ad activity. Use product-traffic-trend for the ASIN's overall weekly raw data.
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 (YYYY-MM-DD); on or after `dateFrom`, with a maximum 26-week range. Actual range is `resolvedDateFrom` through `resolvedDateTo`. | |
| keyword | No | Exact keyword to query. Mutually exclusive with `keywords`. Must equal `LOWER(TRIM(value))`; uppercase letters and surrounding whitespace are rejected. | |
| dateFrom | Yes | Start date (YYYY-MM-DD); maximum 26 weeks. | |
| keywords | No | Keywords to query for the same ASIN in batch, up to 20. Mutually exclusive with `keyword`. Must equal `LOWER(TRIM(value))`; uppercase letters and surrounding whitespace are rejected. Duplicate keywords are rejected. | |
| granularity | No | Data period granularity. Only `week` is currently 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?
With no annotations, the description carries the behavioral burden and does well: it warns that results are not ASIN-level aggregate, notes the effective date boundary via resolvedDateTo, states placement breakdown (ORG/SP/SB/SBV/SPR), and flags that only status=ok items are charged. It does not cover auth, rate-limit, or error-behavior details, so it stops short of a 5.
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 organized into short labeled sections; every sentence carries scoping, use-case, or billing information. It is front-loaded with the core function and avoids redundancy with 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 7-parameter tool with no annotations and a mostly untyped data payload, the description covers invocation context, key constraints, output dimensions, and the sibling distinction. It lacks a detailed list of response value fields, but the stated 'weekly traffic-term timelines... split impressions, positions, and ad activity' gives enough shape for 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?
Schema description coverage is 100%, so the schema already documents all 7 parameters including exact keyword lower/trim rules and the keyword/keywords mutual exclusion. The description adds the 'up to 20 keywords' scope and 26-week cap, but these largely restate schema constraints, 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 opens with a clear verb-resource pair ('Get product traffic-term trend') and then specifies the exact granularity: per-keyword weekly traffic for one ASIN, not ASIN-level aggregate. The distinction from sibling openapi_v2_product_traffic_trend is stated, so an agent can disambiguate without inspecting schema.
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?
A dedicated 'Use cases' section explains when to call the tool: inspect when selected keywords gained or lost traffic for one ASIN and compare placements and ad activity. It also explicitly routes the user to product-traffic-trend when the ASIN's overall weekly raw data is needed, which is a clear when-not/alternative instruction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get product traffic trend
Function
ASIN-level weekly raw traffic data across all keywords; no keyword dimension. Return up to 26 complete Sunday-Saturday periods for up to 20 ASINs. Includes total, organic and advertising impression points, keyword coverage and distributions. Impression points are estimated traffic scores, not actual impression counts. Read items[].status before series; missing weeks are not filled with zero. Items follow request order; missing ASINs remain as empty items. Only status=ok ASINs are charged.
Use cases
Plot and compare ASIN-level weekly traffic and keyword coverage, and locate changing weeks. Use product-traffic-terms-trend for per-keyword data, or product-traffic-trend-profile for precomputed four-week conclusions.
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[ProductTrafficTrendData]",
"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. | |
| asins | No | ASIN batch, up to 20; mutually exclusive with asin. Duplicates after normalization are rejected. | |
| dateTo | Yes | End date (YYYY-MM-DD); on or after dateFrom, containing at most 26 complete Sunday-Saturday weeks. Actual published coverage is reported in resolvedDateFrom and resolvedDateTo. | |
| dateFrom | Yes | Start date (YYYY-MM-DD). Only complete weekly periods contained in the requested range are returned. | |
| granularity | No | Data period granularity. Only `week` is currently 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?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It reveals that impression points are estimated scores not actual counts, that missing weeks are not zero-filled, that items follow request order, that missing ASINs remain empty, and that only status=ok ASINs are charged. These are exactly the non-obvious behavioral facts an agent needs.
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 free-text 'Function' and 'Use cases' sections are tight, front-loaded, and every sentence earns its place. The embedded response schemas and credit-field documentation add length and some cross-endpoint boilerplate, but the numbered section headers keep the definition scannable. A minor deduction for that generic response bulk.
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 no-annotation tool with no separate data output schema, the description covers most critical response facts: total/organic/ad impression points, keyword coverage, items[].status, empty items for missing ASINs, and limited weekly ranges. It stops short of enumerating the full response field structure and possible status values, but it gives enough context for an agent to select and call this 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 igh at 100% and the schema already documents asin/asins mutial exclusivity, date format and range constraints, granularity, marketplace, and max 20 ASINs. The description does not add per-parameter meaning beyond that; its extra detail is mostly about response behavior and data interpretation, which maps better to other dimensions. Therefore the baseline of 3 applies.
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 product traffic trend' and immediately narrows scope to ASIN-level weekly raw traffic data across all keywords with no keyword dimension. It explicitly distinguishes itself from product-traffic-terms-trend and product-traffic-trend-profile, making the tool's purpose and boundaries unmistakable.
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 'Use cases' section tells the agent exactly when to invoke this tool: to plot, compare, and locate changing weeks in ASIN-level weekly traffic and keyword coverage. It also names the two sibling tools to use instead when the need is per-keyword data or precomputed four-week conclusions, which is explicit routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get product traffic trend profile
Function
ASIN-level precomputed four-week traffic conclusions. Return traffic trend profiles for up to 20 ASINs. Only windowPeriods=[4] is currently supported and is the default when omitted. Includes impression, keyword-coverage and distribution evidence with metric directions. Items and window rows follow request order. Charge each ASIN once when at least one row has status=ok; empty profiles are free. The actual snapshot date is resolvedDate. detailLevel defaults to summary: core traffic and keyword coverage with component status, classifications, first/last values and change rates. Request full for placement/distribution breakdowns and all evidence. The mode is echoed in context.detailLevel and changes neither the query nor billing. Read items[].rows[].status (not items[].status), then component supported/calculationStatus before metrics; null is unavailable, not zero. Use trend as the overall conclusion and trendEvidence as its supporting metrics, not as a forecast or causal explanation. Impression points are estimated traffic scores, not actual impression counts. Share changes are absolute decimal differences: 0.05 means +5 percentage points; change rates are relative: 0.05 means +5%. Do not compare normalized slope magnitudes across ASINs or interpret them as percentage growth; the formula is not specified here.
Window validation failures return HTTP 422 VALIDATION_ERROR with supportedValues, suggestedValue and hint in error.details.errors; no query runs and no credits are consumed.
Use cases
Summarize an ASIN's observed four-week traffic and keyword-coverage direction. Use product-traffic-trend for weekly raw data, product-traffic-structure-profile for adjacent-week structure and contributions, and detailLevel=full when detailed evidence is needed.
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[ProductTrafficTrendProfileData]",
"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 (YYYY-MM-DD). Returns the latest profile on or before this date; see resolvedDate. | |
| asins | No | ASIN batch, up to 20; mutually exclusive with asin. Duplicates after normalization are rejected. | |
| detailLevel | No | Response detail only; does not change the data query or billing. Default summary retains total, organic and advertising traffic and keyword coverage, component status, classifications, first/last values and change rates. full additionally includes placement/distribution breakdowns and all statistical evidence. Retry with detailLevel=full only when that extra evidence is needed; use product-traffic-trend for weekly raw data. | summary |
| granularity | No | Data period granularity. Only `week` is currently supported. | week |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | US |
| windowPeriods | No | Defaults to [4]. windowPeriods must be [4] (one 4-week window). If a 4-week profile meets the task, retry with windowPeriods=[4] and the other arguments unchanged; otherwise report the supported scope. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden; it does so thoroughly. It discloses billing behavior ('Charge each ASIN once when at least one row has status=ok; empty profiles are free'), response-reading requirements ('Read items[].rows[].status, not items[].status'), null semantics, unit semantics for share changes and change rates, the non-forecast nature of trendEvidence, and the fact that impression points are estimated traffic scores.
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 front-loaded with a one-line summary and organized into Function, Use cases, and validation behavior. The lengthy caveats are dense but each earns its place because they cover billing, status semantics, units, and error conditions that are essential for correct use.
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—7 parameters, batch ASINs, multiple detail levels, status hierarchy, and billing nuances—the description is complete enough for an agent to select and invoke it correctly. It covers input constraints, output interpretation, error behavior, and credit consumption, while the rich schema descriptions handle the remaining parameter-level details.
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 meaning beyond the schema by clarifying that windowPeriods=[4] is the only supported window, that detailLevel changes response content but not query or billing, and that resolvedDate is the actual snapshot date. It also gives billing and error semantics tied to parameters, which helps the agent invoke the tool correctly.
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: 'Get product traffic trend profile' and then defines the exact scope: ASIN-level precomputed four-week traffic conclusions for up to 20 ASINs. It also distinguishes this tool from closely related siblings by naming product-traffic-trend for weekly raw data and product-traffic-structure-profile for adjacent-week structure and contributions.
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?
Section 2 explicitly states the intended use case: 'Summarize an ASIN's observed four-week traffic and keyword-coverage direction.' It also gives concrete routing guidance to alternatives (product-traffic-trend, product-traffic-structure-profile, detailLevel=full) and describes when validation errors occur, so an agent can decide when to use this tool versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Realtime Product V2 Legacy
[DEPRECATED] Legacy realtime product shape — use openapi_v3_realtime_product.
Returns the pre-#327 response (opaque buyboxWinner/ratingBreakdown/bestsellersRank,
variants keyed by dimensions, no top-level price). Kept for backward
compatibility; migrate to the v3 tool/endpoint for the typed protocol.
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.
Realtime Reviews V2
Fetch realtime reviews for a given ASIN.
Cursor-based pagination: omit cursor for the first page, then pass nextCursor from the previous response for subsequent pages. nextCursor=null means no more data. Related: /reviews/search for review data with AI tags, /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.
Reviews Search V2
Search reviews for an ASIN with multi-dimensional filters.
Filters: star rating range, verified purchase, Vine program, helpful vote count, date range, and AI-generated tags. Results sorted by recent/rating/helpfulVoteCount. Page-based pagination (default 10 per page, max 20). Data sourced from daily BigQuery snapshot with AI-generated tags. Related: /realtime/reviews for live data, /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.
Tiktok Categories
Query the TikTok Shop category tree by ID, path, parent, or keyword.
Use this to discover the category hierarchy for filtering in
/tiktok/products/search. Example: pass parentCategoryPath=["Automotive & Motorcycle"] to enumerate its direct children. The tree is
English-only and global (not region-scoped). productCount reflects
the latest US-region snapshot (v1).
Query modes (mutually exclusive):
No parameters: Returns all root categories (level 1)
categoryId: Single category by ID
categoryPath: Single category by full path
parentCategoryId: Children of a parent by ID
parentCategoryPath: Children of a parent by path
categoryKeyword: Substring match on category name
Related: /tiktok/products/search accepts categoryId or categoryPath for filtering.
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.
Tiktok Creators Search
Search TikTok creators by profile, category, content, and commerce signals.
Data is from the latest daily creator snapshot within the fallback window (region = US in v1). Related-product sales fields describe the overall product sales for SPUs the creator promoted, not creator-attributed GMV. 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.
Tiktok Products Search
Search TikTok Shop products by keyword, category, and multi-dimensional filters.
Use this to discover top-selling SPUs in a niche, narrow by category and
price / shipping signals, or surface fast-growing products by 30-day sales growth.
Example: categoryPath=["Automotive & Motorcycle"] with
categoryRankMax=100 returns the category's top 100 sellers.
Data is from the latest daily snapshot (region = US in v1). Results are paginated (max 100 per page).
Metric coverage today includes saleCnt*, saleAmt*, regionRank,
categoryRank, price / RRP, rating / review count, SKU details, and
populated shop flags.
Related: /tiktok/categories for category tree discovery.
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.
Tiktok Realtime Product
Get realtime TikTok Shop product detail for a single product (SPU) ID.
Use this when you need the product's current state rather than daily-updated values: current price, rating, units sold, inventory, shipping options, SKU variants (selectedOptions), and shop details. Data is collected on demand, so latency is higher than the daily-updated endpoints (typically 2-5 seconds). Only the US marketplace is available currently. Related: /tiktok/products/search for daily-updated data across many products.
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.
Tiktok Realtime Video
Get realtime TikTok video detail for a single video URL.
Returns the video's current state — title, engagement counters (plays, likes, comments, shares), creator profile, soundtrack, and any shopping anchors (linked TikTok Shop products) — collected on demand, so latency is higher than daily-updated endpoints (typically a few seconds). Only tiktok.com video URLs are accepted; short links are not supported. Related: /tiktok/videos/search for daily-updated data across many videos, and /tiktok/realtime/product for full detail on an anchored product.
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[TikTokRealtimeVideo]",
"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 | TikTok video page URL, e.g. https://www.tiktok.com/@handle/video/7300000000000000001 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden, and it discloses meaningful behavior: data is collected on demand, latency is typically a few seconds, and the endpoint only accepts canonical tiktok.com URLs. It clearly implies a read-only operation, though it does not discuss rate limits, credential requirements, or invalid-URL failure 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 prose is tightly written and front-loaded, but the embedded response schemas add a lot of boilerplate, especially the ADR-0003 credit-field discussion and TODO notes that are irrelevant to invoking this endpoint. The description would be stronger if the generic meta/error schema details were trimmed.
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 one-parameter read endpoint, the description covers purpose, alternative tools, URL constraints, latency, expected data fields, and response codes. It is missing a concrete shape for the `data` payload (the 200 schema only shows the generic wrapper), but the prose enumeration of returned fields compensates.
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 documents the single `url` parameter with an example, so baseline is 3. The description adds genuinely useful semantics by restricting input to tiktok.com video URLs and explicitly rejecting short links.
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: 'Get realtime TikTok video detail for a single video URL.' It also distinguishes itself from sibling endpoints by explicitly naming /tiktok/videos/search and /tiktok/realtime/product, so an agent can tell which tool matches the use case.
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 selection criteria: use this for a single video's current on-demand state, /tiktok/videos/search for daily-updated data across many videos, and /tiktok/realtime/product for full product detail. It also states an exclusion: only tiktok.com URLs are accepted and short links are not supported.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tiktok Videos Search
Search daily-updated TikTok videos by engagement, creator, and commerce signals.
Filter by play and like counts, interaction rate, creator follower count, publish date, whether the video carries a shoppable product, and the product's category (by id or path). Each video also returns the primary product's category id and path. Data is from the latest daily video collection within the fallback window. Interaction rate is (likes + comments + shares + saves) / plays, as a decimal; it is computed per video, so filtering by it narrows the result set but does not reduce query time. Related: /tiktok/creators/search and /tiktok/products/search.
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; values above 20 are served as 20. 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 burden. It discloses that data is daily-updated and from a fallback window, and explains that interaction rate is computed per video and filtering by it doesn't reduce query time. These are behavioral nuances beyond what a schema would provide. It doesn't mention side effects, but the read-only nature is implied by 'search'. Overall, good 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 is front-loaded with the purpose and filters in the first paragraph, then includes a note on interaction rate and related tools. It also includes detailed response examples and output schema, which is necessary since there is no separate output schema field. While lengthy, the structure is logical and the text is not redundant with the schema (except some repetition of interaction rate formula). It 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 complex tool with 26 parameters and no annotations, the description covers the main filter groups, data freshness, interaction rate behavior, and related tools. It also provides response structure via examples. The only minor gap is not explicitly mentioning pagination behavior, but that is well-covered in the schema (page/pageSize). Overall, it is quite complete for the complexity.
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 26 parameters. The description adds value by explaining the interaction rate formula (already in schema but restated) and the note that filtering by interaction rate doesn't reduce query time, which is not in the schema. It also clarifies the data source. This is a modest addition beyond the schema, so above 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 clearly states the tool searches TikTok videos with specific filters (engagement, creator, commerce signals). It lists concrete filter dimensions and even names related tools (/tiktok/creators/search, /tiktok/products/search), making the purpose unambiguous and distinguishing it from 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 provides usage context by naming related tools for creators and products, implying that this tool is for video-level search. It also explains the data freshness (latest daily collection within fallback window) and the interaction rate filtering behavior, which helps an agent decide when to use this tool. However, it doesn't explicitly state when NOT to use it, but the sibling naming gives a strong hint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Voc 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.
Add 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.
List 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.
Remove 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.
Poll a crawl job
Poll a crawl job's status. data[] contains already-scraped pages.
Paginate with the skip / limit query params when data[] grows
large. Returns 404 when the job id is unknown or belongs to a
different tenant — the two cases are deliberately indistinguishable so
job-id existence does not leak across tenants.
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.
Submit a crawl job
Submit an async recursive crawl job.
Returns an opaque id; poll GET /webtools/crawl/{id} for status and
finished pages. robots.txt is always honored; external-domain links
are not followed. limit defaults to 100 pages (cap 10000) — set it
explicitly when crawling a larger site. The returned id is bound to
the calling tenant: polling from a different API key returns 404.
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.
Discover URLs on a website
Discover URLs from a website via sitemap and on-page link discovery.
Returns a flat, relevance-ordered list of links (each with optional title /
description). Use search to rank links by keyword relevance;
sitemapMode to control sitemap usage (include / only /
skip); includePaths / excludePaths to filter by URL path regex
(≤50 patterns, ≤500 chars each); and limit (1-100000, default 5000) to
cap results.
Subdomains of the seed host are included by default; set
includeSubdomains to false to lock discovery to the exact seed
host. URLs that differ only by query string are collapsed by default
(ignoreQueryParameters = true); set false to keep query-string
variants as distinct URLs.
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.
Scrape a single URL
Scrape a single URL and return clean content.
Specify one or more of markdown / json / rawHtml in
formats. json returns a structured page summary
(title, page_type, key facts, main entities, etc.) — the extraction
schema is built in, so you don't need to define one in your request.
Response meta carries the target page's HTTP status code, title,
canonical URL, description, and detected language. Always check
meta.statusCode before trusting the content body: a 4xx/5xx (e.g. 404
or a 5xx) usually means the content is an error page, not the real page.
A page that refuses the request (HTTP 401/403/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.
Scrape a page after running browser actions
Scrape after executing a sequence of browser actions.
Supports seven action types: wait, click, write, press,
scroll, scrape, executeJavascript. (screenshot and
pdf are intentionally excluded — their artifacts have no place in
the markdown/json/raw_html response surface.) Cumulative wait time
across all actions is capped at 60 seconds; over-cap requests are
rejected with HTTP 422.
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.
Search 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.
Realtime Product V3
Get realtime product data for a given ASIN.
Use this when you need the product's current state rather than daily-updated values. Example: pass asin="B07FR2V8SH" to get the current price, rating, review count, Best Sellers Rank, inventory, variants (selectedOptions), and Buy Box offer. Data is collected on demand, so latency is higher than the daily-updated endpoints (typically 2-5 seconds). Related: /products/search for daily-updated catalog data, /products/history for trend analysis.
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 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 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"string"New value: +"array"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"array"New value: +"string"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"string"New value: +"array"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"array"New value: +"string"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"string"New value: +"array"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"array"New value: +"string"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"string"New value: +"array"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"array"New value: +"string"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"string"New value: +"array"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"array"New value: +"string"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"string"New value: +"array"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"array"New value: +"string"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"string"New value: +"array"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"array"New value: +"string"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"string"New value: +"array"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"array"New value: +"string"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"string"New value: +"array"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"array"New value: +"string"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"string"New value: +"array"openapi_v2_image_embedding1 field changedInput schema / properties / text / typePrevious value: -"array"New value: +"string"
Add one secure layer between your agents and this server.
