Easyparser — Amazon Product & Seller Data

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: that the call is free, hits the Account API, consumes no credits, and requires an API key. It does not cover rate-limit behavior of the call itself, but the added cost/auth facts are meaningful.

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?

Two sentences, front-loaded with the returned data and then the usage triggers, with the free/no-credit fact highlighted. Every clause adds actionable information and there is no filler.

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?

An output schema exists, so the description need not explain the return structure, and it instead spends its budget on cost, auth, and routing guidance. For a zero-parameter read-only account query this is fully sufficient to invoke correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. It correctly implies no input is required beyond authentication.

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 (check) plus the exact resource (Easyparser account) and enumerates what is returned: plan, credit balance, reset date, rate limits, daily usage by operation. No sibling tool covers account/quota data, so it is unambiguously distinguishable from the product/seller/bulk 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?

Gives explicit when-to-use triggers: before expensive multi-page or 12-month-history jobs, when the user asks about quota or plan, and for usage-pattern analysis with a concrete example question. This is a pre-flight/cost-control call and the description makes that role plain.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful behavior beyond them: a credit cost ('Costs 1 credit') and the interpretation rule that a lower rank number means higher sales velocity, which is domain semantics the annotations cannot convey. It stops short of describing the rank's scope caveats (e.g. category-level granularity limits) or response latency.

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?

Front-loaded with what the tool returns, then usage triggers, then the alternative-routing rule, then cost. Four short sentences with no filler or repetition of 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?

With an output schema present, the return shape need not be restated, and the description correctly focuses on scope, routing, and cost. For a 2-parameter single-purpose read tool with full annotation coverage, an agent has everything needed 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%: the asin pattern, URL derivation hint, and domain enum with marketplace guidance are all documented in the schema itself. The description adds no parameter-level syntax or format detail beyond that, so the baseline 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?

States a specific verb and resource ('Get a product's current Best Sellers Rank (BSR)') and immediately clarifies the payload: numerical rank plus sub-category node identifiers. It explicitly differentiates itself from get_product_detail and get_sales_history, so an agent can route without opening any 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 concrete when-to-use triggers ('Is this product selling well?', daily rank monitoring) and names two alternatives with the exact condition that selects each: get_product_detail when price/rating/content are also needed, get_sales_history for historical trends. Nothing 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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial non-annotation context: a hard 24-hour retention window after job completion, the expiry failure mode and its recovery path, and the fact that calls are free of per-call credits. These are exactly the operational traits an agent needs before calling.

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?

Front-loaded with the core action, then routing guidance, then the retention caveat — a sensible priority order. Slightly padded by the 'same data shown in the item result modal on the Bulk Requests page' aside, which is contextual rather than essential, but nothing is actively wasteful.

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?

With an output schema present the description need not explain return values, and it correctly focuses on the gaps structured fields cannot cover: sequencing, the 24-hour expiry, and the recovery alternative. An agent has everything required to call 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?

Schema description coverage is 100% and the sole item_id parameter is already documented in the schema, including where to obtain it and its alias as a Data Service query ID. The description adds no new syntactic or format detail about item_id, so the 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?

States a specific verb+resource: 'Fetch the parsed result data of a single bulk job item', and immediately clarifies what that data actually is (product detail, search results, seller profile). It clearly differentiates itself from get_bulk_job_items by contrasting 'the DATA behind a specific item' with 'just its 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?

Gives an explicit precondition ('Use this tool after get_bulk_job_items, when the user wants to see the DATA...not just its status') and a full sequenced workflow: list_bulk_jobs → get_bulk_job_items → get_bulk_item_result. It also handles the negative case by telling the agent what to do when data has expired (re-run via get_product_detail).

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false), but the description adds real behavioral context: monitoring endpoints consume no per-call credits, and each item's item_id can be chained to GET /v1/queries/{id} for the parsed result. It does not discuss pagination limits or job-completeness caveats, but the additions are meaningful.

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?

