Mother's Day Gifts – hand-picked gift ideas

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

Annotations already mark it as non-read-only and open-world; the description adds valuable behavior by noting the editToken requirement and that token storage may return a new id requiring bookmark updates. It does not cover invalid-token or duplicate-item behavior, but it adds meaningful mutation context 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?

The description is compact, front-loaded, and mostly waste-free. The 'OpenAPI: addWishlistItem' tail adds little for an agent, and the fragment style is terse, but overall it is appropriately sized.

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 9-parameter mutation with low schema description coverage and no output schema, the description covers the key precondition and token-rotation side effect. It still leaves gaps around the emoji parameter, identifier selection rules, and full return/error behavior.

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 22%, so the description must carry significant parameter meaning. It identifies name/title plus asin, url, searchKeywords, or catalogId, and gives a format hint for url, but it omits emoji and does not clarify identifier exclusivity or optionality.

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 Mother's Day wishlist. It is clear enough to distinguish from create_wishlist, but it does not explicitly route against siblings such as create_and_fill.

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 precondition, 'Requires editToken from create,' which helps frame usage. However, it does not state when to use this tool instead of create_and_fill or other sibling tools, leaving alternatives implicit.

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 supply readOnlyHint=false and openWorldHint=true, so the description must carry most of the burden. It does usefully disclose the returned fields including the sensitive editToken and ownerUrl, but says nothing about authentication requirements, partial-failure behavior when an ASIN or query fails, or what 'curated' defaults get applied when no inputs are given.

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 one-shot value proposition. The only redundancy is restating shopUrl/ownerUrl twice (once as the headline return, once in the full return list), which is minor.

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

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

The tool has 10 parameters, zero required, and no output schema — meaning an agent could invoke it with an empty body and the description never explains what defaults apply, what the occasion parameter does when omitted, or why marketplace is effectively required despite not being marked so. It covers the happy path but leaves real invocation ambiguity.

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 30% across 10 parameters, so the description needs to compensate. It names three input families (ASINs, keywords, search queries) but is silent on locale, occasion, styleTags, budgetBand, relationship, and recipientName — several of which are self-evident enums, blunting but not removing the 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?

States a specific verb and resource — create a curated wishlist and add items in one call — and the 'one call' framing distinguishes it from the create_wishlist + add_wishlist_item sibling pair. However, the description frames the tool exclusively as Mother's Day (Mors dag), while the schema's occasion enum also allows birthday, just-because, and other, so an agent may wrongly conclude the tool is Mothers-Day-only.

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: create a Mother's Day wishlist and add ASINs / keywords / search queries in one call' gives a clear selection signal against the multi-step create_wishlist path, though it never names the sibling explicitly or states when-not to use it (e.g., appending to an existing wishlist should use add_wishlist_item).

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, so the description carries most of the load and does deliver: it enumerates the return fields and discloses the non-obvious id-rotation behavior when storage is 'token'. It omits auth/rate-limit expectations, which keeps it short of a 5.

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

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

Front-loaded with the action, then return values, then the critical id-rotation caveat — good ordering with little waste. The trailing 'OpenAPI: createWishlist' is filler that adds no actionable information.

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

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

For a mutating, open-world creation tool with no output schema, the description does cover return shape and a tricky state behavior. However, half the input parameters are undocumented anywhere and there is no mention of authentication or what happens to caller-supplied items, leaving real gaps before an agent can call it confidently.

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 50% across 8 parameters, and the description mentions none of them — items, occasion, styleTags, budgetBand, locale, and recipientName are left entirely to the schema, where several have no description at all. For a low-coverage schema the description should compensate and does not.

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 Mother's Day gift wishlist') and the title reinforces it. It does not distinguish itself from create_and_fill, which from its name appears to be a competing creation path an agent must choose between.

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

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

The description gives downstream workflow guidance ('Save editToken for add_wishlist_item'), which implies this is a two-step create-then-fill flow, but it never says when to prefer this over create_and_fill or whether it requires an existing account. Usage is inferable rather than 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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses non-obvious behavior: results are paginated, and item output differs by marketplace (amazon.se yields /dp/ASIN links when ASINs exist, other marketplaces fall back to search deep-links with catalogMode=search-ideas). That is real context an agent could not infer from annotations or schema. It does not mention rate limits or empty-result behavior.

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

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

Four short sentences, front-loaded with purpose followed by marketplace caveat, the hard requirement, and sibling routing. Minor waste in the 'OpenAPI: getCatalog' pointer, but no sentence is padded.

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

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

