Resollo Agent API

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

Annotations already declare readOnlyHint=true, and the description reinforces with 'Read-only, no authentication required.' It adds valuable context beyond annotations: the data is 'static', callable once and cacheable for the session, and includes policy URLs. This goes beyond what the annotations alone convey.

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 information-dense but well-organized: it opens with the tool's purpose, then presents a logical list of returned data categories, and closes with usage guidance. Every clause contributes actionable information; despite length, there is no redundancy or 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 empty input schema and an output schema available, the description covers everything an agent needs: what kind of data is returned, how it should be used, its read-only and auth-free nature, and a caching strategy. Nothing essential is missing.

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

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

The tool has zero parameters and the input schema is empty, so there is no parameter semantics to clarify. The rubric baseline for 0 parameters is 4; the description adds no parameter-specific meaning, but none is needed.

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

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

The description identifies a specific verb ('Returns'), a clear resource ('static reference data'), and a precise purpose ('build valid searches and read responses without guessing'). It enumerates the exact contents, making the tool's role unmistakable among operation-focused siblings like products.create and offers.make.

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

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

The description states when to call the tool ('once and cache for the session') and why ('an agent needs to build valid searches and read responses'). It explicitly ties outputs to downstream usage, e.g., 'use these for search's category filter', giving clear guidance absent any alternative metadata 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?

The description repeats the readOnlyHint annotation by stating 'Read-only, no side effects,' and adds an auth requirement ('Authorization: Bearer <agent api key>') that the schema and annotations do not provide. It also discloses the returned entry fields and most-recent ordering, which is useful behavioral context.

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

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

Three sentences with no filler: purpose, parameter guidance, return contents, and side-effect/auth note each earn their place. Important usage information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and annotations covering read-only behavior, the description covers everything an agent needs: role requirement, optional filters, output shape, ordering, auth, and side-effect safety. No critical operational 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%, so parameters are already documented. The description restates the role and state semantics and clarifies default behavior, but adds little beyond the schema's own descriptions.

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

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

The description opens with a specific verb and resource: 'Returns the caller's most recent Make-an-Offer / bargaining offers,' and clarifies it concerns the caller's own offers. The title and description together distinguish this read operation from sibling mutation tools like offers.make and offers.respond.

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 invocation guidance: pass role 'buyer' for sent offers or 'seller' for received offers, and optionally filter by state. It does not name alternatives or state when not to use this tool, but the read-vs-mutate distinction across sibling names is clear.

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 are sparse (only three boolean hints), so the description carries the burden and delivers substantially: it discloses that no money moves, that only a PENDING offer is created, that only one active offer can exist per product, that in-flight locks cause product_not_eligible, and the required Authorization header. This is exactly the behavioral context an agent needs beyond 'make an offer'.

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

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

Four dense sentences, each earning its place: purpose, eligibility/exclusions, concurrency/error behavior, and side-effect clarity with auth requirement. The core verb is front-loaded and there is zero 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 tool with complex eligibility rules and side effects, everything needed to call it correctly is present: type of listing it applies to, seller prerequisites, exclusion cases, error behavior, pending-only semantics, the follow-up tool, and authentication. An output schema exists, so explaining return values is unnecessary.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that offered_price is a non-binding offer amount, but it doesn't add parameter-specific meaning beyond the schema — the behavioral clarification that no money moves is really transparency, not parameter semantics. The schema already explains product_id, currency_code defaulting, and the exclusiveMinimum bound.

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 ('Submits a price offer'), a precise resource ('fixed-price Resollo listing'), and actor ('authenticated buyer'). The 'never on auctions' exclusion and the distinction from the seller-side offers.respond make it unmistakable which action this performs.

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 states when it applies (fixed-price listings with offers enabled and a fully active Stripe Connect account) and when it does not ('never on auctions', locked/not-eligible returns product_not_eligible). Points to the follow-up alternative offers.respond, giving an agent clear routing context.

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 goes well beyond the annotations by disclosing that accepting immediately creates a confirmed order, does not charge any payment method, and that the buyer later pays through the normal flow. It also requires an Authorization header. These behavioral details meaningfully inform the agent about side effects and prerequisites.

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 every sentence carries essential information: core purpose, role/action rules, side effects, and authentication. It is front-loaded with the main purpose and then details conditions without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has role-dependent state transitions and side effects, and the description covers all critical aspects: valid actions per role, required offer state, counter_price condition, the confirmed-order consequence, payment behavior, and auth requirements. Given the output schema exists, return-value documentation is not the description's responsibility.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds role-based meaning by mapping actions to seller versus buyer, and explicitly notes that counter requires counter_price. This supplements the schema's field-level descriptions with usage context.

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

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

