Valentine's Day Gifts – hand-picked gift ideas

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

Annotations already declare this is a write (readOnlyHint=false) with open-world reach. The description adds real behavioral context beyond that — edit token provenance and the warning that token storage may mint a new id so bookmarks must be updated. It still omits duplicate-handling, failure modes, and any indication of return shape beyond the passing "prefer buyUrl in responses" note.

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?

Extremely dense and front-loaded — the action comes first, then prerequisites, then accepted body fields, then the token-storage caveat. The telegraphic phrasing ("Body: name/title plus…") is terse but readable; the OpenAPI name at the end is marginally expendable.

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 no output schema, the description covers prerequisites, most accepted item fields, and the token-rotation caveat. It still leaves emoji and id undocumented and says nothing about behavior on invalid identifiers or duplicate items, leaving visible gaps.

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 has to carry weight and largely does: it names name/title, asin, url (with the "pasted /dp" format hint), searchKeywords, catalogId, and editToken's required provenance. Only emoji and the id parameter go unmentioned, so this meaningfully compensates 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 first sentence gives a specific verb and resource ("Add an item to a wishlist") and the trailing OpenAPI operation name pins it to addWishlistItem. It doesn't explicitly distinguish itself from siblings like create_and_fill, which also appear to populate wishlists, 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?

"Requires editToken from create" is a useful prerequisite and implies this follows a create/mutate step, so usage is implied. But it never states when to pick this over create_and_fill or create_wishlist, and there are no exclusions or alternatives named.

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 usefully adds that this combines wishlist creation and item-filling in one call. It also discloses important return fields including id, editToken, ownerUrl, and shopUrl, with shopUrl described as a share link. It does not cover auth requirements, rate limits, or exact visibility/publishing behavior, but it adds 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?

The important points are front-loaded, but the text is fragmented and repeats return information: it first says it returns shopUrl and ownerUrl, then later lists id, editToken, ownerUrl, and shopUrl. The 'OpenAPI: agentCreateAndFill' reference is internal-looking and not obviously useful to an agent selecting 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?

For a 9-parameter, open-world write tool with no output schema and very low schema description coverage, the description gives useful return-field and one-call context. However, it omits meaning for three parameters and does not address permissions, side effects, or sharing implications beyond calling shopUrl a share link. It is workable but not fully complete.

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 schema description coverage at only 11%, the description must compensate, and it does explain that itemAsins are ASINs, itemKeywords are keywords, and itemQueries are search queries. It also maps recipientName, occasion, and categories, but leaves styleTags, budgetBand, and relationship unexplained. The 'not childName/ageBand' note is helpful but does not cover the remaining parameter gaps.

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

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

The description clearly states a specific verb and resource: create and fill a gift wishlist in one call, adding ASINs, keywords, or search queries. It distinguishes itself from the separate create/add siblings via 'Preferred agent path' and 'one call.' However, framing it as 'Valentine's Day' is narrower than the schema's occasion enum, which includes galentines, anniversary, and just-because.

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

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

It gives explicit preferred-agent guidance: use this one-call path rather than separate creation and item-adding steps. It also says to use recipientName, occasion, and categories rather than childName/ageBand. It does not explicitly name when not to use it versus create_wishlist or 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 the burden and does add real information: the returned fields, the need to persist editToken, and the 'storage is token' case where later mutations may rotate the id. Missing is any statement about whether creation is idempotent or what happens with an empty body.

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 the action and the return contract, then the field list, then the storage caveat — a sensible priority order. The telegraphic field-list sentence and the trailing 'OpenAPI: createWishlist' are terse but not wasteful.

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 creation tool with no output schema, describing the return fields and the id-rotation hazard is genuinely useful. But an agent still can't tell what `items` does, how it interacts with create_and_fill, or what the storage values other than 'token' mean.

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 compensate. It names 6 of 7 parameters but gives no meaning, format, or examples, and it omits the `items` array entirely — the one parameter with nested structure — plus never explains budgetBand or relationship formats.

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 Valentine's gift wishlist') and ties to the OpenAPI operation createWishlist. It does not, however, distinguish itself from the sibling create_and_fill, which appears to overlap in intent.

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 a downstream instruction ('Save editToken for add_wishlist_item') and an exclusion ('categories (not Santa childName/ageBand)'), which implies this is the Valentine's variant rather than a holiday one. It never states when to use this vs create_and_fill or why 0 required params is acceptable.

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

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

The description details dynamic behavior—specifically how output links are generated (ASIN links vs. search deep-links) based on the selected marketplace. This is critical context that goes beyond the simple readOnlyHint annotation.

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 information is highly concentrated, effectively merging pagination, scope, and operational constraints into a single dense paragraph without unnecessary filler.

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

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

Given the need to explain complex output logic and mandatory constraints, the definition is robust. It provides sufficient guidance to understand how this curated catalog tool differs from general search functions.

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?

