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

Annotations only declare readOnly/openWorld; the description adds substantial context beyond that: per-platform parameter support, unit consumption ranges (1 unit vs 1–2 units for amazon), and billing behavior ('a call that fails is not billed'). Those cost and pagination traits materially affect call planning and are not in any structured field.

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 the platform table is dense with zero filler; pagination and billing are one line each. The opening sentence is a fragment and the block-list format is slightly telegraphic, but no line is wasted.

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 a nested free-form params object, multi-platform dispatch, and no output schema, the description covers what's needed to construct a valid call: id source, per-platform params, paging, and cost. It stops short of describing the shape of returned product records, though that is partly inferable from the 'products' framing.

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 is effectively a free-form params bag with additionalProperties: {}, so the description must define the real parameters — and it does, enumerating each platform's accepted params with * marking required ones (categoryId*) and noting optional fields like currency, facets, sort. Without this text the tool would be uncallable.

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 the specific resource and scope ('The products in one category, with no keyword'), which immediately separates it from the keyword-based search_products sibling. The title supplies the verb, and the description pins down the retrieval semantics.

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 prerequisite route ('Get category ids from list_categories') and pagination instructions ('For the next page pass params.page = 2, 3, …'). The 'no keyword' phrasing implies the alternative is a keyword search, but it never names search_products as the when-to-use-this-instead sibling.

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 openWorldHint=true, so the safety profile is known. The description adds a platform-operation catalog and fallback usage, but does not disclose response format, rate limits, auth requirements, or error behavior for direct API calls.

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 sentence front-loads the tool's role, and the platform-operation list is structured and scannable. The list is long but serves as a necessary operation reference absent from schema enums; it could be trimmed if list_platforms already returns the same catalog.

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 generic open-world dispatcher with no output schema, the description covers platform/operation selection and where to find params. It still leaves return values, error handling, and operation-specific behavior unaddressed, which an agent may need before invoking.

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 platform, operation, and params are already documented. The description adds meaningful semantics by enumerating valid operation names per platform and pointing to list_platforms for operation-specific parameters, compensating for the lack of enums.

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 ('Call any operation of the apinoa API directly') and frames the tool as an escape hatch for operations not covered by dedicated tools, with examples such as store catalogs, shipping quotes, and LinkedIn jobs. However, it then lists operations that overlap with siblings like search_products and get_product, so sibling differentiation is not fully 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 says to use this for what the other tools do not cover and points to list_platforms for operation parameters. It does not explicitly say to prefer dedicated tools for overlapping operations or name which siblings cover which listed operations.

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 read-only and open-world behavior, and the description goes well beyond them: it discloses the billing model (units of $0.001 at list price), that failed calls are not billed, and that cost varies by platform with a per-call unit range (aliexpress 1–2, amazon 2–32, others 1). That is exactly the operational context an agent needs before spending money on a call.

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?

Purpose is front-loaded in one line, followed by a compact per-platform list and a closing cost note. Every element carries load — no restated title, no filler — and the hierarchical form is easy to scan before a call.

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 no output schema, the description compensates by naming the returned fields (variants, images, specifications, seller, delivery, price). Combined with full per-platform parameter guidance and the cost model, there is nothing material an agent needs in order to invoke this correctly that 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%, but the schema's `params` property is a bare `additionalProperties: {}` bag; the description is what actually tells the agent which keys are valid on which platform (currency/include/language/region per platform) and which are mandatory. It also clarifies the id-vs-top-level relationship that the schema leaves implicit.

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 precise scope statement — 'One product in full' — and enumerates exactly what the record contains (variants, images, specifications, seller, delivery, price). That framing alone separates it from the sibling search_products/search_products_by_image tools, which return collections rather than a single hydrated record.

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 concrete call context: the accepted platform set, which parameters each platform takes, which are required (marked with *), and that id may be supplied at the top level. What it doesn't do is state exclusions or route the agent — e.g. it never says 'search first to obtain an id' or that an invalid id on one platform can't be resolved via another.

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 and openWorldHint, and the description adds real substance on top: per-platform unit ranges, that costs are billed in $0.001 list-price units, and that a failed call is not billed. Pagination continuation behavior is also disclosed. Auth requirements and error shapes are the main remaining 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?

