New Mum 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 declare readOnlyHint=false and openWorldHint=true, so the write/open-world nature is already covered. The description adds useful context beyond that: the tool performs searches and creates wishes in one call and returns shopUrl (share link) + ownerUrl, which matters since no output schema exists. It does not disclose side-effect details an agent would want for a mutation tool — partial-failure behavior if some ASINs/queries fail to resolve, duplicate-wishlist risk, or rate/latency implications of running searches inline.

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 the preferred-usage steer, followed by return values. 'OpenAPI: agentCreateAndFill' is a cheap but useful spec pointer rather than padding. Little waste overall.

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 correctly compensates for the absent output schema by naming the two returned URLs, and it conveys the create-plus-fill scope. For a 10-parameter open-world mutation tool it is still thin: no statement of the marketplace requirement, auth expectations, locale/marketplace interaction, or what a partially successful fill looks like.

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 30% schema description coverage across 10 params, the description does add meaning where the schema is silent: 'add ASINs / keywords / search queries' maps to itemAsins, itemKeywords, and itemQueries, clarifying that each query is executed and its result added. However seven params (occasion, budgetBand, giftCategories, hostName, dietaryNotes, locale, marketplace) get no mention, and the description omits that marketplace is effectively REQUIRED despite the schema reporting zero required fields.

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 ('create a curated new mum / postpartum gift wishlist') and adds the composite behavior ('and fill'), plus what it returns. The line 'Preferred agent path: create a wishlist and add ASINs / keywords / search queries in one call' implicitly separates it from create_wishlist + add_wishlist_item, though it never names those siblings directly.

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' is a real usage steer: it tells the agent to prefer this one-shot tool over the multi-step alternative. But it gives no explicit when-not-to-use, no named alternatives (create_wishlist, add_wishlist_item exist as siblings), and no prerequisites such as auth or required marketplace, leaving selection partly 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 this is a write operation (`readOnlyHint: false`) with open-world behavior. The description adds useful context by listing the returned fields and emphasizing that `editToken` must be retained for follow-up item creation, which is valuable workflow 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?

The description is short and front-loaded with the core action, then follows with return fields and a workflow instruction. The OpenAPI reference is minor filler 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 mutation tool with no output schema and eight parameters, the description covers return values and `editToken` reuse but omits critical input context. In particular, it does not flag that `marketplace` is required in the schema’s parameter description nor explain how to populate `items`.

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%, and the description adds no input parameter guidance beyond the return fields. It does not explain the `items` shape, the enum meanings for `occasion`/`giftCategories`, or the schema’s note that `marketplace` is 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?