The description clearly states the tool responds to a pending Make an Offer / bargaining offer, with specific actions (accept, reject, counter, accept_counter). It differentiates the resource (offers) from sibling tools like orders.place or orders.reject by focusing on offer response 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?

The description gives strong context on when to use it: the offer must be pending or countered depending on caller role, and the valid actions are role-dependent. It does not explicitly name alternatives or say when not to use it, but the role/state conditions are clear enough to guide correct invocation.

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 annotations, the description discloses crucial behavioral traits: it never charges a payment method, only produces a link, and requires the human buyer to complete payment on Stripe's hosted page. It also provides an explicit guardrail about never telling the user the order is 'paid' after calling, and states the required Authorization header. These details add significant context beyond the simple 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?

Every sentence in the description carries essential information: the core action, the non-charging behavior, the buyer obligation, the post-call communication rule, the failure modes, and the auth requirement. The main action is front-loaded, and the structure flows logically from what it does to how to handle the result, with no wasted 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?

The description is complete for a payment-link tool with one parameter. It covers what the tool does, the preconditions, the failure reasons, the auth requirements, and the important caveat about not claiming payment completion. The output schema exists but is not shown, so the description's mention of returning a Stripe-hosted URL sufficiently communicates the return value.

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?

With 100% schema coverage, the orderId parameter is already documented as 'the uuid of the dispatched, not-yet-paid order.' The description reinforces these preconditions and adds context by explaining the buyer-centric purpose, which helps the agent understand the state requirements for the parameter beyond the schema alone.

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

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

The description states a specific verb and resource: 'Creates and returns a Stripe-hosted checkout URL' for a 'DISPATCHED, not-yet-paid order'. It clearly scopes the action and differentiates it from payment execution by emphasizing it never charges or completes payment, making it distinct from other order/payment related tools.

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

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

The description explicitly specifies when to use the tool: for dispatched, not-yet-paid orders on behalf of the buyer. It also defines when not to use it by documenting failure modes: not_ready_for_payment if not yet dispatched, and already_paid if already paid. This gives clear when/when-not conditions, even if it doesn't name an alternative 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 mark the operation read-only, and the description reinforces this with 'Read-only, no side effects.' It adds meaningful behavioral context beyond the annotations: the required Authorization header, currency conversion behavior, and the decoded status booleans. This goes beyond what annotations alone convey.

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

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

The description is front-loaded with the core action and then efficiently covers role selection, output fields, side effects, and auth. It is slightly dense due to the enumerated output fields, but every sentence adds useful operational detail 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?

Given the rich schema, output schema, and read-only annotations, the description covers everything an agent needs to invoke the tool correctly: authentication, role semantics, sorting, output contents, and the key side effect declaration. No critical operational context 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 the baseline is 3; the schema already explains role, limit, and currency. The description adds extra meaning by tying currency to the output ('total price (converted to the requested currency, default USD)') and by framing role as buyer versus seller perspectives, which is not fully captured by the parameter names alone.

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

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

The description starts with a specific verb and resource: 'Returns the caller's most recent orders.' It clearly distinguishes the buyer and seller perspectives, and it references orders.status as a related sibling, so an agent understands this is the list-all-orders view rather than a single-order status tool.

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

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