Three short paragraphs with the core purpose front-loaded, then usage, then cost/next-step. Efficient overall, though the status-filter guidance and search_key explanation duplicate what the schema descriptions already say, costing some 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?

Complete for an 8-parameter read-only inspection tool: it covers why to call it, how to narrow results, what each item contains, that it is free, and how to escalate to a sibling endpoint for the parsed result. An output schema exists, so return-shape explanation is correctly omitted.

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 every parameter, including the status filter guidance and search_key purpose. The description's parameter-related statements largely restate the schema rather than adding syntax, defaults, or format details. Baseline 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?

States a specific verb and resource ('Inspect the individual items inside a bulk job') and enumerates what an item contains (input value, status, error message, credit cost, completion time). This is clearly distinguishable from siblings like list_bulk_jobs (job-level) and get_bulk_item_result (parsed result).

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 an explicit trigger ('after list_bulk_jobs shows failed_items or invalid_items > 0'), the exact filter recipe ('status="failed" or status="invalid"'), and a secondary use case (search_key to locate one ASIN in a large job). It also routes the agent onward to the Data Service with the item_id.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context not in the annotations: it is a read-only diagnostic over delivery records and is free of per-call credits, which matters for a log-scanning tool.

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

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

Front-loaded with purpose, then the trigger case, then scoping and cost. Two tight paragraphs with no filler; the colloquial 'job finished but my integration didn't fire' phrasing is slightly colorful but aids recognition of the debugging scenario.

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?