While schema coverage is moderate (56%), the description adds vital semantic context to the required `marketplace` parameter, explaining how the choice impacts the final output links (ASIN vs. search links).

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 immediately identifies the resource ('curated Valentine gift starters') and distinguishes itself from the primary discovery mechanism ('search_gifts') and the search sibling.

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 provides a clear mandatory prerequisite ('ALWAYS pass marketplace + locale') and implicitly defines usage by contrasting it with the general discovery function of search_gifts.

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 known. The description adds genuine value by disclosing the full response payload without an output schema, including the nested marketplaces[] shape (domain, label, tagConfigured). It stops short of explaining what a failing paapi/storage status implies or what errors look like.

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 operation and immediately followed by the return contract. The phrase "for Valentine's Day gift inspiration" is marketing-flavored filler that adds no operational meaning, though it is not costly.

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 and no parameters, the description carries the return-value burden itself and does so thoroughly by naming every field. The remaining gap is the unresolved overlap with list_marketplaces, which matters because the tool is explicitly recommended as a discovery entry point.

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 for the description to disambiguate. Baseline of 4 applies; the field list is informational output detail rather than parameter guidance.

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 operation (health check) and enumerates the payload it returns (ok, storage, paapi, trackingTag, defaultDomain, catalogCount, tagConfigured, marketplaces[]), so an agent knows exactly what it gets. It is less clear against the sibling list_marketplaces, since both apparently surface storefront data and the description never explains the difference.

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 supported Amazon storefronts" gives one directive use case, which is more than no guidance. But it offers no exclusions and does not say why an agent should pick this over list_marketplaces for the same information, leaving the main routing decision 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 already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuine behavioral context beyond that: the response carries buyUrl/linkType fields only 'when available' (conditional fields) plus ownerUrl and shopUrl, which tells the agent to expect nullable enrichment data.

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 action and selector, followed by the return summary. The trailing 'OpenAPI: getWishlist' is a minor traceability tag with no real cost.

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 usefully supplies the return shape, and for a single-parameter read-only tool that covers what an agent needs to call it correctly. Only edge cases (not-found behavior, id format validation) are unaddressed.

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 the id as 'Wishlist id (short Redis id or t.* token)'. The description's 'by id' adds nothing beyond that, 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 (fetch a wishlist) plus the key selector (by id), which is clearly distinguishable from siblings like create_wishlist or add_wishlist_item. It also names the main return contents, so the agent knows what it gets back; it stops short of explicitly routing against 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?

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives such as create_wishlist or add_wishlist_item. The only inference available is that you need a wishlist id in hand, which is left 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 already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds useful context beyond annotations, including the exact fields returned, the equivalence to get_health.marketplaces, and the required downstream use of the selected marketplace.

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 are front-loaded with the tool's function, then the return fields, then the required workflow. Every sentence earns its place: purpose, data equivalence, and mandatory usage.

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 zero-parameter, read-only listing tool with no output schema, the description is complete enough. It names the returned fields, identifies an equivalent sibling source, and states the required downstream action.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter meaning because there are none to explain.

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: 'List supported Amazon storefronts,' and enumerates the returned fields (domain, label, currencyHint, tagConfigured). It also distinguishes itself from the sibling get_health by noting that get_health.marketplaces carries the same 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?

It explicitly tells the agent what to do with the result: pick the user's marketplace and pass it on search/catalog/resolve. It also points to get_health as an alternative source for the same data, so the agent can choose between tools with clear context.

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

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

Beyond the readOnly/openWorld annotations, it discloses meaningful behavior: server-configured Associates tags are used rather than invented, and the resolution strategy differs by market (curated /dp on amazon.se and amazon.com, search deep-links elsewhere). It stops short of describing failure modes or what happens when inputs are ambiguous.

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 one rule that matters most (always pass marketplace + locale). Some density is lost in stacked parentheticals, and the openAPI pointer adds little for an agent, but nothing is redundant enough to cut.

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 covers the return value well and the critical required params, but leaves four optional parameters (preferSearch, category, occasion, asin vs url precedence) undocumented. Adequate to invoke, not complete.

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 63% schema coverage, the description adds real meaning for marketplace (required, drives link strategy per storefront) and locale. But it never explains preferSearch, category, or occasion, and it references a `tag=` parameter that does not exist in the schema (additionalProperties: false), which could mislead a caller.

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 (resolve) and the exact input forms it accepts (ASIN, pasted /dp/ URL, keywords) plus the output shape (buyUrl, /dp link or romantic search). An agent can tell this apart from siblings like search_gifts or get_catalog without opening any 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 a hard operational rule — "ALWAYS pass marketplace + locale for the user" — and a precondition for tagging (omit tag= until real IDs are set). It does not, however, contrast itself with the sibling search_gifts tool or state when a caller should prefer that path, which is the one remaining gap.

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 readOnly/openWorld, and the description goes well past that: it discloses a conditional data source (PA-API products when configured for the default storefront, otherwise romantic-filtered search deep-link cards plus catalogMatches) and marketplace-dependent link generation. That runtime-behavior disclosure is exactly the context an agent needs before calling.

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 the purpose, and every clause carries operational content. The trailing 'OpenAPI: searchAmazon' fragment is a minor stylistic wart 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?

With no output schema and six parameters, the description compensates by sketching the return shape (products vs. deep-link cards + catalogMatches) and the preferred fields. Remaining gaps — what catalogMatches contains and how limit affects results — are modest but real.

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 67%; q, locale, and marketplace are already documented in the schema, and the description largely restates the marketplace rule. It adds no meaning for the undocumented 'occasion' and 'limit' parameters, so it does not compensate for the coverage gap — baseline 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 and resource — search Amazon for Valentine's / romantic gift ideas on the user's marketplace — and hints at two result modes. It does not distinguish itself from the plausibly overlapping siblings get_catalog and resolve_product, leaving the agent 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?

The description gives strong how-to directives ('ALWAYS pass marketplace + locale for the end user', 'Prefer buyUrl / trackingTag in results') but no when-to-use versus when-not framing. An agent facing get_catalog or resolve_product gets no routing help, so usage remains implied rather than explicit.

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