Host Gifts – hand-picked gift ideas

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the agent knows this is a mutating external operation. The description adds the editToken requirement, but does not explain mutation effects, duplicate handling, or required permissions beyond that token. With annotations covering the safety profile, this is adequate but limited.

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 is front-loaded in a short two-sentence description with no redundant explanation. The trailing 'OpenAPI: addWishlistItem' is a minor operational reference that adds little for an agent, but overall it is appropriately 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?

This is a mutation tool with nine parameters, low schema description coverage, no output schema, and several undocumented item fields. The description does not explain whether at least one identifying field such as url, asin, name, or catalogId is required, nor what happens after the item is added. For a tool of this complexity, the description is too thin.

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 only 22%, and eight of the nine parameters are undocumented. The description mentions editToken, which the schema already describes, and adds no guidance on how url, asin, name, title, catalogId, emoji, or searchKeywords should be used or combined. The description does not compensate for the low 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 states a specific verb and resource: 'Add an item to a wishlist.' This clearly distinguishes it from create_wishlist and get_wishlist. It does not explicitly contrast with create_and_fill or other sibling tools, so it falls short of a 5.

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 prerequisite 'Requires editToken from create' gives useful context for invocation. However, the description does not say when to use this tool versus create_and_fill, create_wishlist, or resolve_product, leaving alternatives unaddressed.

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 openWorldHint=true, so the agent knows this mutates state and searches externally. With no output schema, the description rightly discloses the returned fields (shopUrl share link, ownerUrl) and that each query is searched and added, but it says nothing about partial-failure behavior, idempotency, or whether the marketplace search could return empty results.

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 the return values, which is good. But 'curated host / hostess gifts gift wishlist' is garbled duplication, and the trailing 'OpenAPI: agentCreateAndFill' operation id gives an agent no actionable value.

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 10-parameter mutating tool with no output schema and thin annotation coverage, the description leaves too much implicit: six parameters (hostName, occasion, budgetBand, dietaryNotes, giftCategories, locale) are never discussed, and the required/optional ambiguity around marketplace is unresolved.

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 only 30% across 10 parameters, so the description carries a heavy burden it only partly meets: it names ASINs, keywords and search queries and bundles them as 'add in one call'. It says nothing about hostName, occasion, budgetBand, dietaryNotes, giftCategories, or locale, and never flags that marketplace is effectively required (0 required parameters at the schema level, yet the schema text calls it 'REQUIRED').

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 (create a curated host/hostess gift wishlist and fill it with ASINs/keywords/queries) and names the return payload (shopUrl, ownerUrl). The phrase 'Preferred agent path: create a wishlist and add ASINs...' implicitly differentiates it from the create_wishlist + add_wishlist_item combo, though it never names those siblings outright.

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?

'Preferred agent path' gives a clear recommendation for when to reach for this tool: whenever creation and population can happen together. It lacks any when-not guidance (e.g., when to fall back to create_wishlist then add_wishlist_item), and the odd 'gift wishlist' framing narrows the apparent scope without explanation.

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 declare readOnlyHint=false and openWorldHint=true, but the description goes further by enumerating the returned payload (id, editToken, ownerUrl, shopUrl, wishlist, storage). This is valuable since no output schema exists, and flagging editToken as something to persist signals its sensitivity. It still omits whether items are persisted server-side or what happens on repeated calls.

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

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

Two short sentences front-loaded with the core action and the key side-effect (save the token). "OpenAPI: createWishlist" is filler for an agent but minor. Nothing else is wasted.

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

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

The return-value list partially compensates for the missing output schema, but with 8 loosely-documented parameters at 25% coverage and a nested items array, the description leaves too much unexplained. An agent can call it with no arguments but cannot confidently populate items or occasion.

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 only 25% across 8 parameters, so the description needs to compensate and does not. Nothing explains items structure, giftCategories filtering behavior, budgetBand format, occasion semantics, or whether marketplace must be supplied despite zero formally-required params.

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 ("Create a host gift wishlist"), which is clearly distinct from the read-oriented siblings get_wishlist and get_catalog. It does not distinguish itself from create_and_fill, which sounds like it could also create a wishlist, leaving some ambiguity at the boundary.

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?