An output schema exists so return values need no explanation, and annotations carry the safety profile. Trigger, scoping, data source, and cost are all covered, leaving only minor gaps like pagination expectations for a 9-parameter list 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?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-tool provenance the schema lacks — that group_id comes from list_bulk_jobs and that omitting it broadens the scan to all jobs. That provenance/routing detail is real value beyond the schema's per-parameter text.

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 ('Check webhook delivery logs for bulk jobs') and enumerates the payload the agent will get back (delivery status, timestamps, whether the callback fired). The diagnostic framing plus the group_id/bulk_request_id filters distinguish it from siblings like get_error_logs and list_bulk_jobs.

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 an explicit trigger scenario ('when a job shows as completed but the user's system never received the webhook') and concrete scoping guidance: use group_id for one job (sourced from list_bulk_jobs) or omit it to scan all jobs. This routes the agent without inference, though it stops short of naming an explicit when-not case.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description still adds real value beyond them: rows carry request_id and query_params for tracing the failing input, and monitoring endpoints consume no per-call credits — a non-obvious operational trait. Pagination/retention behavior is left unstated.

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?

Three short paragraphs, front-loaded with the what-and-scope before the when-to-use and the cost note. Each paragraph earns its place, though the third (credits) is a single-purpose sentence that could be folded into the opening to tighten the whole.

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?

With an output schema present, the description needn't explain return shapes, and it doesn't try. Combined with full annotation coverage and 11 fully documented optional parameters, an agent has everything needed: what it returns, which filters matter, why to reach for it, and the credit implications.

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

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

Schema description coverage is 100%, so every parameter (including the enum semantics for error_channel and operation and the 'Omit for both' behavior) is already documented in the schema. The description reinforces error_channel, error_code, operation, and domain as the useful filters but adds no syntax, format, or default behavior beyond that. Baseline 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 names a specific verb+resource ('List the user's API request error logs') and pins down scope: both real-time API errors and bulk job errors, with the row fields enumerated. It also maps the tool to a concrete surface ('the Errors page of the Easyparser web app'), so an agent can distinguish it from monitoring siblings at a glance.

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 explicit triggering conditions with realistic user phrasings ('why are my requests failing?', 'any webhook errors today?') and names the filters to apply. What's missing is an explicit boundary against the closest sibling, get_bulk_webhook_logs, which an agent could plausibly confuse with the BULK channel of this tool.

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

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

Annotations already establish readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it costs 1 credit and is the only tool returning structured fee category plus exact measurements. It does not mention rate limits or auth, but those are minor omissions given the annotation coverage.

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

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

Front-loads what the tool returns, then when to use it, then the sibling comparison and cost. Every sentence contributes to selection or invocation, and the one-credit note is placed after routing guidance without disrupting flow. No filler or repetition.

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?

An output schema exists, so return values need not be described. Annotations cover the safety profile, and the description supplies when-to-use, explicit sibling differentiation, and cost. Together these are sufficient 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%, and the schema fully documents asin with pattern and domain with enum/default. The description adds no parameter syntax, selection, or format details beyond what the schema already provides. Baseline 3 is appropriate when the schema carries parameter 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?

Names a specific verb ('Get') and resource ('package dimensions'), enumerates height, width, length, weight, and Amazon fee category, and positions itself as the FBA fee-estimation and shipping-cost tool. It explicitly distinguishes itself from get_product_detail by noting that only this tool returns structured fee category and exact measurements. An agent can identify its role without opening sibling 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?

States exactly when to use it: shipping, storage, FBA fees, or warehouse planning. It also states when not to use it (general product info) and names get_product_detail as the alternative for that case. The one-credit cost is included to support selection decisions.

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

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

Annotations declare readOnly/openWorld/non-destructive, and the description adds economics the structured data does not contain: 1 credit per call, +1 credit for a_plus_content, and the hard constraint that exactly one of identifier or url must be supplied. That credit cost and the mutual-exclusion rule are the practical behavioral facts an agent needs before calling.

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?

Front-loaded with the payoff ('Fetch complete, structured information about a single Amazon product'), then routing, then constraints and costs. The long field enumeration is dense but information-bearing, and the alternative-routing sentences are one clause each with no filler.

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?

An output schema exists so return values need no explanation, and the surrounding gaps are covered: sibling disambiguation, identifier mutual exclusivity, credit cost, and the opt-in cost of a_plus_content. Nothing an agent needs in order to call this correctly 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 parameter docs already carry the semantics; the baseline is 3. The description goes beyond it by stating the either/or exclusivity between asin and url and by giving a negative condition for a_plus_content, which is decision guidance the schema does not contain.

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?

Names a specific verb (Fetch) and resource (single Amazon product) and enumerates the returned payload — title, brand, Buy Box price, BSR, variants, etc. It also explicitly distinguishes itself from get_product_offers, get_bestseller_rank, and get_package_dimensions, so an agent can route without opening any 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?

The second and third paragraphs are pure routing guidance: 'use this when you need a full product profile' plus three named alternatives each with the narrower condition that selects them ('only need competing seller prices', 'only need sales rank', 'only need shipping dimensions or FBA fee category'). It also states when to enable a_plus_content ('only when the user explicitly asks').

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral facts not in the structured data: a per-page credit cost, a hard 5-page cap implication, and the fact that the Buy Box winner is returned. It stops short of describing error/empty-result behavior or rate limits, so it is strong rather than 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?

Front-loaded with the core purpose and payload contents, then usage, then cost guidance — a logical ordering with no filler. Minor redundancy in restating what the return contains against an existing output schema keeps it from being maximally tight.

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?

An output schema exists so return values need not be re-explained, and all 7 parameters are fully documented in the schema. The description supplies the remaining decision-relevant context: sibling selection, marketplace constraint, and the credit-cost tradeoff for pagination.

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%, including patterns, enums, defaults and the ASIN format, so the schema does the heavy lifting and 3 is the baseline. The description only adds strategic advice about condition and shipping filters (cheaper than paginating) rather than semantics beyond the schema's own enum and description text.

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 (fetch seller offers for an Amazon product) and enumerates exactly what the payload contains: merchant, price, shipping, condition, fulfillment type, seller rating, plus the Buy Box winner. It explicitly contrasts itself with the sibling get_product_detail, so an agent can route 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 an explicit when-to-use rule ('when the question is about WHO sells the product and at WHAT price'), names the alternative (get_product_detail) for the contrasting case, and adds cost-driven tactics: start with one page, prefer condition/shipping filters over pagination because it is cheaper.

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

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

Despite readOnlyHint/destructiveHint annotations already marking this as a safe read, the description goes far beyond them: it discloses the credit cost model (5 base + 1 per month with worked examples), the weekly aggregation granularity of the response, and an instruction to ask the user or default to 3 months. These are material behavioral traits not derivable from annotations or 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?

Well-organized with a purpose sentence, usage section, and a clearly flagged 'IMPORTANT cost rule.' Front-loaded with what it does. Slightly repetitive — the weekly aggregation point appears twice and the credit formula is stated in two places — but the redundancy is deliberate emphasis, not filler.

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 paid, read-only, time-series retrieval tool with an output schema and full param coverage, the description covers everything an agent needs: scope, cost, granularity, when to prefer a sibling, and default behavior. Nothing required to invoke it correctly 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 coverage is 100%, so baseline is 3, but the description adds value beyond it by giving the cost implication of history_range (worked credit examples) and the default guidance ('default to 3 months for a quick trend read'). It reinforces that the history array is weekly, not daily. Minor deduction because enum semantics themselves are already fully documented in the schema.

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

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

The description states a specific verb and resource ('Retrieve a product's historical performance over up to 12 months: weekly aggregated trends for views, sales, price, and BSR') and clearly distinguishes itself from siblings by naming get_product_detail as the cheaper alternative. An agent can tell exactly what this returns without opening the 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?

It provides explicit when-to-use cases (trend forecasting, seasonality, conversion-rate estimation, due diligence) and an explicit when-not-to-use rule ('Do NOT use it for a simple current price check — get_product_detail is 5x cheaper'), including a cost comparison to guide the choice. This is textbook routing guidance.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), so the bar is lower; the description still adds meaningful non-annotation context: 1 credit per page, a 5-page cap, and the max_rating=3 trick to surface negative feedback without paging. It stops short of describing pagination semantics or auth requirements, hence not 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?

Well front-loaded: purpose first, then when-to-use, then cost/practical tip. Each paragraph is short and earns its place, though 'This is the reputation deep-dive tool' is mildly redundant marketing filler.

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?

With an output schema present, the description needn't explain return values, and it still names the returned fields. Annotations cover safety, all 7 parameters are documented, cost is disclosed, and the sibling routing is explicit — nothing an agent needs to invoke it correctly 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 coverage is 100%, so baseline is 3, but the description goes beyond the schema by explaining the practical intent of max_rating ('set max_rating to 3 instead of paging through everything') and tying rating/time filters to a goal. The other parameters (domain, page bounds, history_range) get no added meaning 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?

States a specific verb (Read) and resource (individual buyer feedback entries for an Amazon seller), enumerates the returned fields (star ratings, comment text, dates), and explicitly contrasts itself with the get_seller_profile sibling. An agent can distinguish it from get_seller_profile and get_seller_products without opening a 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 when-to-use conditions (reading actual buyer comments, analyzing complaint patterns, auditing service quality) and names the alternative (get_seller_profile) with the exact condition that selects it (aggregate 30/90/365-day scores without comments) plus a cost rationale.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, openWorld), and the description adds real operational context the annotations lack: per-page credit cost, a 5-page cap, and the payload-reducing effect of exclude_refinements. It stops short of describing response structure or failure modes, so it is strong 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?

Three tight paragraphs: catalog contents first, then usage and routing, then cost/sort/exclusivity mechanics. Every sentence carries actionable information and the most decision-relevant facts are 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?

With an output schema present, return values need not be explained, and the description correctly limits itself to what the structured fields do not cover: cost per page, pagination cap, sort semantics, and input exclusivity. Nothing needed to invoke the tool correctly 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 schema already carries the parameter definitions (baseline 3). The description goes beyond it by supplying a concrete sort_by value with its effect ('exact-aware-popularity-rank' for best sellers first) and by stating the seller_id/url exclusivity constraint that the schema itself does not encode.

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 ('Extract a seller's full product catalog') and enumerates the returned fields (ASIN, brand, category, price, Prime status, variant counts, rating data). It explicitly names the sibling it is not — get_seller_profile — so an agent can route 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?

Names three concrete use cases (competitor inventory analysis, stock monitoring, pricing-strategy research) and an explicit exclusion with the alternative: 'If you need the seller's legal identity or reputation instead of their products, use get_seller_profile.' It also gives the mutual-exclusion rule 'Provide EITHER seller_id OR url — never both.'

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint=false, so the safety profile is covered structurally. The description adds genuinely non-inferable behavior: a 1-credit cost, and the constraint that it unmask a legal entity (emphasis on data sensitivity/privacy). It stops short of noting rate limits or what happens when a seller_id is invalid.

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?

Front-loaded with the capability, then triggers, then sibling routing, then the parameter constraint and cost. Every sentence carries distinct information; nothing is restated from the schema or annotations.

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?

With an output schema present, return-value detail is unnecessary, and the description instead covers the things an agent actually needs to decide and invoke: when to choose it, what it returns at a high level, acceptable inputs, discovery path, and cost.

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 exceeds that by adding the mutual-exclusion rule 'Provide EITHER seller_id OR url — never both', which the JSON schema does not encode (no oneOf/anyOf), plus the hint that seller_id can be discovered from get_product_offers.

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 names a specific verb and resource ('Unmask the legal identity and reputation of any Amazon merchant') and enumerates the exact payload: legal business name, registered address, and 30/90/365-day plus lifetime feedback trends. It self-labels as 'the supplier-verification and brand-protection tool', which instantly separates it from the product- and review-oriented siblings.

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

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

It gives literal trigger phrasings ('who is this seller?', 'is this merchant legitimate?'), states the compliance/invoicing context, and explicitly routes elsewhere for adjacent needs ('To see WHAT the seller sells, use get_seller_products. To read individual buyer reviews... use get_seller_feedback'). It even documents the discovery path via get_product_offers.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so safety is covered. The description adds non-obvious behavioral facts: it reads web-app jobs too, it is free of per-call credits (rate/cost behavior), and it explains each status including partial_success semantics ('some items failed or were dropped'). It doesn't detail pagination behavior, which keeps it from 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?

Front-loads the core purpose in the first clause, then usage, routing, status legend, and cost note in a logical order. Every sentence (status definitions, credit note, sibling routing) carries information an agent needs; nothing is padding.

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-param read-only list tool with an output schema and 100% schema coverage, this is complete: purpose, when to use, sibling routing, status semantics, and cost behavior are all covered, with the output schema handling return shape.

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

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

Schema coverage is 100%, so baseline is 3. The description compensates for the implicit filter semantics by describing statuses in prose (pending=queued, processing=running, partial_success=partial) and referencing group_id as a drill-down key, adding meaning beyond the enum labels. Pagination/page-limit syntax is left to 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?

States a specific verb (list), resource (bulk extraction jobs), and the exact fields returned (operation, domain, status, counts, timestamps). It also distinguishes itself from sibling listers by noting it reads the same data as the web UI, so it covers app-started jobs — something no sibling (get_bulk_job_items, get_bulk_webhook_logs) 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?

Explicitly names when to use it with real user phrasings ('is my job done?', 'what bulk jobs are running?') and routes to siblings: pass group_id to get_bulk_job_items or get_bulk_webhook_logs. That is explicit when-to-use plus named alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: it works WITHOUT an API key (an auth prerequisite the annotations cannot express) and it returns credit costs and marketplace domains. It does not discuss rate limits or response size, but the no-key note is the important one.

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?

Two tight sentences plus a short final clause. The discovery purpose and the no-API-key fact are front-loaded; nothing is padded or repeated from 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?

An output schema exists, so return-value detail is unnecessary. The description covers the discovery role, the auth-free invocation, and the extra marketplace-domain output — everything an agent needs to decide to call it first. No meaningful gap remains.

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% and the single optional 'operation' enum parameter is fully documented in the schema, including that it returns a single usage guide instead of the whole catalog. The description alludes to 'their parameters, credit costs, and example use cases' but never mentions the operation filter, so it adds nothing beyond the schema. Baseline 3.

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

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

States a specific verb and resource: list all Easyparser operations with their parameters, credit costs, and example use cases. It is clearly distinguishable from every sibling (which are per-operation data tools) because it describes itself as the catalog/discovery endpoint. The extra disclosure of marketplace domains further pins down 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?

Gives explicit when-to-use conditions: 'call this first to understand what the server can do' and 'when you are unsure which tool fits the user's question'. This is precisely the routing guidance an agent needs to pick this meta-tool over the 16 operation-specific siblings.

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

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

Annotations already declare this a safe, open-world read, so the description's job is to add context beyond that — and it does, disclosing the 1-credit cost and the failure mode ('guessing the wrong type returns no results'). It does not discuss rate limits or latency, and return shape is covered by the output schema, so it stops just short of full disclosure.

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 purpose sentence is front-loaded and each subsequent block (workflow, precondition, alternative, cost) earns its place. It is slightly long and would read faster as a tighter bulleted block, but there is no redundant filler.

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 3-parameter read tool with full schema coverage, an output schema, and annotations covering the safety profile, everything an agent needs is present: what it does, when to use it, the sibling to use instead, the type-matching requirement, and the credit cost.

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 enum descriptions already define each type. The description still adds decision-relevant semantics above the schema: concrete digit-length heuristics (UPC 12, EAN/GTIN 13, ISBN 10 or 13) and the behavioural consequence of mismatching the type.

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 transformation ('Convert an external product identifier ... into the corresponding Amazon ASIN') and enumerates the accepted code families. It also explicitly contrasts itself with the sibling search_products, so an agent can route correctly 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 when-to-use ('user has a barcode or standard product code and wants to find the matching Amazon listing'), sample workflows, and a clear when-not/alternative rule ('If the user gives a keyword instead of a code, use search_products instead'). It also flags the hard precondition that identifier_type must match the code.

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

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

Annotations cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds operational context the annotations cannot: 1 credit per page, typical 20-40 results per page, and the recommendation to use sort_by/exclude_sponsored rather than paging further. It also discloses the two-step refinements discovery workflow (read the refinements field first, then pass IDs).

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?

Front-loaded with the action and return shape, then usage boundaries, then cost/efficiency guidance. Every sentence carries operational value with no filler or restatement of the name.

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?

With an output schema present and annotations covering safety, the description still supplies the non-obvious details an agent needs: credit cost, result volume, the refinements discovery dependency, and the ASIN/URL fallback. Nothing material is missing for correct invocation.

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 10 parameters and the baseline is 3. The description goes beyond by explaining the refinements usage pattern ('first run one search and read the refinements field ... then pass them in refinements') and steering toward exclude_sponsored and sort_by, adding practical meaning not present in the schema.

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

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

Specific verb (search) and resource (Amazon product listings by keyword or URL), and it enumerates exactly what is returned: ASIN, title, price, rating, review count, Prime status, badges, and refinement filters. It also explicitly names the sibling it is not (get_product_detail) and the condition that selects it.

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?

States when to use it (market research, keyword analysis, product discovery) and when not to ('If the user already has an ASIN or product URL, do NOT search — use get_product_detail directly'). It routes the agent to the correct alternative with an explicit condition.

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