The description gives clear contextual guidance by explaining exactly when to pass role 'buyer' versus 'seller' and notes the authentication requirement. It does not explicitly name alternatives such as orders.status for single-order checks, so it misses the 'when not to use' guidance needed for a 5.

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 goes well beyond the annotations by explaining the reservation semantics: no payment is charged, the buyer must complete payment through Resollo's checkout flow, and the agent must never tell the user the order is placed or paid. It also discloses auth requirements and the mandatory confirm gate. These behavioral details are not derivable 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 every sentence earns its place: it clarifies what the tool does, what it does not do, what the user must do afterward, what the agent must not say, constraints on listing type, required authentication, and the confirmation gate. The most important distinction (reservation vs purchase) is front-loaded in the first sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the description fully covers the operational context: post-call buyer steps, auth requirements, safety guardrails, listing-type restrictions, and confirmation obligations. With an output schema present, the description does not need to explain return values, and nothing essential to calling this 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 baseline is 3. The description adds some workflow-level context around confirm and product eligibility, but most parameter meaning is already thoroughly documented in the schema, such as confirm being a human-gate boolean, payment_method being off-platform settlement, and currency being informational only. The description does not materially enrich the individual parameter semantics 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 opens with a specific verb and resource: 'Creates a RESERVATION for the given product.' It immediately distinguishes this from a purchase by stating it does NOT complete a purchase or charge a payment method, and it scopes the tool to fixed-price listings only, excluding auctions. This clearly separates orders.place from purchase/checkout sibling tools.

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

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

The description gives clear context for when to use the tool: to reserve a fixed-price product, with the buyer required to finalize payment manually afterward. It also states an important exclusion ('not auctions') and caller requirements such as the Authorization header and explicit buyer approval. It does not explicitly name alternative tools like orders.checkoutLink or offers.make, so it stops short of fully routing between 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?

Beyond the destructiveHint annotation, the description discloses that no money moves, that a specific error (order_not_reserved) is returned once the order has progressed, and that an Authorization header is required. These behavioral details meaningfully exceed 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?

Four purposeful sentences, each earning its place: the action and constraint, the error condition, the money clarification, and the auth requirement. The key constraint is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter destructive action, the description covers timing, failure mode, side effects (no money movement), auth, and what to do after the reserved window. The output schema covers any return details, so nothing critical is missing.

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

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

The input schema already fully describes orderId as 'The uuid of the RESERVED order to reject,' giving 100% schema description coverage. The tool description adds no extra parameter-level meaning, so the baseline of 3 applies.

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

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

The description states a specific verb ('Rejects'), the resource ('an order'), and the actor ('on behalf of the SELLER'). It also pins down the exact state condition ('only allowed while the order is still RESERVED'), which clearly distinguishes this from sibling tools like orders.place or orders.status.

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

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

The description explicitly defines when the tool is allowed (while RESERVED, before dispatch/payment) and what happens past that point. It also directs the agent to the normal Resollo order page for anything after dispatch, providing a clear fallback alternative.

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 goes well beyond the readOnlyHint annotation by disclosing the authentication header requirement, the forbidden response for non-buyer/seller callers, and the decoded-boolean representation instead of a raw state number. This gives the agent actionable expectations about behavior and failure modes.

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 three sentences and every sentence earns its place: return payload, authorization constraint, and read-only guarantee. Information is front-loaded with the primary purpose before the access caveat.

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 two-parameter tool with a fully documented input schema and an output schema present, the description covers the key behavioral constraints: auth, role-based access, read-only semantics, and what data is returned. Nothing essential is missing for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both orderId and currency. The description adds little beyond the schema except noting currency semantics are shared with search_products, which is a minor cross-reference; this meets the baseline but does not exceed it.

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 the specific verb 'Returns' and clearly identifies the resource: the current status of one Resollo order. It enumerates the statuses (reserved, dispatched, paid, received, rejected, closed), notes decoded booleans rather than a raw number, and mentions carrier/tracking and total price, which fully disambiguates it from the sibling tools.

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

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

The description provides clear usage context by stating the caller must be the buyer or seller and that authorization is required, plus it explicitly notes read-only behavior. It does not compare with sibling tools, but no other sibling directly overlaps with order-status retrieval, so the absence of exclusions is acceptable.

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 are neutral (readOnlyHint=false, openWorldHint=false, destructiveHint=false), so the description carries the burden and delivers richly: listing is created INACTIVE and not publicly visible, the seller must manually review/activate via activation_url, content is AI-generated server-side, the listing is attributed to the API key's user, and post-call agent messaging is prescribed (never say 'live' or 'published'). This far exceeds what the annotations convey.

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

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

