Resollo Agent API

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

Annotations already declare readOnlyHint and openWorldHint, and the description reinforces consistency while adding genuinely new behavioral facts: no authentication is required, the call is safe to cache for the session, and other tools default to the caller's currency when known. That is auth, caching, and cross-tool default behavior — real value beyond 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?

Front-loaded with the purpose, then a dense enumeration of payload contents, then two short operational sentences. The long first sentence is warranted for a reference-data dump, though it would scan better as a list; nothing is padding.

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

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

An output schema exists, so return values need not be described, and the description nonetheless names the payload categories plus the auth, caching, and currency-default behavior an agent needs before calling. Nothing material is missing for a static reference endpoint.

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

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

The schema has zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool is 4. The description instead explains what the parameterless payload contains, which is useful but not 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?

Opens with a specific verb and resource ("Returns the static reference data") and then enumerates exactly what that data is: category ids and keys, condition codes, currency codes and default, payment/shipment method codes, sort options, max page size, and policy URLs. An agent can tell immediately that this is the taxonomy/reference endpoint and not a search or listing 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?

Explicitly states the purpose of calling it (build valid searches and read responses without guessing), tells the agent how to use the output ("use these for search's category filter"), routes a sub-question to the right sibling ("see sellers.status max_images"), and advises caching once per session. Both the when and the alternative path are stated.

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 annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds useful context: authentication requirements via OAuth or Bearer token, newest-first ordering, and the return fields for each entry. It repeats the no-side-effects point already covered by annotations, but the auth and ordering details are meaningful additions.

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, dense, and free of waste. It starts with the core purpose, then covers role semantics, state filtering, return contents, and auth in a logical sequence.

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, full schema description coverage, and read-only annotations, the description is complete enough for correct invocation. It covers authentication, filtering behavior, ordering, and the key fields returned without over-explaining.

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 explains role, limit, and state in detail. The description reinforces the same role behavior and state values but does not add syntax, format, or edge-case meaning beyond what the schema provides.

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

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

The description states a specific verb and resource: it returns the caller's recent Make-an-Offer / bargaining offers, with role and state filtering. The scope is clear enough to distinguish it from mutation siblings like offers.make and offers.respond, 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?

It explains exactly how to use role: buyer for sent offers, seller for received offers, and omission for both, plus optional state filtering. It gives clear contextual guidance but does not explicitly compare against sibling listing tools such as orders.list or sellers.listings.

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 only give readOnlyHint=false, destructiveHint=true, openWorldHint=false; the description goes well beyond by stating no money moves, that a PENDING offer is created awaiting seller response, the one-active-offer-per-product constraint, the specific error code returned when ineligible, and the auth requirements (OAuth or Bearer agent key). This is exactly the extra context annotations cannot carry.

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

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

Front-loaded with the core action and eligibility, then constraints, then auth. Dense and largely waste-free, though the single long paragraph with em-dashes and parentheticals could be split for faster scanning.

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 mutation tool with a rich output schema present, the description covers everything an agent needs: eligibility preconditions, auth, the pending-not-paid semantics, the concurrency lock, and the error code. Return-value detail is correctly left to the output schema.

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

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

Schema description coverage is 100%, so product_id, currency_code and offered_price are already fully documented in the schema; the description adds only the buyer-context and listing-currency framing, not new parameter semantics. 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 ('Submits a price offer on a fixed-price Resollo listing') and immediately delimits it from auctions and from the sibling offers.respond ('see offers.respond'). An agent can distinguish it from every sibling without opening a schema.

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

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

Explicit when-it-works conditions (fixed-price listing, seller has offers enabled, active Stripe Connect account), an explicit when-it-does-not ('never on auctions'), and the failure mode (product_not_eligible) plus the alternative/next step (offers.respond). Nothing is left to inference.

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

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

Annotations declare only readOnlyHint=false, destructiveHint=true, openWorldHint=false; the description goes well beyond them by disclosing that accept immediately creates a confirmed order, that no payment method is charged at this step, that the buyer still completes payment through the normal flow afterward, and that a signed-in user or agent API key header is required.

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?