"Save editToken for add_wishlist_item" gives one concrete downstream workflow, which is genuinely useful routing. However, there is no guidance on when to use this versus create_and_fill, or whether a wishlist is required before other operations.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that results are paginated and curated, which is useful, but says nothing about page-size defaults, total counts, or the behavior of the redundant giftCategory vs giftCategories fields. "OpenAPI: getCatalog" is a docs pointer that adds no behavioral information.

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

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

Three short sentences with the resource description front-loaded and the invocation rule second. "OpenAPI: getCatalog." is low-value filler that does not earn its place for an agent caller, keeping this from a top score.

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 8-parameter read tool with no output schema and only half the parameters described, the description is thin: it never explains pagination semantics, the limit default of 24, or how the two gift-category parameters interact. An agent can call it correctly for the required-parameter path but will likely guess on filtering.

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 only 50%: limit, offset, giftCategory and occasion are undocumented in both schema and description. The only parameter guidance, "ALWAYS pass marketplace + locale," merely restates the schema's required list, and the description does nothing to disambiguate the overlapping giftCategory (enum) and giftCategories (comma-separated string) parameters — the single most confusing aspect of this 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 identifies the resource precisely — a paginated curated set of host gift starters — which is distinct from search-based discovery. It lacks an explicit verb (list/get) and never states what a 'catalog' entry actually is, but an agent can tell it apart from search_gifts and the wishlist siblings.

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

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

"Search remains primary discovery" implicitly steers agents to search_gifts for discovery and to this tool for curated browsing, and "ALWAYS pass marketplace + locale" is an invocation rule. However, there is no explicit statement of when this tool is preferred over search_gifts, nor any exclusion or precondition beyond the required parameters.

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 safety profile is covered. The description still adds real behavioral context the annotations don't: the exact shape of the response, the 'null until enrolled' state for trackingTag, and the per-marketplace tagConfigured flag. It omits any mention of failure modes or error signaling, which keeps it below 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 is front-loaded in the first clause, the field list is compact parenthetical shorthand, and the imperative 'Use this first' is positioned where it will be read. No filler sentences.

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

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

With no output schema, the description carries the burden of describing returns and does so field by field, including the nontrivial null-state caveat. Zero params and read-only annotations mean nothing else is needed 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?

Zero parameters, so the baseline is 4. The description spends its space on return semantics instead, which is the right allocation for a no-argument tool.

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 ('Health check for Host Gifts') and immediately enumerates what comes back, making it unmistakable versus siblings like list_marketplaces or get_catalog. An agent can identify the tool's role 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?

'Use this first' gives explicit ordering guidance relative to the other tools, which is the key decision an agent faces here. It does not, however, say when not to use it or explicitly name an alternative (e.g. 'use list_marketplaces for full marketplace detail'), so it stops short of the top band.

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 readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely new behavioral detail: it says which fields come back (buyUrl/linkType when available, ownerUrl, shopUrl), which matters because there is no output schema, and the conditional 'when available' warns the agent that some fields may be absent.

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

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

Two tight sentences with the action stated first and return shape second, no wasted prose. The trailing 'OpenAPI: getWishlist' is a spec cross-reference that adds little for an agent but is short enough not to hurt readability.

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 single-param read tool with read-only annotations and no output schema, this is nearly complete: it tells the agent what it returns and flags conditional fields. The only gap is a note on what happens for an invalid or missing id.

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 a single parameter with 100% schema description coverage ('Wishlist id'), so the schema fully documents it. The description adds nothing beyond 'by id' — no id format, prefix, or example — so this is the expected baseline for a fully-covered 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+resource combination ('Fetch a wishlist by id') that is clearly distinguishable from mutation siblings like create_wishlist and add_wishlist_item. It does not explicitly name an alternative reading tool (e.g. list_* vs get-by-id), but the intent is unambiguous.

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

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