Front-loaded one-line purpose, then a compact per-platform table, then a pagination rule and a billing note. Every line is load-bearing, with no restatement of the tool name or boilerplate.

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 no output schema, the description must imply the return shape, and it only hints that the response indicates which of page/cursor to use next. Nothing is said about what a review record contains or when pagination ends (absence of cursor/page), which is the one thing an agent looping over pages would want.

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 nominally 100%, but the critical 'params' property is a free-form object with additionalProperties: {} and no documented members, so the description carries real weight by enumerating exactly which keys each platform accepts and which are required (id*, page, cursor) and that id may be supplied at the top level. This is meaningfully beyond what the structured schema conveys.

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 lead sentence names a specific resource (a product's reviews) and its scope (one page at a time), which is immediately actionable. It implicitly separates itself from get_product by focusing on reviews, but no sibling is named explicitly, so an agent must infer that get_product is the right call for the product itself.

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 per-platform parameter table and the explicit pagination rule ('pass params.page or params.cursor as the previous answer indicates') give concrete context for how to call it repeatedly. What is missing is any when-not guidance or reference to alternatives such as search_products, so the agent gets usage mechanics but not tool selection criteria.

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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses billing semantics ('units of $0.001 at list price; a call that fails is not billed') and per-platform unit costs, which is genuinely useful context an agent can't get from annotations. It stops short of describing return shape or rate limits.

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

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

Front-loaded purpose sentence, then a compact per-platform table, then pagination and cost notes. Every line carries actionable information 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?

With 100% schema coverage and no output schema, the description covers invocation for all six platforms, pagination, and cost. The notable gap is that it never characterizes the returned comment data, which for a read tool would help an agent 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?

The schema defines params as a free-form additionalProperties object, so without the description an agent would have no idea what keys are legal. The description enumerates the exact accepted param names per platform and flags required ones with '*', adding substantial 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?

The description names the resource (comments) and distinguishes three retrieval modes keyed to parameters: post comments, a comment's replies, or an account's comments. It is clearly distinct from siblings like get_social_post or list_social_posts, though it never explicitly contrasts with them.

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

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

It explicitly tells the agent how to select each mode (params.post vs params.comment vs username) and how to paginate ('call again with params = { cursor } alone'). What's missing is any statement of when to prefer this over sibling tools or 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.

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

Annotations already mark this as read-only and open-world, and the description adds useful operational context: per-platform unit costs and the fact that failed calls are not billed. It does not cover authentication or rate-limit behavior, but that is a smaller gap given the annotations.

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?

It is front-loaded with the core outcome, then uses compact platform bullets for the variable parameter surface, followed by a brief cost note. The structure is efficient and every section serves a clear purpose.

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-only single-post lookup with no output schema, the description provides enough about return fields, platform parameters, and cost. It could be strengthened by explicitly distinguishing itself from the social-profile, comments, and list tools.

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 already 100%, so the baseline is 3. The description adds meaningful platform-specific detail by listing the accepted parameter names for each platform and clarifying that id may be supplied at the top level.

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 opening phrase 'One post: text, author, media, counts, time' establishes that this retrieves a single social post and previews its contents. It is clearly narrower than sibling list_social_posts, though it does not 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 platform bullets make clear that an id and platform determine usage, and the cost note helps decide whether to call it. However, there is no explicit when-to-use guidance versus get_social_profile, list_social_posts, or get_social_comments.

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 openWorldHint=true, so the safety profile is covered. The description adds genuinely non-derivable behavior: unit costs per platform, list-price conversion ($0.001 per unit), and the important billing rule that failed calls are not charged. It doesn't describe error modes or rate limits, 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?

Purpose sentence first, then a compact per-platform matrix with required-flag legend and cost note — high information density with no filler. The asterisk legend and unit ranges are terse but decodable in one read.

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?

No output schema exists, and the opening sentence covers the return shape well enough for selection. For a 3-param nested-schema read tool the description supplies the missing per-platform parameter contract and billing behavior. Remaining gap is the unexplained meaning of 'include' and 'userId' within the params bag.

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 would be 3, but the schema's 'params' object is an untyped additionalProperties bag — the description is the only place that names the valid per-platform keys (username, include, userId) and their required/optional status. It also clarifies that username may be passed at the top level rather than nested. Small gap: the semantics of 'include' and 'userId' are never explained.

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 resource definition — 'One account on a social platform' — and enumerates the returned fields (name, bio, followers, verification, links), which is more than the title conveys. It implicitly separates this from post-oriented siblings like get_social_post and list_social_posts by focusing on the profile entity, but never names those siblings 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?

The platform/param matrix tells the agent exactly what each platform accepts, which is practical usage guidance, but there is no statement of when to choose this over get_social_post or list_social_posts, and no prerequisites or exclusions are given. Usage is implied by the platform enumeration rather than argued.

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?

With readOnlyHint and openWorldHint already declared, the description adds useful behavior beyond the annotations: this is a one-level category read, ids feed browse_category, costs are in $0.001 units, and failed calls are not billed. It does not describe return fields or pagination, but the safety profile is already covered by annotations.

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 purpose and usage, then presents platform-specific parameter support and cost behavior compactly. Every section helps the caller decide and invoke the tool; there is no redundant 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?

For a read-only, open-world listing tool with no output schema, the description covers invocation sufficiently: platform selection, categoryId semantics, accepted platform parameters, and billing behavior. It lacks return-shape details such as category fields or pagination, which are the main remaining gap.

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 has high coverage for top-level parameters, but params is a generic additionalProperties object; the description compensates by listing which parameters each platform accepts and by explaining categoryId omission versus child retrieval. It still leaves region values/types and some requiredness details implicit, and the '* = required' note is not clearly reflected in the listed 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 states a specific resource and scope: one level of a marketplace's category tree, with top-level versus child behavior controlled by categoryId. It also distinguishes the output's role from browse_category by saying the ids feed that sibling, so an agent can identify 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?

It gives clear invocation guidance: omit params.categoryId for the top level and pass an id to get children. It also names browse_category as the downstream consumer, but it does not explicitly state when to choose browse_category instead or whether list_platforms should be called first.

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?

The description provides crucial, non-structural behavioral constraints: it is 'Free' and requires 'no key'. This significantly aids an agent by defining its operational cost and authentication requirements.

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

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

The description packs a large amount of high-value information (scope, content, cost, authentication) into a single sentence without becoming overly verbose or tangential.

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 discovery tool that lists broad, foundational data (platforms), providing the scope, contents (operations, costs), and access requirements (free/no key) makes it contextually 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%, meaning the parameter 'platform' is fully detailed in the schema. The description does not add substantial meaning beyond what the input schema already provides, maintaining the baseline score.

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 primary goal is to list every platform apinoa serves and details related to its operations. It distinguishes itself as a broad discovery tool among the available search and get-product 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?

Usage is implied for discovery (e.g., before using a specific API call), but the description does not explicitly state 'when' to use it versus other listing tools, offering only an implicit use 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?

Beyond the readOnlyHint and openWorldHint annotations, the description adds meaningful behavioral detail: per-platform unit costs, the fact that failed calls are not billed, and exact cursor-based pagination behavior. These are operational traits an agent could not infer from the annotations alone.

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 dense but well structured: it front-loads the purpose and source-selection rule, then provides a compact platform matrix, followed by pagination and cost notes. Every section contributes directly to correct 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?

For a complex, nested, multi-platform list tool, the description covers platform selection, allowed params per platform, pagination, and billing. It does not describe the shape of returned posts, and there is no output schema, so return-value expectations remain somewhat underspecified.

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 exposes platform plus a free-form params object, so the description carries almost all parameter semantics. It enumerates which params each platform accepts, including required-parameter notation and platform-specific options such as userId, sound, playlist, relatedTo, sort, and period.

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 a specific verb and resource: listing posts from a social platform. It also distinguishes the tool's breadth from single-post siblings by explaining that params select among account, search, hashtag, community, sound, company, playlist, related-post, or trending-feed modes.

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 strong guidance on how to choose a source via params and explicitly covers pagination by saying to call again with only the previous cursor. It does not explicitly compare against siblings such as get_social_post or get_social_profile, so it stops short of full when/when-not/alternatives 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?

Goes well beyond the readOnlyHint/openWorldHint annotations by disclosing the cost model in units of $0.001 at list price, the per-platform unit consumption (e.g. amazon 1–2 units), and that failed calls are not billed. Pagination behavior is also disclosed, which is exactly the operational context 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?

Purpose and return shape come first, followed by a compact per-platform matrix, then pagination and cost notes. Every bullet carries a distinct fact; nothing is padded.

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 no output schema, the description still summarizes the return shape (SearchResult items with title, price, rating, seller, url). Combined with the platform matrix, pagination rules, and billing note, an agent has everything needed for a correct first 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?

The nested params object is unconstrained (additionalProperties: {}), so the schema alone documents nothing about valid keys. The description supplies the full valid-parameter matrix per platform, marks required fields, notes that query may be given at the top level, and defines the pagination semantics. This is meaning far 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 and resource with a scoping constraint: 'Search a marketplace's products by keyword.' The keyword scoping clearly separates it from the image-based sibling search_products_by_image and from single-item siblings like get_product.

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 per-platform applicability: which params each of the five platforms accepts, which are required, and how to paginate (params.page = 2, 3, … or cursor). It stops short of naming when to prefer alternatives on the same listing, such as browse_category or search_products_by_image, so routing against those siblings 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 openWorldHint=true, so the safety profile is known. The description adds meaningful behavioral context by explaining that the provided URL is downloaded and sent as the search image, which tells the agent that an external image fetch occurs.

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 short and front-loaded: the core action appears first, followed by the image URL handling and supported platforms. Every sentence carries useful information, and the platform list is compact.

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-only search tool with a fully described input schema and no output schema, the description covers the main calling requirements: the action, required image URL format, platforms, and external fetch behavior. It could mention expected return shape, but that is not essential given the schema and annotations.

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 platform, image_url, and the nested params object. The description reinforces that image_url is used as the search image and lists the supported platforms, but it does not add substantial semantics beyond the structured fields.

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 and resource: it finds marketplace products that match a photo. This clearly distinguishes image-based search from generic product lookup, though it does not explicitly contrast with the sibling search_products 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?

Usage is implied by the phrase "match a photo" and the instruction to provide an image URL. However, it does not say when to choose this over text-based search_products or mention any constraints such as image availability or platform-specific limitations.

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 openWorldHint=true, so the safety profile is covered. The description adds useful context that layout/fonts/colours are preserved and that the result is a translated image, but it says nothing about supported fonts/limits, failure behavior, or the return format beyond 'the translated image'.

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 core action and the preservation guarantee, with zero filler. Every clause 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 four-parameter tool with no output schema, the description covers the action, input form, and that a translated image is returned. The only minor gap is the exact return format (URL vs. binary), but overall it is 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?

Schema coverage is 100%, so all four parameters are already documented, including enums and format constraints. The description only reinforces that the image is supplied as a URL and adds no syntax or format meaning beyond the schema, so 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 ('Replace the text inside a product image with a translation') and names the preserved properties (fonts, colours, layout), which distinguishes it clearly from sibling tools like search_products_by_image. An agent can tell exactly what this does 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?

The description implies usage ('Give the image as a URL') and the operation type makes its niche evident, but it never states when to use this versus alternatives or any preconditions/exclusions. It relies on the agent inferring context from the name and siblings.

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