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 57 tools
Most tools target distinct resources, but several clusters overlap heavily: openapi_v2_realtime_product (explicitly deprecated) vs openapi_v3_realtime_product is a direct ambiguity, and the five product_traffic_* / four keyword_* variants plus keyword_detail vs keyword_market_profile require careful reading to pick correctly. Descriptions do differentiate them, but boundaries are thin for an agent scanning 57 names.
Two conventions coexist: clean verb_noun for the newer tools (create_video_asset, get_video_asset, list_video_assets, submit_video_generation, poll_video_task, get_account_balance) versus the legacy openapi_v2_*/openapi_v3_* resource-path style for the bulk. Within the openapi group there are also singular/plural inconsistencies (products_search vs product_traffic_terms). Readable but not uniform.
57 tools is far above the heavy threshold and reflects a sprawling multi-domain surface (Amazon catalog, TikTok, keyword/market/traffic analytics, fashion ML embeddings, web scraping, video generation). Even for an aggregator this is not well-scoped and imposes a large selection burden on the agent.
Coverage across the e-commerce intelligence domains is unusually thorough — search, detail, history, trend, leaderboards, competitor, VoC, watchlist CRUD, realtime, and web tools all present. Minor gaps remain: no delete/update for registered video assets and no dedicated listing-level management APIs, but core lifecycles are covered.
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 accepts categoryPath. /markets/search uses exactly one of category.ids, category.path, or category.name; category.includeDescendantCategoryProducts controls whether each market's metrics include descendant-category 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": {
"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?
Annotations are absent, so the description carries the full burden. It implies read-only behavior via 'Query' and states that no parameters returns all root categories, but it does not explicitly declare read-only status, authentication requirements, rate limits, or side effects. It does disclose mutual exclusivity of parameters and provides response structure, but without annotations, a more explicit behavioral profile would be stronger.
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 concise and well-structured: purpose, example, query modes, and related endpoints are clearly organized and front-loaded. However, the description includes a large response schema block (due to no separate output schema) that makes the overall text lengthy, though this is a necessary inclusion rather than redundancy. The core guidance is tight 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?
The description covers all 6 optional parameters, explains the behavior for each query mode, includes examples, and details how this tool connects to other endpoints. It also embeds the output schema (since no separate schema exists) and error responses. For a read-only discovery tool with no required parameters, this is comprehensive enough for an agent to select and invoke it correctly without ambiguity.
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 describes each parameter (100% coverage), but the description adds significant context: it explains the mutual exclusivity of query modes, what each mode does (e.g., 'No parameters: Returns all root categories'), and provides an example. This goes beyond the schema's field descriptions, enhancing the agent's understanding of parameter combinations and intended usage.
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 queries the Amazon category hierarchy by ID, path, parent, or keyword, with a specific verb and resource. It lists distinct query modes and gives an example, and it explicitly distinguishes itself from sibling tools by mentioning related endpoints like /products/search and /markets/search, 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 explicit usage guidance: 'Use this to discover category structure for filtering in other endpoints' and then describes how this tool relates to /products/search and /markets/search, including the exact parameters those endpoints accept. It also details mutually exclusive query modes and gives a concrete example with categoryKeyword and parentCategoryPath, leaving no ambiguity about when to use it versus alternatives.
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?
With no annotations, the description carries the full burden. It discloses that data is based on the latest daily snapshot and that results are paginated (max 100 per page). It also implies a read-only operation via the response schema. These are useful behavioral details, though it doesn't cover authentication, rate limits, or specific side effects (likely none for a search). It adds 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 core prose is concise and front-loaded with purpose and example. However, the overall description block includes large embedded response schemas (200 and 422) that are redundant given the separate output schema fields. This bloats the definition and reduces conciseness, though the key information is upfront.
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 22 parameters, the description covers the main use case, pagination, and snapshot behavior. It includes an example that clarifies usage. While it doesn't explain every filter in prose, the schema provides those details. The description is sufficient for an agent to select and invoke the tool correctly, though it could mention return value structure more explicitly.
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 descriptions for all 22 parameters (100% coverage). The description only adds an example use of the 'asin' parameter, which is more about usage than parameter semantics. Since the schema fully documents each parameter, the description adds minimal extra meaning, meeting the baseline of 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 function: 'Search competitor products by keyword, brand, ASIN, or category with filters.' It gives a concrete example with an ASIN and differentiates from a sibling tool by noting 'Related: /products/search for broader keyword discovery.' This is specific and distinguishes it from other 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 explains when to use it: 'Use this to identify competing products around a specific listing or brand.' It also mentions an alternative for broader searches, implying when not to use it. However, it doesn't explicitly state conditions like 'use this instead of products_search when you need competitor context,' so it's clear but not exhaustive.
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.
Function
Return data.points[] in ascending date order for one US category market. Each point groups full-category measures under marketTotal and selected Top 100 measures under marketSample, including size, estimated monthly sales and revenue, plus 1/3/6/12-calendar-month new-product measures. For each period, marketTotal contains new-SKU count, share of all category SKUs, monthly sales, and monthly revenue; marketSample also contains averages and shares.
Use cases
Use history to inspect observed market changes over time. Use search for a current snapshot and structure-profile with a selected date for distribution evidence.
Example
Call with {"categoryId":"1045564","includeDescendantCategoryProducts":true,"sampleType":"unitSalesTop100","dateFrom":"2026-08-01","dateTo":"2026-09-14"}. Read data.points[].date, data.points[].marketTotal.monthlyRevenue, data.points[].marketSample.monthlyRevenue and data.resolvedDateFrom/data.resolvedDateTo.
Data range
US only. Returns available month-end snapshots inside the requested inclusive range; missing months are not filled. An empty points list means no month-end snapshot was found in that range.
New-product definition
At each point date and for each newProductMetrics[] item with periodMonths=N, a product is new only when its business launch date is later than that date minus N calendar months and no later than that date. The business launch date prefers Amazon Date First Available; when unavailable, it uses the earliest valid SKU first-observed date, SKU first-review date, or parent-product first-review date. Products without a business launch date are not counted as new.
| Name | Required | Description | Default |
|---|---|---|---|
| dateTo | Yes | Last date of the requested history range (YYYY-MM-DD), inclusive; must be on or after dateFrom. | |
| dateFrom | Yes | First date of the requested history range (YYYY-MM-DD), inclusive. | |
| categoryId | Yes | Amazon category node ID to analyze. | |
| sampleType | No | How to select the Top 100 products within the category scope: by estimated monthly unit sales or by estimated monthly revenue. | unitSalesTop100 |
| marketplace | No | Amazon marketplace; currently US only. | US |
| includeDescendantCategoryProducts | No | Whether market metrics include products assigned to descendant category nodes; defaults to true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and it does well: it states the data range (US only), describes the return format (month-end snapshots, missing months not filled, empty list meaning), and provides a detailed new-product definition including fallback logic for launch date. This goes beyond what the schema provides and fully discloses key behaviors.
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, front-loading the function purpose and use cases, then providing an example and additional context. It is detailed but not overly verbose; each section adds value. It could be slightly more concise, but the density is reasonable for a complex 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 the tool's complexity (output structure, new-product definition, missing data behavior), the description is comprehensive: it covers return format, data range, example call, and the crucial new-product definition. With no output schema, the description fills the gap by explaining what data.points[] contains. Sibling tools are differentiated, and the agent has everything needed to call 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 schema already documents all six parameters. The description adds an example call that illustrates parameter values but doesn't add extra semantics beyond the schema. It does explain the new-product definition which is crucial for interpreting the data, but that's more about output than parameters. Baseline 3 is appropriate since schema covers everything.
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 data.points[] in ascending date order for one US category market, with specific measures under marketTotal and marketSample. It distinguishes it from sibling tools like openapi_v2_markets_search and openapi_v2_markets_structure_profile by explicitly stating they serve different use cases (snapshot and distribution evidence).
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, including when to use history vs. search vs. structure-profile, and guides the agent to use search for current snapshot and structure-profile for distribution evidence. However, it doesn't mention when NOT to use this tool beyond those alternatives, so it's not fully explicit about exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Function
Find a paginated list of US Amazon category markets. Each data[] row contains the category identity and current market measures grouped by statistical scope. data[].marketTotal contains full-category measures; data[].marketSample contains selected Top 100 sales, per-product averages and competition. productTopNMetrics[] and brandTopNMetrics[] each have one row for N=3/5/10/20. Both return avgBsr, avgMonthlySales, avgMonthlyRevenue, monthlySales, monthlyRevenue, monthlySalesRate and monthlyRevenueRate. Product rows also return productTopN and topNSkuCount; brand rows return brandTopN and topNBrandCount. Each row selects the leading products or brands by monthly unit sales; productTopN and brandTopN are rank cutoffs, topNSkuCount is the actual number of selected products, and topNBrandCount is the actual number of selected brands. Brand averages are per product in the selected brands. Both statistical scopes return newProductMetrics[] for 1/3/6/12 calendar-month windows. marketTotal returns new-SKU count, share of all category SKUs, monthly sales, and monthly revenue for each window; marketSample additionally returns averages and shares. meta.total is the number of matching markets.
Use cases
Use search to compare markets by size, per-product sales, price, BSR, package weight or volume, ratings, gross margin, fulfillment, new-product performance or Top N concentration in one call. All filters apply before pagination. topN selects the group used by generic Top N filters; newProductPeriod selects the window used by generic new-product filters and sorting. Neither selector limits the response arrays. Sample sales and revenue filters use per-product averages so markets with different actual sample counts remain comparable. Use category.ids to select multiple market rows by category ID. category.includeDescendantCategoryProducts controls whether each row's product metrics include descendant categories and defaults to true. Alternatively, use a complete category.path or exact category.name; omit all locators to search every market. category.name filters by the exact node name and may return multiple market IDs. For fuzzy category discovery, use /categories. Use structure-profile for its distributions or history for its time series.
Example
Call with {"category":{"ids":["1045564","1234567"],"includeDescendantCategoryProducts":true},"filters":{"sampleAvgMonthlySalesMin":1500,"sampleAvgGrossMarginRateMin":0.2,"topNProductMonthlySalesRateMax":0.5},"sampleType":"unitSalesTop100","topN":"10","newProductPeriod":"3","page":1}. Read data[].categoryId, data[].marketTotal.monthlySales, data[].marketTotal.newProductMetrics[], data[].marketSample.avgMonthlySales, data[].marketSample.productTopNMetrics[], data[].marketSample.brandTopNMetrics[], data[].marketSample.newProductMetrics[] and meta.total.
Data range
US only. Each category ID yields its own market row. By default, its product measures include products assigned directly to the category and its descendants without duplicates; set category.includeDescendantCategoryProducts=false to count only directly assigned products. Top 100 is selected by monthly unit sales or revenue. If date is omitted, the latest available snapshot is used; data[].date gives its actual date. category.path resolves the complete path to one category ID before search; category.name matches the node name exactly. Historical flat requests, including categoryKeyword, remain accepted through Pydantic. New requests use /categories for fuzzy name discovery. Legacy dateRange remains accepted but is not part of the published request schema. Top N and new-product filters use topN and newProductPeriod respectively. Gross-margin rates use decimals from 0 to 1; monetary filters use USD.
New-product definition
For each newProductMetrics[] item with periodMonths=N, a product is new only when its business launch date is later than data.date minus N calendar months and no later than data.date. The business launch date prefers Amazon Date First Available; when unavailable, it uses the earliest valid SKU first-observed date, SKU first-review date, or parent-product first-review date. A missing business launch date is not classified as new; the product still remains in the product-count denominator. Search returns all four windows so an Agent can compare short- and long-window new-product activity without additional calls.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Snapshot lookup date (YYYY-MM-DD); defaults to latest available. | |
| page | No | Page number, starting at 1. | |
| topN | No | Top group size used by generic Top N filters. The response always returns all four groups. | 10 |
| sortBy | No | Market metric used for sorting. | sampleMonthlyRevenue |
| filters | No | Market metric conditions, applied before pagination. | |
| category | No | Choose IDs, a complete path, or an exact name; omit all locators to search all markets. | |
| pageSize | No | Markets per page. | |
| sortOrder | No | Sort direction. | desc |
| sampleType | No | Select Top 100 by monthly unit sales or revenue. | unitSalesTop100 |
| marketplace | No | Amazon marketplace; currently US only. | US |
| newProductPeriod | No | New-product window used by generic new-product filters and sorting. The response always returns all four windows. For a window of N months, a product is new when its business launch date is later than the snapshot date minus N calendar months and no later than the snapshot date. Products without a business launch date are not counted as new, but remain in the product-count denominator. | 3 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it delivers: it explains pagination, filter-before-pagination, Top 100 selection by sales/revenue, response always includes all Top N groups, new-product window semantics, date default, descendant inclusion default, and legacy parameter acceptance. This far exceeds what an agent needs for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but it is explicitly sectioned (Function, Use cases, Example, Data range, New-product definition) and front-loaded with the core function. Some redundancy with schema descriptions exists, but the structured format lets agents skip to relevant sections, so the length is largely justified; a small trim would move this to 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 11 parameters, nested objects, no output schema, and no annotations, the description is exceptionally complete: it describes returned data structures (marketTotal, marketSample, productTopNMetrics, brandTopNMetrics, newProductMetrics, meta.total), pagination, defaults, and edge cases like products without launch dates. An agent has enough to call it correctly and interpret 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?
Although the schema already has 100% parameter coverage, the description adds crucial semantics: sample filters operate on per-product averages, category.path resolves to one ID while category.name may match multiple IDs, legacy dateRange/categoryKeyword remain accepted via Pydantic, and gross-margin rates are decimals 0-1 while monetary values are USD. These clarifications materially reduce misuse.
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 'Find a paginated list of US Amazon category markets', a specific verb+resource+scope, and later contrasts itself with sibling tools like /categories, markets_structure_profile, and markets_history for fuzzy discovery, distributions, and time series. An agent can immediately distinguish this search tool from related market tools without opening schemas.
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 lists when to use search versus /categories for fuzzy discovery, structure-profile for distributions, and history for time series. It also explains locator alternatives (ids, path, name, or omit all) and notes legacy endpoints remain accepted, giving clear when-to-use and when-not-to guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Function
Return one selected Top 100 product distribution for one US category market. The required dimension parameter selects exactly one of brand, seller, price, sellerCountry, fulfillment, ratingCount, rating, listingAge, listingYear or productFeature. The response echoes data.dimension and returns its groups in data.buckets[], including product count, estimated sales and revenue, Amazon self-operated contributions within each group, 1/3/6/12-calendar-month new-product measures, and example ASINs. Products that do not fit a named business group belong to the other/unclassified group.
Use cases
Use structure-profile to inspect one grouping behind the market metrics; call it again with another dimension when needed. Use search for overall metrics and history for changes over time.
Example
Call with {"categoryId":"1045564","includeDescendantCategoryProducts":true,"sampleType":"unitSalesTop100","dimension":"price"}. Read data.dimension="price", data.sampleSkuCount, data.buckets[].skuRate, data.buckets[].revenueRate and data.buckets[].amazonSelfOperatedRevenueRate. The bucket product counts add up to data.sampleSkuCount.
Data range
US only. Buckets describe the selected Top 100 products for the resolved data.date, not all products in the category. Product shares use the actual selected product count; sales and revenue shares use their respective valid totals for that same sample. Shares total 1 when the denominator is positive, subject to rounding. Each bucket returns all four new-product windows so an Agent can compare them without additional calls.
New-product definition
For each bucket newProductMetrics[] item with periodMonths=N, a product is new only when its business launch date is later than data.date minus N calendar months and no later than data.date. The business launch date prefers Amazon Date First Available; when unavailable, it uses the earliest valid SKU first-observed date, SKU first-review date, or parent-product first-review date. Products without a business launch date are not counted as new, but remain in the bucket product-count denominator.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Market lookup date (YYYY-MM-DD); defaults to the latest published snapshot. The response date shows the actual snapshot date. | |
| dimension | Yes | One distribution to return: brand, seller, price, sellerCountry, fulfillment, ratingCount, rating, listingAge, listingYear, or productFeature. | |
| categoryId | Yes | Amazon category node ID to analyze. | |
| sampleType | No | How to select the Top 100 products within the category scope: by estimated monthly unit sales or by estimated monthly revenue. | unitSalesTop100 |
| marketplace | No | Amazon marketplace; currently US only. | US |
| includeDescendantCategoryProducts | No | Whether market metrics include products assigned to descendant category nodes; defaults to true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes on the full burden. It explains the response structure (data.buckets[]), the data range (US only, selected Top 100), the calculations (shares total 1 subject to rounding), and the new-product definition in detail, which is valuable behavioral context beyond what the schema provides.
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, front-loading the core function and example call. It is long but every section provides necessary detail, and the numbering aids skimming. Minor redundancy in example and use cases but not excessive.
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 everything an agent needs: what the tool does, how to call it with a concrete example, what the response contains, the data scope and limitations, and the definition of key terms like new-product metrics. Given the complexity, it's remarkably complete without an output 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 has 100% coverage, so baseline is 3. The description adds extra meaning for the dimension parameter (lists all allowed values) and clarifies the date parameter default behavior, plus the example call shows how parameters combine correctly. This goes beyond just restating 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 returns one selected Top 100 product distribution for a US category market, with a required dimension parameter that selects the grouping. It lists all possible dimensions and distinguishes it from siblings like openapi_v2_markets_search and history, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The use cases section explicitly says to use structure-profile for inspecting one grouping and to use search for overall metrics and history for changes over time. It doesn't explicitly state when not to use it beyond that, but the guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read products by ASIN or parent
Function
Read catalog facts for products you already know, in one of two mutually exclusive modes, both returning the shared Product model. asins mode takes 1 to 50 canonical ASINs and answers in request order; an ASIN missing from the snapshot comes back as status=empty with emptyReason=asin_not_found rather than being dropped. parentAsin mode pages through every product under one parent, ordered by monthlySalesFloor descending (nulls last) then asin. Omit dateRange for the latest daily snapshot or pass 'YYYY-MM' for a month-end snapshot; context.resolvedDate names the snapshot actually read, and is null when the serving index does not record it. No filters and no sort options — this is an exact read. Validation failures return 422 with a stable reason code in the message: asins_or_parent_asin_required, asins_and_parent_asin_exclusive, asin_must_be_normalized, duplicate_asins, asins_limit_exceeded, pagination_not_allowed_in_asins_mode, date_range_invalid. Billing: asins mode charges 1 credit per status=ok item, parentAsin mode 1 credit per request.
Use cases
Use detail to read a known ASIN list — competitors supplied by the user, a watchlist, ASINs returned by another tool — or to enumerate a parent's variants. Use /products/search to discover ASINs by condition, /openapi/v3/realtime/product for live page data instead of the daily snapshot, and /products/history or /products/sales-trend for how a product changed over time.
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[ProductDetailBatch, ProductDetailParentPage]]",
"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 | parentAsin mode only. Default 1. | |
| asins | No | Exact-read mode: 1-50 canonical ASINs (^[A-Z0-9]{10}$), answered in request order. Mutually exclusive with parentAsin. | |
| pageSize | No | parentAsin mode only. Default 20, max 100. | |
| dateRange | No | Omit or 'Nd' (e.g. '30d') for the latest daily snapshot; 'YYYY-MM' for that month's month-end snapshot (earliest 2026-02, latest the most recent completed month). Same rule as /products/search. | |
| parentAsin | No | Parent-member mode: every product whose parentAsin equals this value, paged, ordered by monthlySalesFloor desc (nulls last) then asin. Mutually exclusive with asins. A standalone ASIN is its own parent, so it returns itself. | |
| 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 key behaviors: missing ASINs return status=empty rather than being dropped, ordering for parentAsin mode, snapshot selection via dateRange, resolvedDate behavior, validation failure reason codes, and billing credit rules. It doesn't detail pagination mechanics or the full Product model, but the disclosed behaviors are substantial and specific.
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 clear sections (Function, Use cases) and front-loads the core purpose. It is dense but every sentence adds value, covering modes, edge cases, validation, billing, and alternatives. Slightly long but justified by the tool's 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?
For a read tool with no annotations and no output schema, the description covers the essential operational context: modes, limits, error behavior, billing, and snapshot selection. It doesn't describe the Product model fields, but the output schema is absent and the description names the shared model, which is acceptable for a detail-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?
Schema description coverage is 100%, so the schema already documents all six parameters thoroughly. The description adds context about mutual exclusivity, request ordering, and snapshot 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 opens with a specific verb and resource ('Read products by ASIN or parent') and immediately distinguishes the two mutually exclusive modes. It clearly differentiates from siblings like openapi_v2_products_search, openapi_v2_products_history, and openapi_v3_realtime_product by naming them and their purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 (known ASIN list, watchlist, enumerating parent variants) and when to use alternatives (/products/search for discovery, /openapi/v3/realtime/product for live data, /products/history or /products/sales-trend for changes over time). This 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 a product's day-by-day page history
Function
Return what one ASIN's product page showed on each observation day in a date range of up to 730 days. Per-point series (price, bsr, subBsr, monthlySalesFloor, rating, ratingCount, sellerCount) are aligned with timestamps; change series (title, imageUrl, bestSeller, amazonChoice, newRelease, aPlus, inventoryStatus, bsrCategory, subBsrCategory, parentAsin) record an entry only when the value changes. timestamps are observation days, not a continuous calendar: days can be missing, and a per-point value is not guaranteed to be that day's direct observation, so read the series as a trend. latest holds the parent ASIN, title and image last observed in the window; context echoes the requested window and the observed one. This endpoint is page-observation only — no revenue, growth rates or parent totals. Its monthlySalesFloor is that day's page text, which can differ from the catalog-snapshot value returned by /products/search. aspects trims the response to the listed series. asin must be canonical (^[A-Z0-9]{10}$); lowercase is rejected with 422 asin_must_be_normalized. No observation in the window returns data null. Billing: 1 credit per request.
Use cases
Use history to see how a listing changed day by day — a price move, a badge won or lost, a rank category renamed, a variant moved to another parent. Use /products/sales-trend for monthly sales and revenue on the catalog-snapshot basis, and /products/detail for the product's current facts.
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 | Single ASIN in canonical form: 10 uppercase letters/digits (^[A-Z0-9]{10}$). Lowercase or suffixed values are rejected with asin_must_be_normalized. | |
| aspects | No | Return only these series (response field names); omit for all. timestamps, latest and context are always returned. Empty, unknown or duplicate values are rejected with invalid_aspects. | |
| 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 provided, the description carries the full burden and does so impressively. It discloses per-point vs. change series semantics, non-continuous timestamps, the distinction between page-text monthlySalesFloor and catalog-snapshot values, ASIN normalization rules and the 422 error, null data when no observation exists, and credit billing. This goes far beyond a simple 'get history' statement.
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 deliberately structured into '1. Function' and '2. Use cases', with the core purpose front-loaded. Every sentence earns its place by clarifying behavior, constraints, or alternatives. The organization makes the length appropriate for the endpoint's 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 the lack of a full output schema for the data payload, the description explains the response structure (per-point series, change series, latest, context) well enough. It covers input validation, edge cases (no observation, invalid aspects), billing, and usage context. An agent has everything needed to invoke 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?
Although schema coverage is 100% and the baseline is 3, the description adds substantial meaning beyond the schema. It explains that aspects trims the response to the listed series, that asin must be canonical with the exact regex pattern, that the date range can be up to 730 days, and that marketplace is constrained to US. These details help the agent construct valid calls and interpret errors.
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?
Opens with a specific verb+resource: 'Get a product's day-by-day page history'. The description then precisely scopes it to one ASIN over a date range, and explicitly distinguishes it from sibling tools like /products/sales-trend and /products/detail. There is no ambiguity about what this endpoint does.
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 when to use this tool ('see how a listing changed day by day') and when to use alternatives ('Use /products/sales-trend for monthly sales... Use /products/detail for current facts'). This is exactly the kind of when/when-not guidance that helps an agent choose correctly.
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.
Get a product's monthly sales trend
Function
Return monthly sales and revenue floors for one ASIN and its parent, one point per month, on the same catalog-snapshot basis as /products/search. A finished month (pointKind=monthEnd) comes from that month's last-day snapshot and no longer changes; the current month (monthToDate) follows the latest snapshot and updates daily. Every month in the window has a point, so the series never skips a month. inCatalog=false means the product is not in that month's snapshot and every metric is null; inCatalog=true with a null monthlySalesFloor means it is in the catalog without a sales figure — the two nulls mean different things. Money is USD. The four MoM growth rates compare adjacent month-ends and are computed by the server; they are null for monthToDate points and whenever the previous month is missing, null or not above zero. Data starts at 2026-02; the default window is the latest 12 months but never earlier than that, and a window spans at most 24 months. Billing: 1 credit per request, independent of window length.
Use cases
Use sales-trend to judge whether a product is selling better or worse month over month, and whether the move is the product's own or the whole parent's. Use /products/history for what the page showed on a given day, and /products/detail for the product's current facts.
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[ProductSalesTrend]",
"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 | Single ASIN in canonical form: 10 uppercase letters/digits (^[A-Z0-9]{10}$). Lowercase, spaces or a site suffix are rejected with asin_must_be_normalized. No batch. | |
| endMonth | No | Last month, YYYY-MM. Defaults to the latest month: the month of today (UTC) minus 2 days, so the current month is served from the 3rd. Unlike dateRange on /products/search, the current month is accepted. | |
| startMonth | No | First month, YYYY-MM (earliest 2026-02). Defaults to endMonth minus 11 months (12 points), but never earlier than 2026-02. | |
| 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 excels: it explains point kinds (monthEnd vs monthToDate), the meaning of nulls (inCatalog=false vs null monthlySalesFloor), currency, MoM growth rate conditions, data start date, default window, max window, and billing (1 credit). No contradictions and a rich set of behavioral details.
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 structured into 'Function' and 'Use cases' sections, is front-loaded with the core purpose, and every sentence adds value. It is long but efficient, covering all necessary detail without redundancy.
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, the description covers a comprehensive set of contextual details: data basis, point kinds, null semantics, billing, defaults, use cases, and even an example response. The generic output schema is provided, and the description mentions the key fields (monthlySalesFloor, inCatalog, pointKind). Nothing essential is missing for an agent to call it 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%, and each parameter already has a thorough description (asin format, month defaults, marketplace const). The description adds context about window limits and data start but not parameter-specific semantics beyond what the schema provides. Baseline 3 is appropriate since 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 clearly states the tool's purpose: 'Get a product's monthly sales trend' and details what it returns (monthly sales and revenue floors for one ASIN and its parent). It explicitly distinguishes itself from siblings in the use cases section, naming /products/history and /products/detail and explaining their different purposes, so an agent can immediately tell which tool to use.
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 provides explicit guidance on when to use this tool (to judge month-over-month sales trend) and when to use alternatives (/products/history for daily snapshots, /products/detail for current facts). This is clear, direct, and leaves no ambiguity about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Amazon products
Function
Discover candidate Amazon products by keyword, category and business metrics, returning a paginated list of the shared Product model (max 100 per page). Reads the catalog snapshot: omit dateRange or pass 'Nd' for the latest daily snapshot, or 'YYYY-MM' for that month's month-end snapshot (earliest 2026-02). Filters include price, monthly sales and revenue floors, growth rates, BSR and its 7-day change, rating, seller count, brand and seller lists, badges, fulfillment, package weight in ounces, package size tier, Buy Box seller country, gross margin rate and category scope. Setting any range or list filter excludes products whose value is unknown, so a narrower result set is a coverage effect, not a market finding. categoryScope=includeChildren (default) matches the given category levels and every subcategory; exactOnly requires the product's path to end at the last given level. monthlySalesFloor is the page's 'N+ bought in past month' figure carried forward by the catalog snapshot, a lower bound rather than an estimate. Billing: 1 credit per request.
Use cases
Use search to find products you do not know yet — niche discovery, competitor screening, filtering by margin or growth. Use /products/detail to read ASINs or a parent's variants you already know; it takes no filters. Use /products/competitors for competitor lookup around one ASIN, and /markets/search for category-level demand and competition.
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. No data in the source currently. | |
| lqsMin | No | Minimum Listing Quality Score. No data in the source currently. | |
| 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 |
| bsrGrowthMax | No | Maximum 7-day main-category BSR change (see bsrGrowthMin). | |
| bsrGrowthMin | No | Minimum 7-day main-category BSR change = rank 7 days ago − rank today; positive means the rank improved. bsrGrowthMin=1000 keeps products that moved up at least 1000 places. Negative allowed. About 70.7% of products have a value. Setting this excludes products whose value is unknown — a narrower candidate set, not a market finding. | |
| categoryPath | No | Category hierarchy from root to current level (e.g., ['Electronics', 'Computers', 'Laptops']) | |
| fulfillments | No | Fulfillment filter. Example: ['FBA', 'FBM']. | |
| categoryScope | No | includeChildren (default): categoryPath matches the given levels, so every subcategory is included. exactOnly: the product's category path must end at the last given level. Ignored without categoryPath; exactOnly without categoryPath is rejected with category_scope_requires_category_path. | includeChildren |
| 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. | |
| subBsrGrowthMax | No | Maximum 7-day sub-category BSR change (see subBsrGrowthMin). | |
| subBsrGrowthMin | No | Minimum 7-day sub-category BSR change (rank 7 days ago − rank today; positive = improved). Setting this excludes products whose value is unknown — a narrower candidate set, not a market finding. | |
| 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. | |
| packageSizeTypes | No | Package size tiers (US 2024-25 FBA tiers): smallStandard, largeStandard, largeBulky, extraLarge. Mostly inferred from weight alone (dimensions cover ~2% of products), so a light but long item can be classed smallStandard. About 31.4% of products have a tier. Setting this excludes products whose value is unknown — a narrower candidate set, not a market finding. | |
| packageWeightMax | No | Maximum package weight in ounces (see packageWeightMin). | |
| packageWeightMin | No | Minimum package weight in ounces (page 'Item Weight' converted; same unit as /markets/search). About 31.4% of products have a value. Setting this excludes products whose value is unknown — a narrower candidate set, not a market finding. Populated from the 2026-09-16 snapshot onward; month-end snapshots (dateRange='YYYY-MM') before that have no value. | |
| monthlyRevenueMax | No | Maximum monthly revenue floor. Example: 50000.00. | |
| monthlyRevenueMin | No | Minimum monthly revenue floor. Example: 1000.00. | |
| grossMarginRateMax | No | Maximum gross margin rate, 0-1 (see grossMarginRateMin). | |
| grossMarginRateMin | No | Minimum gross margin rate, 0-1: (price − FBA fee) ÷ price; excludes referral fee and cost of goods. Products with unknown FBA fee are excluded. Setting this excludes products whose value is unknown — a narrower candidate set, not a market finding. Populated from the 2026-09-16 snapshot onward; month-end snapshots (dateRange='YYYY-MM') before that have no value. | |
| 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. | |
| buyBoxSellerCountryCodes | No | Buy Box seller country codes, two uppercase letters each, e.g. ['CN', 'US']. About 88.7% of products have a value. Setting this excludes products whose value is unknown — a narrower candidate set, not a market finding. | |
| monthlyRevenueGrowthRateMax | No | Maximum monthly revenue growth rate as decimal (see monthlyRevenueGrowthRateMin). | |
| monthlyRevenueGrowthRateMin | No | Minimum monthly revenue growth rate as decimal: today's monthlyRevenueFloor vs the same-basis value 30 days earlier, minus 1. About 3.7% of products have a value. Setting this excludes products whose value is unknown — a narrower candidate set, not a market finding. Populated from the 2026-09-16 snapshot onward; month-end snapshots (dateRange='YYYY-MM') before that have no value. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full behavioral burden and does so thoroughly. It discloses that the tool reads a catalog snapshot, charges 1 credit per request, explains that range/list filters exclude unknown values as a coverage effect rather than a market finding, and clarifies that monthlySalesFloor is a lower bound. These are non-obvious behavioral traits an agent would otherwise not know.
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 appropriately structured for a 67-parameter tool: a compact function summary, then use-case routing. It is front-loaded with the most decision-relevant facts and has no filler. Each section earns its place by clarifying scope, semantics, billing, or alternatives.
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 annotations, the description is complete for invocation purposes. It covers what the tool returns, pagination limits, snapshot semantics, billing, filter semantics, caveats, and when to choose sibling tools. The opaque Product model in the response schema is a minor gap, but the agent has enough 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?
Although schema coverage is 100%, the description adds meaning beyond the schema by grouping the 67 filters into semantic categories and explaining cross-cutting behaviors: coverage effects, snapshot date semantics, category scope behavior, package-size inference caveats, and the gross margin formula. It also clarifies how monthlySalesFloor relates to the 'N+ bought in past month' figure, which is not evident from parameter names 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 a specific verb and resource ('Search Amazon products') and immediately states the function: discover candidate products by keyword, category, and business metrics, returning a paginated list. It also names sibling tools like /products/detail and /products/competitors, which distinguishes this search tool from alternative product 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?
Section 2 explicitly states when to use search: to find products you do not know yet, such as niche discovery and competitor screening. It then names the alternatives and their conditions: use products/detail for known ASINs, products/competitors for lookup around one ASIN, and markets/search for category-level demand. This 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 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 Bestsellers V2
Get the current Best Sellers (BSR-ranked) products for an Amazon category.
Data is collected on demand (typically 2-5s latency). Provide either categoryId (Amazon category node id, e.g. 172282) or categoryPath (e.g. ["Electronics"]); page 1 = ranks 1-50, page 2 = 51-100. Discover category ids via /categories. Related: /products/search for daily catalog 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[AmazonRealtimeBestsellers]",
"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 | Bestseller page: 1 = ranks 1-50, 2 = ranks 51-100 | |
| categoryId | No | Amazon category node ID (e.g. 172282); discover via /categories | |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | US |
| categoryPath | No | Category hierarchy from root, e.g. ['Electronics'] |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It usefully notes 'Data is collected on demand (typically 2-5s latency)' and explains pagination, but it does not mention authentication, rate limits, or the behavior when both categoryId and categoryPath are provided.
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 summary is concise, but the description is bloated with large response schemas, including irrelevant ADR-0003 credit-field TODOs and a tokensUsage note about video polls that has no bearing on this endpoint. This extra boilerplate undermines the otherwise tight structure.
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 simple parameter set and absence of a dedicated output schema, the description covers the essential invocation details: parameter alternatives, pagination, latency, and related endpoints. The response schema is included but does not describe the 'data' payload structure, so an agent can call the endpoint correctly but not fully predict the returned product fields.
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 adds value by explaining the either/or relationship between categoryId and categoryPath, giving a concrete example, and referencing /categories for discovery, which is beyond what the schema 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 states a specific action and resource: 'Get the current Best Sellers (BSR-ranked) products for an Amazon category.' It also introduces the key differentiator of real-time/on-demand data and points to /products/search for daily catalog data, helping distinguish it from sibling 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 clearly instructs to provide either categoryId or categoryPath, tells users how to discover category IDs via /categories, and contrasts this endpoint with /products/search for daily catalog data. It lacks an explicit 'when not to use' statement but gives sufficient routing context.
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.
Search a product's reviews
Function
Return individual review texts with their AI-generated tags for one ASIN, page by page (default 10 per page, max 20). The reviews are those of the parent the ASIN belongs to, not only of that child ASIN. Filters: star rating range, verified purchase, Vine program, helpful vote count, review date range and mediaTypes; all filters combine with AND. mediaTypes=['image'] keeps reviews with at least one image — about 8% of stored reviews carry images and reviews added since 2026-08-30 currently carry none, so it mainly matches older reviews; video filtering is not offered, and on this endpoint videos[].url holds the video's cover image rather than a playable address. Tags are returned on each review but cannot be filtered on. Sort by recent, rating or helpfulVoteCount. At most 5000 reviews of a parent are read before filtering, so meta.total can be capped for very large parents. Reviewer identity is not returned. Billing: 1 credit per request.
Use cases
Use search to quote the reviews behind a finding — e.g. the low-star reviews of the month where /voc/trend shows a pain point rising. Use /voc/analysis for the aggregated demand profile and /voc/trend for how it changes over time; both return aggregates only. Use /realtime/reviews for the newest reviews currently shown on the product page.
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 |
| mediaTypes | No | Media filter. The only value is 'image': keep reviews with at least one image. Omitted or empty means no media filter. About 8% of stored reviews carry images, and reviews added since 2026-08-30 currently carry none, so this filter mainly matches older reviews. Video filtering is not offered. | |
| 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?
With no annotations provided, the description carries the full burden and delivers exceptionally: it discloses that reviews belong to the parent ASIN rather than only the child, that all filters combine with AND, the mediaTypes image caveat (8% coverage, none since 2026-08-30), that video filtering is unavailable and videos[].url holds a cover image, that tags cannot be filtered on, the 5000-review pre-filter cap affecting meta.total, that reviewer identity is not returned, and the 1-credit billing cost. This far exceeds what annotations would typically provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but densely informative — every sentence carries operational significance, and it is structured with numbered sections and scannable bullet-like lists, front-loaded with the core function before use cases. Minor redundancy exists where the mediaTypes caveat appears in both the body and the input schema, but the prose earns its place overall.
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 13-parameter tool with no standalone output schema, the description is remarkably complete: it covers pagination defaults and caps, sort fields, all filter semantics, edge cases (parent ASIN, 5000 cap, no-video caveat), cost, and the embedded HTTP response schema documents return shape. An agent has everything needed to invoke it 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: the crucial parent-ASIN review semantics (reviews returned are the parent's, not just the child's), the explicit AND-combination behavior across all filters, the 5000-review read cap that explains why meta.total may be capped, and billing per request. These are value-adds the input schema does not convey, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Search a product's reviews') and immediately narrows the scope: individual review texts with AI-generated tags for one ASIN, page by page. It explicitly differentiates from siblings in section 2, telling the agent that /voc/analysis and /voc/trend return aggregates only and /realtime/reviews returns the newest product-page reviews, so an agent can pick the right tool without inspecting other schemas.
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 gives explicit when-to-use guidance ('quote the reviews behind a finding — e.g. the low-star reviews of the month') and explicit when-not-to-use exclusions with named alternatives (/voc/analysis for aggregated demand profile, /voc/trend for changes over time, /realtime/reviews for newest product-page reviews). Nothing about selection is left to inference.
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. | |
| isAigc | No | Filter by AI-generated-content status. true = only AIGC videos; false = only confirmed non-AIGC (unknown excluded). Omit to return all. Unknown status is not directly filterable — a result with no isAigc field has unknown status. | |
| 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?
Annotations are absent, so the description carries the full burden. It discloses data freshness (daily collection within fallback window), interaction rate calculation, and that filtering by interaction rate does not reduce query time. However, it omits pagination behavior, default sort order, rate limiting, and potential side effects (none, but that's not stated).
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 purpose, filters, and key computation. The inclusion of a response example and extensive output schema in the description text is verbose and unnecessary given the output schema is already provided separately, but the core description is efficient and well-structured.
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 27 parameters, the description covers all key aspects (filter dimensions, data source, computation, alt tools). However, it lacks explicit mention of pagination defaults, maximum page size (already in schema), and does not handle edge cases like empty result sets. But with 100% schema coverage and clear purpose, it's adequately 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%, so the baseline is 3. The description adds context for some parameters (e.g., categoryPath subtree matching semantics) but largely restates what the schema already documents. It adds marginal value 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?
Clearly states it searches daily-updated TikTok videos by engagement, creator, and commerce signals, with a specific verb ('search') and resource ('TikTok videos'). Differentiates from sibling tools by listing concrete filter dimensions and explicitly naming related tools at the end.
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 clear context on when to use the tool (searching videos with specific filters) and explicit alternative tools: 'Related: /tiktok/creators/search and /tiktok/products/search.' However, it does not explicitly state when NOT to use this tool over those alternatives (e.g., when needing creator-only data).
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.
Get the review and demand-tag trend
Function
Return how reviews and demand tags change over time for one ASIN set or one category: one point per week (Monday to Sunday, UTC) or month, each with reviewCount, average rating, rating distribution, sentiment counts and rates, and the count and share of the window's top tags per dimension (default painPoints, scenarios, buyingFactors; topN 1-30, default 10). Same scope and merge rules as /voc/analysis: ASIN mode covers every review of the parents the ASINs belong to (several ASINs of one parent count once; context.resolvedAsins lists the ASINs that took part), and the points' reviewCount sums to /voc/analysis reviewCount for the same window. Tags are chosen by their count over the whole window, so every point reports the same tag set and a missing tag shows count 0. Every period of the window has a point; a period without reviews has reviewCount 0 and null metrics. reviewCount is the number of reviews that were tagged and entered the statistics, not total review volume, and coverage rises year over year — do not read a rising reviewCount as growing review volume. avgRating is computed from tagged reviews only and runs about 0.01 star below the average over all reviews, so a period-to-period change of that size is not a real change; whether sentiment and tag shares carry a similar bias has not been verified. Samples are sparse: most single parents have fewer than 5 tagged reviews in a week or month, so points below lowSampleThreshold carry lowSample=true and context.lowSamplePeriodCount counts them. Window: dateFrom+dateTo, or period (default 6m, resolved like /voc/analysis), widened to whole periods; at most 25 months or 52 weeks, so weekly granularity takes period up to 6m (1y and 2y are rejected with period_limit_exceeded — give explicit dates or use monthly); not before 2024-01-01 (date_before_coverage). Category mode is monthly only. context.snapshotDate is the statistics partition actually read. Aggregates only — no review text and no reviewer identity. Billing: 1 credit per request.
Use cases
Use trend to tell whether a complaint, a usage scenario or sentiment is rising or fading, and whether a burst of low ratings was a one-off. Weekly points are meaningful only for top products or larger ASIN sets. Use /voc/analysis for the full demand profile of one window (all 11 tag dimensions), and /reviews/search with dateStart/dateEnd to read the reviews behind a period. Compare two ASIN sets by calling this endpoint once per 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": {
"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[VocTrend]",
"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 | 'asin' for an ASIN set, 'category' for a category path. Same meaning as on /voc/analysis. | |
| topN | No | Tags returned per dimension (1-30), chosen by their count over the whole window so every point reports the same tag set. | |
| asins | No | ASINs (max 100, required when mode='asin'), each in canonical form ^[A-Z0-9]{10}$ — lowercase, spaces or a site suffix are rejected with asin_must_be_normalized. The trend covers every review of the parents these ASINs belong to, not only these child ASINs; several ASINs of one parent count once. ASINs whose parent cannot be resolved are skipped — see context.resolvedAsins. | |
| dateTo | No | Window end, YYYY-MM-DD; must be given together with dateFrom. It may lie in the future: periods after today are returned as empty points. | |
| period | No | Relative window, default '6m'. Resolved to whole months exactly as /voc/analysis does, so the same period gives both endpoints the same window ('2y' is 25 whole months). With granularity='week' only '1m', '3m' and '6m' fit the 52-week limit; '1y' and '2y' are rejected with period_limit_exceeded. Ignored when dateFrom and dateTo are given. | |
| dateFrom | No | Window start, YYYY-MM-DD; must be given together with dateTo. The window is widened outward to whole periods and may not start before 2024-01-01 (date_before_coverage). | |
| labelTypes | No | Tag dimensions to return, no repeats. Defaults to ['painPoints', 'scenarios', 'buyingFactors']. | |
| granularity | No | One point per week (Monday to Sunday, UTC) or per month. A window holds at most 25 months or 52 weeks, so 'week' works with period up to '6m'; for a longer weekly window give dateFrom/dateTo (max 52 weeks) or use 'month'. Category mode supports 'month' only; 'week' is rejected with granularity_not_supported_for_category. | month |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | US |
| categoryPath | No | Category hierarchy from root, up to 10 levels (required when mode='category'). Example: ['Electronics', 'Computers']. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full behavioral burden and handles it exceptionally. It discloses reviewCount semantics, avgRating bias, sparse-sample lowSample flags, window widening, period granularity limits, coverage-date constraints, aggregation-only output, credit cost, and even unresolved-ASIN 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 description is long but tightly organized under 'Function' and 'Use cases', with critical caveats front-loaded. Every paragraph adds operational or interpretive information that an agent needs, and the structure makes the density navigable.
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 endpoint with 10 parameters and no annotations, the description is unusually complete: it covers scope rules, semantics of returned values, edge cases, error conditions, limitations, billing, and alternatives. An agent has enough guidance to choose, invoke, and interpret 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?
Although schema description coverage is 100%, the prose adds substantial meaning beyond the schema: topN tags are chosen over the whole window so the tag set is consistent across points, ASIN mode expands to parent reviews, dateFrom/dateTo must be given together, granularity limits interact with period choices, and category mode supports month only. This significantly reduces ambiguity.
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 the review and demand-tag trend," then clarifies exactly what is returned (weekly/monthly points with reviewCount, rating, sentiment, and tag shares). It also distinguishes itself from the sibling /voc/analysis and from /reviews/search by positioning the tool as the time-trend counterpart.
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, when to use /voc/analysis for the full demand profile, and when to use /reviews/search to read underlying reviews. It also gives practical constraints such as weekly points being meaningful only for top products or larger ASIN sets, and notes that comparing two ASIN sets requires one call per set.
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.