There is no explicit when-to-use guidance, no mention of prerequisites, and no routing to or away from siblings such as add_wishlist_item or create_wishlist. The only usage signal is the implied 'by id' lookup, which is already carried by the schema.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful context that the result should be used to pick a marketplace for downstream tools, but it does not describe the return format (e.g., whether IDs or names are returned) or any other behavioral traits beyond what annotations provide.

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

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

Two concise sentences with zero waste. The core purpose is front-loaded, and the mandatory usage guidance follows immediately. Every sentence earns its place.

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

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

For a simple zero-parameter list tool with no output schema, the description provides enough context: it tells what is listed and how to use the result. It could be slightly more complete by specifying what the list contains (e.g., marketplace IDs vs. names), but nothing essential for calling 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?

The tool takes zero parameters, so there is nothing to document in the schema. The description correctly focuses on how the output should be used rather than parameter semantics. Baseline 4 applies for a 0-param tool.

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

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

States a specific verb ('List') and resource ('supported Amazon storefronts'), making the tool's function immediately clear. It does not explicitly name sibling tools it differs from, but the domain is distinct enough that an agent can distinguish it from wishlist/catalog tools 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?

Provides clear usage context: 'Agents MUST pick the user's marketplace and pass it on search/catalog/resolve.' This tells the agent when to use this tool and what to do with its output. It lacks explicit when-not-to-use or exclusion criteria, but the directive is strong enough for 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?

Annotations already establish readOnlyHint=true and openWorldHint=true. The description adds a meaningful behavioral detail beyond that: the returned buyUrl has trackingTag null until enrollment. It does not cover error cases or rate limits, but the added output-state context is useful.

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

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

Three short sentences, front-loaded with the core action and immediately followed by the required-parameter rule and output note. Every sentence contributes useful information with no waste.

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 8-parameter, open-world read tool with no output schema, the description covers the essential call path: input types, required params, and the buyUrl return. It is incomplete on how the optional occasion, budgetBand, and giftCategory parameters influence resolution, and it offers no failure or rate-limit context.

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 moderate (63%). The description restates the main documented inputs (ASIN, URL, keywords, marketplace, locale) and reinforces the two required fields, but it says nothing about occasion, budgetBand, or giftCategory, which are undocumented in the schema as well. It adds some clarity but does not compensate for the coverage gap.

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 (resolve) plus the three accepted input modes (ASIN, pasted Amazon /dp/ URL, keywords) and the output (buyUrl). That is clear, but it does not explicitly differentiate this from siblings like search_gifts, which could also consume keywords; an agent has to infer the boundary.

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 a clear prerequisite: 'ALWAYS pass marketplace + locale,' and the purpose sentence makes the general use case obvious. However, it never states when to prefer this over search_gifts or when not to use it, so it stops short of full alternative routing.

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 safety and open-web scope are covered. The description adds real context the annotations don't: results are scoped to the end user's marketplace, and marketplace+locale must always be supplied together. It says nothing about result volume, the purpose of limit, or failure behavior when a marketplace is unsupported, so it is additive but partial.

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

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

Two tight sentences with the core action front-loaded and the mandatory-parameter constraint immediately after. "OpenAPI: searchAmazon" is an internal routing hint of marginal value to an agent, which is the only wasted fragment.

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

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

For a 7-parameter tool with no output schema and two enums (occasion, giftCategory) whose effect on results is unexplained, the description does the minimum. An agent knows how to call it but not what the optional gift-filtering parameters actually change, nor when to prefer a sibling 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 description coverage is 57%, and the schema already documents q, locale, marketplace, and dietaryNotes with examples. The description reinforces the marketplace/locale pairing but adds nothing about occasion, giftCategory, or limit beyond their enum values. Baseline 3 is appropriate for a mid-coverage 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: "Search Amazon for hostess / dinner-party gifts on the user's marketplace." That is more specific than a bare "search" and scopes the domain (gift/entertainment shopping), which separates it from get_catalog or resolve_product. It stops short of naming a sibling it is explicitly not, so a 4 rather than a 5.

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 only directive is "ALWAYS pass marketplace + locale," which is parameter hygiene, not when-to-use guidance. With siblings like get_catalog and resolve_product in the same family, the description never says when to search here versus browsing a catalog or resolving a known product.

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