A single dense paragraph that front-loads the purpose, then the seller rules, the buyer rule, and the payment consequence, closing with auth requirements. It is appropriately sized for a stateful multi-action tool, though the action/role rules echo the schema's enum description closely.

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

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

With an output schema present, return values need not be explained; the description still covers every decision point an agent needs — auth method, offer state requirements, action eligibility by role, counter_price conditionality, and the downstream consequence of acceptance.

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

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

Schema coverage is 100%, and the schema's own enum description already maps each action to seller vs. buyer and notes counter_price is required for 'counter'. The description largely restates these same role/action pairings, adding little syntax or format detail 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?

States a specific verb ('Responds to') and resource ('a pending Make an Offer / bargaining offer'), which cleanly separates it from offers.make (creating an offer) and offers.list (reading them). The role-conditional action rules make the tool's scope unambiguous 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?

Gives explicit preconditions: sellers must use accept/reject/counter on a pending offer, buyers must use accept_counter on a countered offer. It does not name a sibling alternative for the underlying transaction (e.g. orders.place or offers.make), but the state conditions are precise enough to select the tool 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?

Goes well beyond the annotations: it clarifies that no charge is ever made and no payment is completed, that a human must finish payment on Stripe's hosted page, that the agent must not report the order as paid, and it specifies auth requirements (OAuth or Bearer agent API key) and named error conditions. This is exactly the kind of side-effect and precondition disclosure annotations cannot carry. The destructiveHint=true annotation is conservative but not contradicted, since creating a link mutates nothing the description claims is safe.

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

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

Front-loads what the tool does, then the critical caveat that it never charges, then preconditions and auth. No sentence is filler; each one changes agent behavior (don't claim paid, don't attempt payment, expect specific errors).

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

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

With an output schema present, the description need not explain the return payload, and it covers everything else an agent needs: eligibility, failure codes, auth, and a behavioral instruction about post-call messaging. Nothing material is missing for correct invocation.

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

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

Only one parameter and schema description coverage is 100%, so the schema already documents orderId as the uuid of a dispatched, not-yet-paid order. The description restates the same constraint ("dispatched, not-yet-paid order") without adding format or sourcing detail beyond the schema, matching the baseline of 3.

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

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

States a specific verb+resource+output ("Creates and returns a Stripe-hosted checkout URL") scoped to a DISPATCHED, not-yet-paid order and acting on behalf of the buyer. This is clearly distinguishable from siblings like orders.place, orders.status, and orders.reject, which all concern order lifecycle rather than payment links.

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 clear preconditions for use (order must be dispatched and unpaid) and explicit failure modes (not_ready_for_payment, already_paid) that tell the agent when the tool will not work. It stops short of naming sibling tools as alternatives (e.g., checking state via orders.status first), so it is clear context but not a full when/when-not/alternative map.

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, it discloses the authentication requirement (OAuth sign-in or 'Authorization: Bearer <agent api key>'), the default newest-first ordering, and the currency-conversion default chain. 'Read-only, no side effects' partly restates readOnlyHint=true, but the auth and ordering context is genuine added value.

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?

One dense paragraph with the purpose front-loaded and no filler sentences. The enumeration of return fields is somewhat redundant given an output schema exists, costing a little tightness.

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 three-optional-parameter read tool with full schema coverage, annotations, and an output schema, everything an agent needs is present: auth, filter semantics, ordering, currency behavior, and the read-only guarantee. No gaps remain that would cause a misinvocation.

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 role, limit and currency are already fully documented, and the description's role and currency sentences largely restate those descriptions. It adds only the default-ordering note ('omit role for both') already implied by the enum, 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?

