Teacher 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 mutation and external lookup are known. The description usefully adds that the response includes shopUrl (share link) and ownerUrl, which matters since there is no output schema. It does not disclose failure semantics — what happens if an ASIN or query fails to resolve, whether a partial wishlist is left behind, or whether the call is idempotent — which is the key unknown for a create-and-populate operation.

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, front-loaded statements: what it does, what it returns, and the preferred path. Minor waste in the duplicated 'teacher gifts gift wishlist' phrasing and the low-value 'OpenAPI: agentCreateAndFill' pointer, but nothing bloated.

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 and the description does cover the two return URLs, so the return side is adequately handled. However, with 10 mostly undocumented optional parameters and no required list (while the schema text marks marketplace as 'REQUIRED'), the description should at least explain the role of the curation inputs and any interaction between the three item-source parameters.

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%, so most of the 10 parameters carry no explanation anywhere. The description does clarify the three input modes (ASINs / keywords / search queries map to itemAsins, itemKeywords, itemQueries) and that queries are searched and added, which is beyond the schema. But subject, occasion, teacherName, budgetBand, giftCategories, and marketplace precedence/requirement are left unexplained.

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 and fill a curated teacher-gift wishlist in one call) and distinguishes the one-shot behavior from the stepwise path implied by siblings create_wishlist + add_wishlist_item. It doesn't name the siblings explicitly, and the phrase 'teacher gifts gift wishlist' is clumsy, but an agent can tell what it produces.

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 explicit positive guidance to use this over multi-call creation when the agent already knows ASINs/keywords/queries. There are no exclusions or conditions for when to fall back to create_wishlist plus add_wishlist_item (e.g., adding items later or building incrementally).

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 a non-read-only, open-world operation. The description adds useful behavioral context by listing key return fields and specifically noting that editToken must be saved for add_wishlist_item.

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 purpose, followed by return fields and the next-step token usage. The OpenAPI reference is minor but does not significantly detract.

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?

It partially compensates for the absent output schema by naming return fields, but with 8 parameters and only 25% schema coverage, the lack of parameter explanation leaves the definition incomplete 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?

Schema description coverage is only 25%, with 8 parameters, yet the description does not explain any parameter semantics. It adds no meaning for items, subject, occasion, budgetBand, teacherName, giftCategories, or the required marketplace field.

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 clear verb and resource: 'Create a teacher gift wishlist.' It is distinguishable from most siblings, though it does not explicitly clarify how it differs from 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 implies a workflow by saying 'Save editToken for add_wishlist_item,' but does not state when to use this tool instead of alternatives like create_and_fill, nor does it describe prerequisites or exclusions.

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 is covered; the description adds that results are paginated, which annotations do not convey. However it says nothing about ordering, page size limits (capped at 100 in schema), or whether the curated set varies by marketplace/locale — useful context that is left out.

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 resource and the mandatory-parameter rule; nothing is padded. The trailing "OpenAPI: getCatalog." is filler for an agent but negligible.

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 8 params, two overlapping category filters, and no output schema, the description should say what a catalog entry looks like and how occasion/category interact; it does not. The pagination mention partially compensates for the missing output schema but leaves an agent guessing on the filter semantics.

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?

At 50% schema coverage the description should carry weight for the undocumented params (q, limit, offset, occasion, giftCategory, giftCategories), but it only repeats that marketplace and locale are required, which the schema already states. It never clarifies the confusion between giftCategory (enum) and giftCategories (comma-separated string), which is the biggest semantic risk here.

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?

"Paginated curated teacher gift starters" names the resource and the result type (curated, paginated), and "Search remains primary discovery" implies the split from search_gifts. It lacks an explicit verb phrase (list/get/browse), but the resource and scope are specific enough to pick the tool over search_gifts.

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" explicitly positions this as a secondary, browse-style tool relative to search_gifts, which is real routing guidance. "ALWAYS pass marketplace + locale" gives a hard precondition. It stops short of stating exclusions (e.g. when not to bother with the catalog) but the context is clear.

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, and the description adds value beyond them by disclosing the return payload and the state nuance that trackingTag is null until enrolled. It does not cover auth requirements or latency, 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 purpose and the 'use this first' cue before the field list. The trailing 'OpenAPI: getHealth' is spec metadata of little use to an agent, a small bit 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 no output schema, the description compensates by naming every returned field, including the nested marketplaces[] keys. Still missing is any note on what a non-ok status looks like or how this differs from list_marketplaces.

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 disambiguate and the baseline is 4; the description correctly implies a no-argument call.

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 ('Health check for Teacher presents') and enumerates the exact response fields, so an agent can distinguish it from every sibling, none of which is a health probe.

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 a clear ordering cue for when to call it, but it never mentions alternatives such as list_marketplaces, which overlaps with the marketplaces[] payload, and states no when-not 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?

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 declare readOnlyHint and openWorldHint, so the safety profile is covered; the description adds real value on top by disclosing the return contract ('buyUrl', trackingTag null until enrolled) and pointing to the OpenAPI operation name. It does not say what happens on ambiguity or when nothing resolves, 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?

Three short fragments, front-loaded with the core resolution behavior, with no filler. The trailing "OpenAPI: resolveProduct" is a compact and useful pointer rather than padding, though the parenthetical about trackingTag is slightly dense to parse.

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 8 parameters and no output schema, the description partially carries the return burden (buyUrl, trackingTag) but leaves the optional enrichment parameters — occasion, giftCategory, budgetBand — unexplained in both schema and prose. An agent knows how to make a minimal call but not how to use the full parameter surface.

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 does much of the work; the description reinforces the three pickup parameters (url, asin, keywords) and the two required ones. It says nothing about occasion, giftCategory, or budgetBand, whose enum values carry no descriptions in the schema either, so the coverage gap is not compensated.

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 names a specific verb (resolve) and enumerates the accepted inputs (ASIN, pasted Amazon /dp/ URL, keywords) plus the output (buyUrl). That is far more concrete than the name alone. It stops short of naming how this differs from the sibling search_gifts, which is the main remaining 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?

"ALWAYS pass marketplace + locale" gives a hard usage constraint, and the enumeration of the three input modes implies which parameter to supply. There is no explicit when-to-use vs. when-not guidance, and nothing routes the agent between this tool and search_gifts or get_catalog.

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 and external-call profile is covered. The description adds little beyond a restatement of required params and an implementation hint ('OpenAPI: searchAmazon'); it says nothing about result volume, the limit cap, or how results are ranked.

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 with the core action and the mandatory-parameter warning front-loaded. The 'OpenAPI: searchAmazon' fragment is tacked on and doesn't help an agent decide or invoke, but it 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?

Seven parameters and no output schema, yet the description never characterizes the return (list of products? ASINs? prices?) nor the interaction between q and the enum filters. For a search tool with annotations covering safety, this is adequate but leaves real 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 57%, and the schema itself documents q, locale, and marketplace, plus enums for occasion and giftCategory. The description only echoes that marketplace and locale are mandatory, adding no meaning for subject, limit, or the enum semantics. Baseline 3 fits given partial 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?

States a specific verb and resource: 'Search Amazon for teacher appreciation gifts.' The OpenAPI pointer ('searchAmazon') confirms the operation. It does not explicitly distinguish itself from siblings like get_catalog or resolve_product, which an agent could easily confuse with a product search.

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' is a calling instruction, not a when-to-use rule. There is no guidance on when to pick this over get_catalog or resolve_product, and no exclusions or prerequisites are mentioned; usage must be inferred from the name.

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