The description gives a specific verb and resource: "Create a new mum gift wishlist." It also names the follow-up tool `add_wishlist_item`, helping distinguish it from read/list siblings, though it does not explicitly contrast with `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?

The description implies this is the creation step and explicitly tells the agent to save `editToken` for `add_wishlist_item`. However, it does not state when to use this versus `create_and_fill`, nor does it mention 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=true and openWorldHint=true, so safety is covered. The description's added value is limited to confirming pagination and the mandatory marketplace/locale pairing; it says nothing about what a page contains, result ordering, or what an empty catalog looks like — relevant for an open-world tool whose inventory varies by storefront.

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 fragments, with the resource and the mandatory-parameter rule front-loaded. 'OpenAPI: getCatalog' is low-value metadata for an agent, but it costs almost nothing and nothing else 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?

With no output schema, the description carries the burden of explaining what a page returns, yet it only says 'gift starters'. For an 8-parameter, open-world catalog tool with two overlapping category filters, it leaves meaningful gaps an agent would need to guess around.

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 50%, so the description should compensate at least partially; it only reiterates that marketplace and locale are mandatory and that results are paginated. The genuinely ambiguous pair — single-value giftCategory enum vs comma-separated giftCategories string — is left completely unexplained, as are occasion and q interactions.

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 resource and scope: a paginated, curated catalog of new-mum gift starters. It also implicitly separates itself from the search tool via 'Search remains primary discovery'. The verb is implied rather than stated ('Paginated curated ... starters'), which keeps 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 remains primary discovery' explicitly routes the agent to search_gifts for lookups and positions this tool as the browse/curation path, and 'ALWAYS pass marketplace + locale' gives a hard invocation rule. It doesn't spell out an explicit when-not condition (e.g. empty query, no curation available), so it stops at 4.

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 value by enumerating the response shape and flagging that trackingTag is null until enrollment. That null-until-enrolled note is genuine behavioral context an agent would otherwise misread as a failure. It doesn't mention latency, failure modes, or whether 'ok' can be false while sub-checks fail.

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, then the return payload, then the imperative 'Use this first.' — a sensible ordering with no filler. The trailing 'OpenAPI: getHealth.' is a minor reference artifact that adds little for an agent already invoking the tool by name.

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 contract itself and does so completely, including the nested marketplaces array and its three fields. Combined with annotations covering the read-only/open-world nature, an agent has everything needed to call and interpret this 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?

The tool takes zero parameters, so per the rubric the baseline is 4 and there is nothing for the description to disambiguate. No misstatements about inputs are present.

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 New Mum Gifts') and enumerates exactly what the call returns, so the agent knows this is a diagnostic endpoint rather than a data query. It doesn't explicitly contrast against siblings like list_marketplaces, but the return-field list makes its scope 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?

The terse directive 'Use this first.' gives a clear sequencing rule that an agent can act on, implying a preflight/verification role before other tools. It stops short of naming alternatives or stating when-not to call it, so it falls below a 5.

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 usefully adds that trackingTag is null until enrollment, which tells the agent the return may lack affiliate tagging. It does not cover precedence when multiple inputs are supplied or any failure/rate-limit 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?

One dense sentence plus a hard requirement and an API alias reference; no filler, and the core purpose is front-loaded before the constraints.

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 primary return field but leaves the gift-context parameters and input precedence unexplained. The critical invocation requirements (marketplace + locale) are stated, so an agent can call it correctly, but not optimally.

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%; the description clarifies the accepted URL shape (/dp/) beyond the schema's generic "Pasted Amazon product URL", and maps url/asin/keywords to input modes. However the three gift-context parameters (occasion, budgetBand, giftCategory) have no description in either place and their effect on resolution is unstated.

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) plus the three accepted input forms (ASIN, pasted /dp/ URL, keywords) and the output (buyUrl). This is clearly distinct from siblings like search_gifts or create_wishlist, though it never names them 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?

"ALWAYS pass marketplace + locale" gives a hard usage rule, but there is no guidance on when to prefer this over search_gifts or list_marketplaces, and no exclusions. Usage is only implied by the input modalities.

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 and network scope are covered. The description usefully adds that results come from the user's specific marketplace, but says nothing about result shape, pagination via limit, or how heterogeneous Amazon results are filtered to the gift domain.

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, purpose front-loaded, no filler. The trailing "OpenAPI: searchAmazon" is an implementation routing artifact that 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, two enums, and no output schema, yet the description never indicates what a result contains (product ids? prices?) or that results are meant to feed resolve_product or add_wishlist_item. Adequate to call the tool, thin for using the output downstream.

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 marketplace/locale emphasis merely restates what the schema already documents (including "REQUIRED") at 57% coverage. Nothing is said about how occasion or giftCategory enums interact with q, what dietaryNotes expects from the agent, or how limit caps results, leaving several parameters explained only by bare 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?

States a concrete verb and resource scoped to a category: "Search Amazon for new mum / postpartum gifts on the user's marketplace." No sibling in the list performs a query-style search (get_catalog and resolve_product are lookups), so the tool is distinguishable, but the description never names those siblings to make the boundary explicit.

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 parameter requirement, not usage guidance. There is no statement of when to choose this over get_catalog or resolve_product, nor any when-not condition or prerequisite context.

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