Opens with a specific verb and resource ('Returns the caller's most recent orders') and immediately scopes it to the authenticated user, which separates it from siblings like offers.list and products.search. It also anchors itself to orders.status, so an agent knows this is the list view of the same order domain.

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 role parameter is framed as explicit routing: 'buyer' for orders you placed, 'seller' for orders on your listings, omit for both — that removes the main ambiguity an agent would face. However, it never states when to prefer a sibling (e.g., when to use orders.status instead for a single order), so the when-not guidance is absent.

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 flag destructiveHint=true, and the description explains the real-world consequence behind that: inventory is reserved, no payment is taken, and a human must complete checkout. It also adds auth requirements and the critical instruction never to tell the user the order is 'placed' or 'paid'. It does not discuss reservation expiry or how a reservation is released, which is the main remaining gap.

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 reservation-not-purchase distinction is correctly front-loaded, and every paragraph carries operational instructions. The caveat is repeated three times (does not purchase, buyer must pay manually, never say 'placed'), which is slightly redundant but defensible for a high-stakes mutation.

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 destructive, human-in-the-loop mutation with eight parameters, the description covers scope, auth, preconditions, post-call messaging, and limitations. An output schema exists, so return-value detail is unnecessary, and the remaining gaps are minor.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds decision-relevant meaning by tying confirm to the human-approval gate and restricting product_id to fixed-price listings, which the schema itself does not say. It does not add anything on payment_method/shipment_method beyond the schema's seller-acceptance note.

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 first sentence states a specific verb and resource ("Creates a RESERVATION for the given product") and immediately scopes it against the obvious misreading ("does NOT complete a purchase and does NOT charge"). This clearly separates it from siblings such as orders.checkoutLink and offers.make, which an agent might otherwise confuse with placing an order.

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?

Explicit when-to-use conditions are given: fixed-price listings only, not auctions; requires a signed-in user via OAuth or bearer agent key; and the buyer must have explicitly approved the specific order with confirm=true. It also names the follow-up path (buyer completes payment at resollo.com via Stripe or cash confirmation), which effectively routes the agent to the correct next step.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description goes further: it discloses the state-machine constraint, the exact failure mode ('Returns order_not_reserved'), the money-safety guarantee ('This does NOT move any money'), and the auth requirement (OAuth sign-in or Bearer agent API key). That is meaningful context beyond 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?

Three sentences, front-loaded with the action and its precondition, followed by the failure mode, the money-safety note, and auth. Every clause carries information an agent needs before calling.

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

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

An output schema exists so return values needn't be explained, and the description still covers preconditions, failure code, money semantics, and auth. Nothing required to call this mutation correctly is missing.

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

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

Schema coverage is 100% and the schema already documents orderId, its uuid format, and pattern. The description only reinforces the precondition ('RESERVED order to reject'); baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Rejects an order'), names the acting party (on behalf of the SELLER), and scopes it to the RESERVED state. This clearly separates it from siblings like orders.place, orders.status, and orders.checkoutLink.

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

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

Gives an explicit precondition ('only allowed while the order is still RESERVED, i.e. before the seller has dispatched it or the buyer has paid') and an explicit alternative for the out-of-scope case ('use the normal Resollo order page for anything after dispatch'). Nothing is left to inference.

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

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

Goes well beyond the readOnlyHint annotation: discloses the access-control rule and failure mode ('forbidden otherwise'), the authentication options (OAuth or bearer agent key), the decoded-boolean return shape, and that it is side-effect free. An agent knows exactly what it will get and what could fail.

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 packed sentences: what it returns first, then access control, then auth/side-effect guarantees. No redundant restatement of the tool name or title, and every clause carries 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?

With an output schema present, the description needn't detail return values, and it still covers the caller-visible contract: permissions, auth, error condition, and status encoding. 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%, so both orderId and currency are already documented in the schema. The description mentions the returned price but adds no syntax or formatting guidance for the currency parameter, so it neither compensates nor detracts.

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 ('Returns the current status of one order') and enumerates the exact status values plus the payload (carrier/tracking, total price). This clearly separates it from siblings like orders.list and orders.checkoutLink.

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?

Implicitly scopes usage to a single known order and states the authorization precondition (buyer or seller, else forbidden). It does not explicitly name orders.list as the alternative for browsing multiple orders, so routing relies on 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?

Goes well beyond the annotations (readOnly=false, destructive=true, openWorld=false) by disclosing that the result is an INACTIVE non-public draft, that the seller must activate it, that Resollo never converts photos, that no photo bytes may be passed as arguments, and the exact OAuth/Bearer auth requirement. This is unusually rich 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 core action is front-loaded and the two-step workflow is logically sequenced, so most sentences carry weight. It is nonetheless long and dense, with some parenthetical caveats about image vs. file handling that could be tightened without losing meaning.

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?

Output schema exists so return values need not be explained, and the description still covers the full lifecycle: preconditions (signed-in user), the two upload paths, the follow-up call, and the inactive-draft outcome. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100% and the enum is already described, so the baseline is 3. The description earns extra credit by explaining the downstream consequences of each value (picker renders in-chat for MCP Apps clients vs. direct revealing upload_id/direct_upload and hiding the picker), which materially helps value selection.

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

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

States a specific verb+resource ('Starts creating a new Resollo listing from photos') and immediately distinguishes itself from the sibling products.createFromUpload by framing itself as the first step of a two-step flow. An agent can tell it apart from other products.* tools 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?

Explicitly lays out when to use each mode: picker (1) for MCP Apps clients or when only inline pixels exist, direct (2) only for agents that can produce WebP and do an HTTP PUT. It names the follow-up tool (products.createFromUpload) and the fallback path, leaving nothing 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 only cover readOnly/destructive/openWorld hints, while the description adds substantial behavioral context: the product is created as an INACTIVE draft (not public), the seller activates it via activation_url, 2 AI credits are consumed per call, non-WebP photos are rejected rather than converted, and a signed-in user is required. Actions, side effects, cost, and failure mode are all disclosed.

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

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

The action and its precondition are front-loaded, and the remaining sentences each carry real weight (draft state, cost, rejection rule, auth). It is dense but nearly waste-free; the aside about the photo picker panel is the only marginally non-essential 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?

For a one-parameter mutation that already has an output schema, annotations, and a fully described input, the description covers everything an agent needs: sequencing with its predecessor, what gets created, what is returned, cost, and constraints. Nothing material 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%, so the schema fully documents upload_id and its relationship to products.create. The description restates the same origin ('its upload_id') without adding format or validation detail beyond the schema, so the baseline 3 applies.

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

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

The description states a concrete verb and outcome ('Finishes a direct upload started with products.create') and names the sibling it chains from. An agent can immediately distinguish it from products.create and the other products.* tools because it is framed as the terminal step of a two-phase upload flow.

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 the exact precondition for calling: PUT the converted photos to direct_upload.put_urls first, then call this with the upload_id from products.create. The alternative/predecessor tool is named explicitly along with the condition that selects it, leaving nothing 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?

Beyond the read-only annotation, the description adds substantial behavioral context: no authentication required, exact not_found conditions, semantic_profile nullability, shipment price text-range semantics, and payment method distinctions. These details materially help an agent interpret results 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 front-loaded with the core purpose and then adds relevant field-reading guidance. It is dense but largely waste-free, though its single long paragraph and many semicolon-separated details reduce scanability.

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 get-by-ID tool, the description covers the important gaps: authentication requirements, error conditions, null semantic profiles, currency handling, and payment method interpretation. The output schema exists, so it does not need to document every return field structurally.

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 has 100% description coverage for productId and currency, including the UUID format and currency default behavior. The description reinforces that lookup is by ID but does not add parameter-level 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 uses a specific verb and resource: fetching full details of one specific Resollo product listing by ID. It clearly distinguishes this from sibling operations like products.search and products.create by emphasizing retrieval of a single listing.

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 states the usage context: use this when you have a product ID and need full listing details. It also explains not_found outcomes for missing, sold, expired, or moderation-hidden products. However, it does not explicitly name products.search as the way to obtain an ID.

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

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

Annotations give readOnly/openWorld, but the description adds real value on top: only active, purchasable listings are returned (never sold/expired/moderation-hidden), no auth is required, and pagination uses next_cursor with count being the all-pages total. It also discloses that Semantic Profile fields are not returned. Slightly short of a 5 only because it doesn't detail rate limits or ordering guarantees beyond what's implied.

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

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

Front-loaded with scope, then usage, then the products.get alternative, then pagination/count, then auth. Dense but each sentence carries distinct information; only minor tightening (e.g., the Semantic Profile field enumeration) is possible.

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 10 params all documented, an output schema present, and annotations covering safety, the description still supplies scope constraints, pagination mechanics, count semantics, auth status, and sibling routing. Nothing an agent needs 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 coverage is 100%, so baseline is 3, but the description adds non-trivial semantics beyond the schema: prefix-at-word-start matching behavior, the distinction between count (total) and page size, and that cursor round-trips next_cursor. These clarify how results behave, not just what fields exist.

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

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

Opens with a specific verb and resource ("Search active, publicly available product listings on the Resollo marketplace") and explicitly contrasts itself with products.get for single-product lookups. An agent can distinguish it from every sibling without opening a schema.

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

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

States exactly when to use it (browse/filter by keyword, category, price, currency, location) and names the alternative ('call products.get instead') with the precise condition (you already have the ID). Explicit routing is provided.

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 operational details beyond the annotations, such as the 500-character cap on the question text and the exact authentication methods required (OAuth/Bearer header). It also explicitly states that the behavior is identical to the web form.

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 highly efficient, moving logically from core function to functional limitations and finally to technical requirements (authentication). It is neither overly verbose nor overly sparse.

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

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

Given the complexity (involving submission, authentication, character limits, and manual follow-up), the definition is complete. It addresses all necessary preconditions for a successful invocation.

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

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

The schema coverage is 100%, so the schema itself already documents the parameters fully. The description only reinforces the character limit which is already in the schema, meeting the minimum viable standard.

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 explicitly states it submits a public question about a product listing. It uses a specific verb ('Submits') and clearly identifies the resource and the action taken on that resource.

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 definition provides excellent context on usage by explaining the full lifecycle: the tool submits the question, but the seller answers it manually on the web UI. This clarifies that the tool is for inquiry, not response automation.

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=false, so repetition of 'read-only' adds little, but 'no authentication required' is genuinely new operational context. The disclosure that answer/answered_at are null for unanswered questions is also valuable behavioral detail beyond 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?

Three tight sentences with zero waste; the return shape and null caveat come first, followed by usage, with the access constraints last. Nothing is padding.

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

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

An output schema exists, so return format need not be spelled out, and the description still covers result semantics and access requirements. Only minor gaps remain, such as ordering or pagination expectations for products with many questions.

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% with a single required productId documented as a UUID, so the schema carries the full burden. The description adds no further parameter meaning (e.g., no note on what happens with an unknown or malformed UUID), so the baseline 3 applies.

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

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

States a specific verb and resource (returns every question asked about a product listing) plus the shape of the result, including that answers are inlined with null semantics. This clearly separates it from siblings like questions.ask and reviews.list.

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

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

Explicitly names two use cases: checking what past buyers asked before asking a new one, and advising a buyer on a purchase. This implicitly routes the agent away from questions.ask, though it never names the alternative or any exclusion condition directly.

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 adds useful behavioral context beyond the annotations: reviews are tied to verified order lines, only actual buyers can leave them, and no authentication is required. It does not cover pagination, sorting, or error behavior, but the output schema exists and annotations already declare read-only status.

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 and each sentence mostly earns its place by covering returns, provenance, usage, and safety. The final sentence partly repeats the read-only annotation, which keeps it slightly below maximally concise.

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 read-only tool with one well-documented parameter, an output schema, and annotations covering safety, the description is complete enough. It explains what is returned, why the data is trustworthy, and when it is useful.

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 one required parameter, productId, and schema description coverage is 100%, so the schema already documents it as the product listing's UUID. The description only implies the parameter via 'for a product' and adds no further syntax or format details.

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: it returns reviews for a product, including rating, message, date, average rating, and review count. This is clearly distinguishable from sibling tools like products.get or orders.list, which cover different resources.

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 usage context by saying the reviews are useful to judge product or seller quality before advising a buyer. However, it does not explicitly compare against alternatives or state when not 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 openWorldHint=false, so the safety profile is covered; the description nevertheless adds the authentication fact ('no authentication required') and discloses null semantics for the rating field. It does not contradict the annotations in any way, though the 'read-only' restatement is redundant.

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

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

Front-loaded with the core action, then the field inventory. The long enumerations of fields largely duplicate what the output schema already conveys, so a few clauses are less load-bearing than they look, but no sentence is filler and the reputation/URL framing 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?

With only one required parameter and a full output schema, the description is more than complete enough: it covers purpose, auth, and return semantics. The only shortfall is not routing the agent to sellers.listings for the actual item list after obtaining shop_url.

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 uuid format and pattern are fully documented in the schema. The description adds real value by explaining where the id comes from ('the same seller id as search's seller_id filter' / 'seller.id from any search or getProduct result'), which is 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?

States a specific verb and resource ('Returns a seller's public profile') and enumerates the exact fields returned, drawing an explicit parallel to the web /user/<id> page. This clearly separates it from siblings like sellers.listings, sellers.status, and reviews.list, which cover other slices of seller data.

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

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

Gives two concrete use cases ('judging seller reputation before advising a buyer', 'get the shop_url for browsing everything they sell') and even cross-references the seller_id filter used by search. What is missing is an explicit when-not / alternative pointer — e.g. that sellers.listings is the tool for fetching the items themselves.

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, so the 'Read-only, no side effects' line is redundant, but the description still earns credit by disclosing that soft-deleted listings are excluded and spelling out the auth requirement (OAuth sign-in or Bearer agent API key header). It also explains the lifecycle semantics of 'inactive' drafts and where edit_url points.

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 most important fact — all states, not just public ones — is front-loaded, and each sentence is informational. It runs long, though, and the aside about drafts carrying the midpoint of Resollo's AI price suggestion is tangential to selecting or invoking the tool.

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

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

Everything an agent needs to choose and call this tool is present: state coverage, the draft-recovery use case, auth prerequisites, exclusion of soft-deleted items, and optional filtering. Return values are already covered by the output schema, and the description's field summary is a bonus rather than a requirement.

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

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

Schema coverage is 100% and both parameters are fully documented there, including the state enum and limit bounds, so baseline 3 applies. The description restates 'optionally filter to a single state' and the meaning of 'inactive' without adding anything the schema does not already say, and it never mentions 'limit'.

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 ('Returns the caller's own product listings') and pins down the scope precisely: every state including inactive, pending_moderation, rejected, closed, excluding soft-deleted. This distinguishes it cleanly from public-search siblings like products.search and from products.get / products.create.

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 two explicit usage triggers: recovering a draft created with products.create when the product_id is lost, and reviewing what the seller currently has listed. It implicitly excludes public-facing search ('not just the publicly visible ones') but never names products.search or products.get as the alternative for that case.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, yet the description still adds real behavioral context: each draft listing costs 2 credits charged at creation time, max_price null means no cap, and ai_credits_purchase_url/translate_credits_purchase_url are the remediation paths. The closing 'Read-only, no side effects' mostly restates the annotation, which keeps it from a 5.

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

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

The purpose and the capability list are front-loaded in the first sentence and everything after it is actionable. It is dense and somewhat run-on (the parenthetical asides stack up), but no sentence is pure filler.

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

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

With an output schema present, the description does not need to document return shapes, and it correctly focuses on when to call and how to interpret the credit/price results. Nothing an agent needs in order to invoke this zero-param read tool is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description instead documents the semantic meaning of returned values (null max_price = no price cap, required payment/shipment config), which is helpful but technically return-value information rather than parameter meaning.

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

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

States a specific verb and resource — it returns the authenticated seller's listing capabilities — and enumerates the concrete fields (listing permission, payment/shipment config, image/price limits, AI credit balance). This is clearly distinguishable from siblings like sellers.get or sellers.listings, which retrieve profile/listing data rather than a pre-flight capability check.

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 ordering rule: call this BEFORE asking the user for photos or calling products.create, and explains why (surface blockers upfront rather than after a failed attempt). It also names the concrete downstream condition — products.create will not succeed without a payment/shipment method — which is exactly the when-to-use signal an agent needs.

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