The description is long (~230 words) but every sentence earns its place for a side-effecting tool: activation flow, auth requirement, image constraints, and post-call user messaging are all load-bearing. There is some redundancy (the photos-only concept is stated three times), and the 'web listing form AI autofill' comparison is nice-to-have rather than essential, so it is not a zero-waste 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter, side-effecting creation tool with an output schema, the description is complete: it covers post-conditions (inactive draft), the manual activation step, the activation_url return value, auth key sourcing and attribution, image sourcing constraints, and the exact messaging the agent must give the user. Nothing an agent needs to call this correctly and handle the aftermath 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 every parameter already has a meaningful description, including that images must be base64 bytes and never URLs, and that name/price/condition/category_id/description are AI overrides. The description reinforces the photos-only constraint and tie to the 'AI autofill' pipeline, but adds little parameter-specific meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description leads with a specific verb, resource, and the defining mechanism: 'Creates a new Resollo product listing FROM PHOTOS ONLY'. It precisely distinguishes itself from the read/search siblings (products.get, products.search) by anchoring on photo-driven AI generation, and the title reinforces the same 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?

The description gives clear when-to-use context (you have photo files of an item) and explicit exclusions: never accept direct listing content, never fetch or invent an image from a URL. However, it never names a sibling alternative or explicitly states when to choose another tool (e.g., products.search for retrieval), so it stops short of a 5.

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

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

It discloses no-authentication-requirement, and the not_found cases (nonexistent, sold, expired, moderation-hidden) go well beyond the readOnlyHint annotation. These are the behavioral nuances an agent needs to interpret responses correctly.

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

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

The description is dense but efficient, front-loading the core action and resource. The parenthetical definition of the Semantic Profile is a bit verbose, yet it directly aids tool selection by telling the agent why that data matters for buyer fit.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema, full parameter schema coverage, and readOnly annotations, the description supplies the remaining essential context: no authentication, not_found semantics, and the key returned areas. Nothing critical to correctly invoking or interpreting this tool is missing.

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

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

Schema description coverage is 100%, so both productId and currency are already fully documented in the schema. The description adds no parameter-level meaning beyond the schema, which aligns with the baseline for full schema coverage.

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 ('Fetch') and resource ('product listing by ID'), and enumerates the returned fields, making it unmistakably distinct from the sibling search tool products.search. It also highlights the Semantic Profile as a key differentiator for buyer-fit evaluation.

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 makes clear this is the tool for retrieving a single product's full details by ID and notes not_found behavior. It does not explicitly name alternatives or state when not to use it, but the context strongly implies it for exact product lookups rather than discovery.

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 annotation, the description discloses that results are limited to active, purchasable listings (excluding sold, expired, or moderation-hidden), pagination behavior via next_cursor, no authentication required, and that sort order is never influenced by paid placement. These are meaningful behavioral traits not present in 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?

Four sentences cover purpose, use cases, the key sibling relationship, pagination, and authentication. Information is front-loaded, and every sentence adds either essential scope or behavioral guidance; there is no filler or repetition of schema fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a rich output schema available and readOnlyHint=true, the description fully situates the tool: what it filters, what it excludes, pagination mechanics, auth expectations, and where to go for deeper per-product data. Nothing needed for correct invocation is missing.

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

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

The input schema provides 100% description coverage for all 10 optional parameters, including defaults, formats, and constraints. The tool description adds only general filter categories already reflected in the schema, so it does not substantially elevate parameter understanding beyond the baseline.

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

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

The description opens with a specific verb and resource: 'Search active, publicly available product listings on the Resollo marketplace.' It clearly defines the scope ('browse or filter by keyword, category, price range, currency, or seller location') and explicitly contrasts with products.get, so an agent can distinguish it from the sibling tool without opening schemas.

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

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

