Resollo Agent API

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

Annotations already mark readOnlyHint=true, but the description adds meaningful behavioral context: no authentication is required, and not_found is returned for missing, sold, expired, or moderation-hidden products. This goes usefully 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?

Every sentence earns its place. The primary action and return contents are front-loaded, and the edge-case/auth details are placed at the end without excess 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?

There is no output schema, so it is valuable that the description enumerates the returned product data and the not_found semantic. It is complete for most invocation needs, but the undocumented optional currency parameter remains a small but real gap.

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

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

Schema description coverage is 0%, so the description must explain parameters itself. It ties productId to the target listing, but it does not explain the optional currency parameter at all, leaving its purpose and impact on returned data ambiguous.

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 ('Fetch'), a specific resource (a single Resollo product listing), and a required identifier (its ID). It is clearly distinguishable from siblings like searchProducts, which would search for products, and placeOrder, which would transact.

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 that this tool is for fetching details of one product when its ID is already known, which implies when to use it. However, it does not explicitly contrast this with searchProducts or placeOrder, nor does it provide explicit '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.

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutating nature is covered. The description adds significant behavioral context: the tool does not charge payment, the order is not complete after calling, a human must log in and pay separately, and the user should never be told the order is placed or paid. This provides meaningful operational caveats beyond what annotations supply.

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 a single dense paragraph with several critical warnings. It is front-loaded with the core action and caveat, but the whole block is long and mixes usage conditions, post-call instructions, authentication, listing type, and buyer consent into one unbroken run-on block. It earns points for packing value, but structure and readability suffer.

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 mutating order tool with 8 parameters and no output schema, the description covers the core operational caveats: payment not charged, manual checkout required, fixed-price only, auth header, and buyer-approval requirement. It doesn't mention return value or error/validation behavior, but the main contextual risks are handled strongly.

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

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

Schema description coverage is 0%, so the description carries the burden for parameter meaning. It clarifies that 'confirm' must be true and that product_id/shipment_method/payment_method are part of the required call, but it does not elaborate on format or domain meaning for fields like address_key, quantity, currency, or comment. For a tool with 8 parameters and no schema descriptions, the description compensates somewhat but leaves several parameters self-explanatory or undocumented.

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 a RESERVATION for the given product', and immediately distinguishes itself from a purchase by clarifying it does NOT complete a purchase or charge a payment method. This clearly differentiates it from what an agent might assume a 'placeOrder' tool does, and it is distinct from the sibling read-only tools getProduct and searchProducts.

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

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

The description provides explicit when-to-use guidance: only fixed-price listings can be reserved (not auctions), and it requires the buyer's explicit approval before calling (confirm must be true). It also tells the agent what to do after calling—tell the user the item is reserved and that they must complete payment themselves at resollo.com—and includes the auth header requirement. This goes beyond vague context and gives actionable conditions.

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 beyond the readOnlyHint by revealing that only active, purchasable listings are returned, never sold/expired/moderation-hidden ones, that semantic profile fields are deliberately not included, and that pagination is cursor-based. This gives the agent a much richer safety and behavior profile than 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 a single focused paragraph with no filler. Every sentence contributes either to scope, usage boundary, behavior, pagination, or authentication, and the most important primary purpose appears first.

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 9 optional parameters and no output schema, the description covers filters, pagination, scope, sibling routing, and auth well. It does not enumerate the per-result fields returned (only notes what is not returned), so an agent still has some uncertainty about the exact listing shape.

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

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

Schema description coverage is 0%, but the description compensates well by mapping keyword, category, price range, currency, seller location, and cursor to their intended semantics. Limit and sort are not explicitly explained, though sort is fully documented by the enum and limit by the schema defaults.

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 ('Search') and resource ('active, publicly available product listings on the Resollo marketplace'), and immediately distinguishes this from getProduct. An agent can tell this is the browse/filter search tool without ambiguity.

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

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

It states when to use the tool: to browse or filter by keyword, category, price range, currency, or seller location. It also explicitly says to call getProduct instead for full details on a specific product ID, gives clear pagination instructions via cursor, and notes that no authentication is required.

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