No output schema exists, yet the description sketches the return shape (paginated items, marketplace-dependent link format), and required parameters are called out. For a read-only browse tool the remaining gap is filter semantics, which is a parameter-level rather than a completeness failure.

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

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

With 10 parameters and only 40% schema description coverage, the description needs to compensate, but it only addresses marketplace and locale — and the marketplace semantics it restates are already in the schema's own description. The eight filter parameters (q, ids, limit, offset, interest, occasion, styleTag, budgetBand) are undocumented in the description, leaving the agent to infer filtering behavior from enum values alone.

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

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

The description establishes a specific resource ('curated Mother's Day gift starters') and scope ('paginated'), and explicitly names search_gifts as the primary discovery path, so the agent can distinguish it from that sibling. The term 'starters' is slightly vague about what an item actually is, keeping it just 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?

'Search (search_gifts) remains primary discovery' gives explicit routing against the most likely alternative, and 'ALWAYS pass marketplace + locale' states a hard precondition. It does not state the positive trigger for choosing this tool (e.g. browsing curated gift ideas rather than searching), so it is clear context without full when/when-not coverage.

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 bar is lower; the description still adds real value by naming each returned field and flagging that trackingTag is null until real Associates IDs exist. It omits details like whether storage/paapi are booleans or objects and what happens on failure, so it is not exhaustive.

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 compact sentences, front-loaded with purpose and usage before the field list. The trailing 'OpenAPI: getHealth' is marginally useful but reads as generated 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 no output schema, the description carries the return-shape burden and does list all fields plus one caveat, which is adequate for a trivial zero-param probe. It stops short of explaining what storage/paapi values signify or the tool's relation to list_marketplaces, leaving a small 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?

Zero-parameter tool, which sets the baseline at 4. The description correctly implies no input is needed, and nothing misrepresents the empty 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 ('Health check for Mother's Day Gifts') and enumerates the returned fields (ok, storage, paapi, trackingTag, defaultDomain, catalogCount), so the agent knows exactly what this returns. It does not explicitly contrast with siblings like list_marketplaces or get_catalog, even though the title says 'Health & marketplaces'.

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 to discover service status' gives a clear ordering/context cue that no sibling provides. There is no when-not guidance or named alternative, but the entry-point framing is strong enough for practical selection.

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 safety is covered. The description adds genuine value beyond that by naming the response contents (items with buyUrl/linkType when available, plus ownerUrl and shopUrl), which matters since no output schema exists. It stops short of describing not-found behavior or field optionality rules.

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 retrieval scope front-loaded, followed by return-value hints. The trailing "OpenAPI: getWishlist." is spec trivia that doesn't help an agent decide or invoke, a small piece of 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?

With a single well-documented parameter and no output schema, the description compensates reasonably by enumerating the main returned fields. Gaps remain around missing-wishlist behavior and whether items can be empty, but nothing critical to invoking it correctly is absent.

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 id property already documents the short Redis id / t.* token formats. The description only restates that lookup is by id, adding no syntax or format detail beyond the schema. Baseline 3 applies 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: "Fetch a Mother's Day wishlist by id." This clearly separates it from the write-oriented siblings (create_wishlist, add_wishlist_item, create_and_fill). It doesn't explicitly name an alternative, but the retrieval framing 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?

Usage is implied by "by id" — the agent knows it needs a pre-existing wishlist identifier rather than a search query. However, there is no explicit guidance on when to call this versus siblings like get_catalog or search_gifts, and no prerequisites or failure conditions 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=true, so safety is covered; the description adds that this is a plain GET and that its result is a prerequisite input for other calls. It does not disclose whether results are paginated, cached, or region-restricted, so the added context is real but modest against an already-declared read-only profile.

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

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

Two sentences, front-loaded with the action and endpoint, followed by the operative constraint. No filler and every clause carries information the agent needs.

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 parameters, no output schema, and read-only annotations, the description supplies the two things an agent actually needs: what comes back and why it must be called first. It would be fully complete if it addressed the failure case where the user's marketplace is not in the returned list.

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 input parameters, so the baseline is 4 and nothing in the schema requires explanation. The description does useful extra work by naming the fields each marketplace record carries (domain, label, tagConfigured), which matters because there is no output 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 ("List supported Amazon storefronts") plus the endpoint, and enumerates the returned fields (domain, label, tagConfigured), which cleanly separates it from siblings like get_catalog and resolve_product. An agent can tell immediately that this is the enumeration/discovery call, not a data-fetch call.

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 second sentence explicitly prescribes usage with "Agents MUST pick the user's marketplace and pass it on search/catalog/resolve," making the workflow ordering unambiguous and naming the consuming siblings. It stops short of saying when not to call it or how to handle a user whose marketplace is absent from the list, so it is clear context rather than a full when/when-not rule set.

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

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

Annotations already mark this as readOnly and openWorld, but the description adds useful behavioral context beyond them: it will not invent Associates tags and omits tag= until real server-configured IDs exist. It also discloses that marketplace choice changes the output from a /dp link to a Mother's Day search deep-link.

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

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

The description is short and front-loaded with the core conversion behavior and required parameters. The trailing 'OpenAPI: resolveProduct' reference is slightly extraneous but not disruptive.

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 resolver with no output schema and nine parameters, the description covers the main input modes, required parameters, output link types, and tag behavior. It does not explain the optional refinement parameters (styleTag, budgetBand, occasion, preferSearch), which is a remaining gap but not a fatal one.

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 description maps the three main input modes to url, asin, and keywords, and emphasizes that marketplace and locale are always required. But with schema coverage at 56%, it leaves occasion, styleTag, budgetBand, and preferSearch without added meaning beyond their enum values.

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 conversion target: resolve an ASIN, pasted Amazon /dp/ URL, or keywords into a buyUrl, including the two possible output forms (/dp product link or Mother's Day search link). This is clearly distinct from sibling tools like search_gifts or suggest_gifts, though no sibling is named explicitly.

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

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

It gives the concrete input modes (ASIN, pasted URL, keywords) and a required-parameter instruction: 'ALWAYS pass marketplace + locale.' However, it does not state when to prefer this tool over search_gifts, suggest_gifts, or get_catalog, so the selection guidance is only implied.

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 readOnly and openWorld, and the description adds genuinely useful behavior: PA-API products when the default storefront is configured, otherwise Mother's Day deep-link cards plus catalogMatches. That dual-mode return path is exactly the kind of context annotations cannot express, though rate limits and result-count behavior are unmentioned.

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, front-loaded with purpose then behavior then the mandatory-parameter rule. The trailing 'OpenAPI: searchAmazon' is a low-value pointer but costs little.

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 tool with no output schema, the description does the important work of explaining what comes back in each mode. The gap is the filter parameters (budgetBand, occasion, interest) whose semantics are left entirely to enum values.

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 63%, so the schema already documents q, locale, styleTag, and marketplace. The description reinforces marketplace/locale as mandatory and 'for the end user', which adds a real directive, but says nothing about limit, budgetBand, occasion, or the interest/styleTag alias.

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 — searching Amazon for Mother's Day gift ideas on the user's marketplace — plus a fallback behavior. It is clear on its own, but never names or contrasts with the obvious sibling suggest_gifts, so sibling differentiation is left to inference.

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?

'ALWAYS pass marketplace + locale for the end user' is a parameter directive, not guidance on when to pick this over suggest_gifts or get_catalog. The condition that changes behavior (default storefront configured vs not) is described as an output consequence rather than a reason to choose the 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=true, so safety is covered. Beyond that the description adds only the identity claim ("alias of search_gifts") and a parameter reminder — nothing about what a call actually returns (curated ASIN /dp links vs. marketplace search deep-links), which the schema hints at but the description never surfaces.

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 identity and purpose, with the critical marketplace/locale constraint called out in caps. No filler, though the reminder duplicates what the required-array already enforces.

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?

A 7-parameter tool with four undocumented enum/optional params (occasion, styleTag, budgetBand, limit), no output schema, and only an alias reference as behavioral context. An agent could not tell what differentiates the gift-suggestion output or how the optional filters change it.

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 43% across 7 parameters with 3 enums. The description only reminds the agent to pass marketplace and locale (both already marked required) and says nothing about q, limit, occasion, styleTag, or budgetBand, so it fails to 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?

States a specific verb and resource (suggest Mother's Day gift ideas for a query) and explicitly names the sibling it mirrors ("Alias of search_gifts"), so an agent can place it relative to search_gifts. It stops short of saying how it differs from that sibling, which keeps it from 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?

"for a query on the user's marketplace" plus the Mother's Day framing implies when to reach for it, and "ALWAYS pass marketplace + locale" gives a hard usage constraint. But calling itself an alias of search_gifts with no when-to-prefer-either guidance leaves the agent to guess which of the two to call.

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