The description gives explicit when-to-use instructions ('Use this to browse or filter...') and a direct when-not-to-use rule: 'For full details on one specific product you already have the ID for... call products.get instead.' It also names what this tool does NOT return, which prevents misuse.

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 annotations, the description discloses the side effect: a product_questions record identical to the web form is created on behalf of the authenticated caller. It also adds the required Authorization Bearer header and clarifies the tool's boundary—no drafting or sending an answer—which are meaningful behavioral facts not visible in the schema.

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

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

Three sentences, each earning its place: what the tool does, what it does not do, and the auth requirement. The main action is front-loaded 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?

For a two-parameter mutation with an output schema and clear annotations, the description covers the essential context: auth header, side effect, public nature, and tool boundaries. Nothing needed to call 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 description coverage is 100%: both product_id and question already have detailed descriptions, including the 500-character cap and UUID format. The description repeats the 500-character cap but adds no new parameter-level meaning, so the baseline of 3 applies.

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

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

The description names the verb ('Submits'), the resource ('public question about a product listing'), and the actor ('authenticated caller'), and ties it to the same record the web form creates. This clearly distinguishes it from siblings like questions.list, which is a read operation.

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

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

It clearly establishes this tool is for asking, not answering: the seller answers on the Resollo web UI and this tool does not draft or send an answer. It does not explicitly name a sibling for the read workflow, but the context is clear enough that an agent knows when to use this tool.

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

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

Annotations already declare readOnlyHint=true, and the description adds 'no authentication required' plus a meaningful behavioral detail: answer/answered_at are null for unanswered questions. This goes beyond the annotation and helps the agent interpret results, though it does not discuss pagination or potential 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?

Three concise sentences with no filler: behavior is front-loaded, then edge cases, then usage scenarios, then auth note. Every sentence contributes distinct information.

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 single-parameter, read-only listing tool with an output schema available, this description is complete: it tells the agent what it returns, what nulls mean, when to use it, and that no authentication is needed. No critical context 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?

There is only one parameter and schema description coverage is 100%, with productId already described as 'The product listing's uuid.' The description adds no further parameter meaning beyond using the phrase 'product listing', so it does not exceed the schema baseline.

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

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

The description states a specific action ('Returns every question asked about a product listing') on a clear resource (product Q&A), including the key detail that seller answers are included where they exist. It distinguishes itself from siblings like questions.ask by framing this as retrieving past buyer questions, and from reviews.list by focusing on Q&A rather than reviews.

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

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

The description gives explicit use cases: check what past buyers asked before asking a new question, or before advising a buyer. This effectively routes an agent to this tool versus asking a new question, though it does not name alternatives or state when not to use it.

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

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

Beyond the readOnlyHint annotation, the description adds meaningful behavioral context: 'Read-only, no authentication required' clarifies access requirements, and 'Every review is tied to a real, verified order line -- only actual buyers can leave one' discloses data provenance and trust guarantees. These are valuable traits not present in the annotations or schema and they do not contradict them.

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 composed of three compact sentences, each earning its place: the return payload, the verification/trust characteristic, and the intended use case with auth status. The core purpose is front-loaded, with no redundant or filler wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read-only tool with an existing output schema, this description is complete: it states what is returned, provides trust/verification context, names the decision scenario, and clarifies authentication. There are no missing critical details that would prevent an agent from invoking 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?

The single parameter productId is fully covered by the input schema with type, format, pattern, and description 'The product listing's uuid.' Since schema coverage is 100%, the description does not need to add parameter detail, and it does not. Baseline 3 applies when the schema carries the 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?

The description opens with a specific verb and resource: it returns reviews left for a product by past buyers, and explicitly enumerates the contents (rating, message, date) as well as the aggregate average rating and review count. This clearly distinguishes reviews.list from sibling tools like questions.list or products.search by naming the exact domain object and data being retrieved.

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

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

The description states a clear usage context: 'Useful to judge product/seller quality before advising a buyer on a purchase decision.' This tells the agent when to call the tool, but it does not explicitly contrast it with alternatives or state when not to use it, so it falls short of the explicit exclusion/alternative guidance level.

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 annotation, the description explicitly states 'Read-only, no authentication required' and details exactly what data is returned, including edge cases like null feedback rating. It also explains how the seller id relates to search, adding practical behavioral context.

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

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

The description is front-loaded with the core action and then provides a dense, useful enumeration of return fields and use cases. Every sentence adds meaningful information for tool selection or invocation, 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 a single well-documented parameter, an output schema present, and annotations covering read-only behavior, the description fully covers what an agent needs: purpose, return contents, use cases, authentication requirements, and parameter sourcing.

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

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

The input schema already fully documents sellerId and where it comes from (search or getProduct result). The description adds further value by noting the same seller id can be passed as search's seller_id filter and by tying the parameter to the shop_url use case.

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 ('Returns a seller's public profile') and enumerates the exact fields returned, making the tool's purpose unmistakable. It does not explicitly distinguish itself from sibling tools like sellers.status, but the public-profile framing and field list make the boundary reasonably clear.

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

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

The description gives clear use cases: judging seller reputation before advising a buyer and obtaining shop_url for browsing a seller's items. It does not explicitly state when not to use this tool or name alternatives, but the context is concrete enough for an agent to select it appropriately.

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 the description adds valuable behavioral context: no side effects, required Authorization header, soft-deleted exclusion, inclusion of edit_url, and the fact that inactive drafts can be activated via that URL. This goes well beyond the structured 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?

Every sentence contributes: scope, use cases, output fields, optional filtering, read-only behavior, and auth requirement are all covered in a dense but easily parseable paragraph. The core definition is front-loaded, 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?

Given the read-only annotation, the existing output schema, and only two optional parameters, the description is complete. It covers authentication, exclusions, state semantics, and the practical recovery scenario for lost product IDs, so an agent has everything needed to invoke and interpret the tool.

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

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

Schema coverage is 100%, so the schema already documents both limit and state. The description reinforces that state is optional and that 'inactive' corresponds to products.create drafts, but it does not add meaningful parameter detail beyond the schema, matching the baseline expectation.

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 ('Returns'), a specific resource (the caller's own listings), and an explicit scope ('EVERY state' including inactive, pending moderation, rejected, closed), while also noting what is excluded (soft-deleted listings). This clearly distinguishes it from public listing search and from products.get.

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

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

Gives explicit use cases: finding a draft created via products.create when the product_id is unknown, and reviewing what the seller currently has listed. It does not explicitly name alternative tools or exclusion conditions, but the intended contexts are clear enough for an agent to select it correctly.

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 the description reinforces this with 'Read-only, no side effects.' It adds non-obvious behavioral context beyond annotations: products.create consumes 2 credits per call, payment/shipment configuration is a prerequisite, and the tool reveals plan-based limits. This gives an agent useful operational expectations without contradicting 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?

The description is dense but every sentence earns its place: the first states the core purpose and specifics, the second provides actionable sequencing and dependency information, and the final sentence confirms safety. It is front-loaded with the result and then explains why and when to invoke the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there are no parameters and an output schema exists, the description covers all the essential context an agent needs: what the tool reports, why it matters, when to call it, and that it is safe. It even ties the result to downstream behavior with products.create, making the tool's role in the workflow fully understandable.

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

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

The input schema has zero parameters, and the description correctly focuses on what the response contains rather than input semantics. It names the key result fields—listing capabilities, payment/shipment setup, max images/price, AI credit balance—which adds meaning beyond the empty schema. The baseline of 4 for a parameterless tool is appropriate.

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

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

The description states a specific verb and resource: 'Returns the authenticated user's current listing capabilities.' It enumerates exactly what is included—creation eligibility, payment/shipment configuration, plan limits, and AI credit balance—so an agent can distinguish this from generic seller info tools like sellers.get.

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

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

The description gives explicit timing guidance: 'Call this BEFORE asking the user for photos or calling products.create.' It explains why the preflight matters by noting that payment/shipment methods are required for products.create to succeed. It does not explicitly contrast sellers.status with alternatives like sellers.get or products.get, so it stops short of full when-not-to-use guidance.

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