Dorm Kit – hand-picked gift ideas

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

With no annotations, the description carries the full burden; it does disclose the authorization requirement (editToken / X-Edit-Token) and its provenance, which is genuinely useful. However it says nothing about mutation semantics such as duplicate handling, whether the item fields are merged or replaced, or what constitutes a valid item payload.

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 followed by the prerequisite. Nothing is wasted, though the second sentence could have carried some of the missing payload guidance instead of stopping at the token.

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

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

For a 10-parameter mutation with no annotations, no output schema, and 20% schema coverage, the description is too thin: it omits the payload requirements, the success/return behavior, and error conditions such as an invalid or expired editToken.

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?

Ten parameters with only 20% schema description coverage, yet the description only names the two required ones (id, editToken). The eight item-identification fields (url, asin, name, title, emoji, notes, catalogId, searchKeywords) are undocumented in both schema and description, leaving the agent to guess which combination identifies an item.

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 ("Add an item to an existing dorm kit") and the word "existing" implicitly separates it from create_kit/create_and_fill_kit. It never explicitly says how it differs from sibling mutations, 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?

Gives the operative usage condition: the kit must already exist and the caller must hold an editToken obtained from create_kit / create_and_fill_kit. It names the sibling tools as prerequisite sources but offers no explicit when-not guidance or mention of search_kit_items for inspecting existing contents.

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?

No annotations are provided, so the description carries the full burden. It says the tool creates and fills but not whether an existing kit can be overwritten, whether filling is best-effort or atomic on partial failures, how queries/keywords/ASINs are combined, or that multi-item resolution may be slow or costly — significant gaps for a 10-parameter mutation.

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, front-loaded with the composite purpose and required inputs. The required-params clause is partly redundant with the schema's required array and field descriptions, but nothing else is wasted.

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

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

A 10-parameter composite tool with no annotations, no output schema, and 20% schema coverage needs far more than two sentences. The agent cannot tell what the tool returns (kit id? resolved items?), how fill sources interact, or how the dorm-context parameters affect results.

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 20% (just locale and marketplace), so 8 parameters are undocumented. The description names itemQueries, itemKeywords, and itemAsins but adds no meaning beyond the names — no precedence between them, no explanation of roomType/budgetBand/university/dormRules steering behavior — and "marketplace + locale REQUIRED" merely restates the 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 ("create a dorm kit and fill") and names the three fill inputs. The word "One-shot" gestures at the composite nature differentiating it from create_kit + add_kit_item, but the siblings are never named, so an agent must infer the distinction.

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?

"One-shot" implies this is the atomic alternative to the create_kit then add_kit_item sequence, but the description never says so explicitly, never states when to prefer the stepwise path, and never covers what happens if no item inputs are supplied.

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?

With no annotations, the description carries full burden, and it does disclose the return surface (id, editToken, ownerUrl, roommateUrl), which usefully signals a shareable owner/roommate link pair plus a secret edit token. It says nothing about auth requirements, whether item entries are validated or resolved against the catalog, failure behavior for bad asins, or rate limits.

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 action, then the return shape, then the hard requirement. Nothing is padded or redundant.

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

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

The return-field list partly compensates for the missing output schema, but for an 8-parameter creation tool with no annotations and 25% schema coverage, the description leaves too much open — especially the structure and validation of items and the meaning of the dorm-specific filters. Adequate to attempt a call, not adequate to call it correctly in edge cases.

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 25% across 8 parameters; only marketplace and locale are documented in the schema, and the description merely restates that they are required. The items array is the entire substance of "pre-filled" yet its nested fields (asin, catalogId, searchKeywords, etc.) have zero descriptions anywhere, and roomType, dormRules, budgetBand, and university get no semantics.

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 ... dorm kit wishlist") and distinguishes empty vs pre-filled variants. However, with a sibling named create_and_fill_kit, the empty-vs-pre-filled distinction is exactly where differentiation matters most, and the description never names or contrasts with that 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?

No guidance on when to choose this over create_and_fill_kit or how add_kit_item relates to the pre-filled path. The only imperative is "marketplace + locale REQUIRED," which is parameter documentation, not usage guidance.

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?

With no annotations at all, the description carries the full disclosure burden. It usefully reveals what the response covers (storage mode, trackingTag status, catalog count), which implies a read-only diagnostic, but it never states that it is non-mutating, needs no auth, or has no side effects.

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?

A single compact sentence that front-loads the key signal (service health) and then lists the specific data points. No waste, though it reads as a terse fragment rather than a complete sentence.

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?

There is no output schema, so the description is the only documentation of return values, and it enumerates the four things returned. For a zero-parameter diagnostic tool that is essentially complete, though it omits any indication of response shape or format.

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 and the schema is empty with 100% coverage, so there is nothing for the description to clarify. The baseline for a no-parameter tool 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?

The description names the resource and enumerates what it reports (service health, storage mode, trackingTag status, catalog count), but it is a noun fragment with no verb and never says it is a read-only status probe. An agent can infer the purpose from the name plus the field list, but the statement of intent is implicit rather than 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?

There is no guidance on when to call this tool, no prerequisites, and no alternative named. Health-check tools are somewhat self-evident, but the description does nothing to confirm or constrain usage.

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?

With no annotations, the description carries the full burden and does disclose real behavioral context: affiliate links currently omit ?tag= because Associates IDs are unregistered, exposed via tagConfigured=false, plus a directive never to invent placeholders. It does not state whether the call hits the network or caches results, which keeps it from 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?

Three short sentences, front-loaded with what is returned, then usage guidance, then the tag caveat. Every sentence carries distinct information an agent would otherwise get wrong.

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 compensates by naming the three returned fields and the tagConfigured flag. Ordering, total count, and whether results are static across calls are unstated, which is a minor remaining gap for a static reference 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to clarify on input side. Its field enumeration is bonus value aimed at output shape rather than parameter meaning.

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") and even enumerates the returned fields (id, domain, defaultLocale), which goes beyond the name. No sibling tool deals with marketplaces, so the agent can route to it unambiguously.

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?

"Prefer matching marketplace + locale to the end user" gives concrete downstream selection guidance, so the agent knows why it is calling this and how to choose among results. It stops short of naming explicit alternatives or when-not-to-call conditions, but for a zero-param enumeration tool little more is required.

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?

No annotations exist, so the description carries the full burden. It adds one genuinely useful behavioral fact — amazon.se links carry ?tag=sw-dormkit-21 when configured — but omits whether this is a network/lookup operation, what happens when multiple of url/asin/keywords are supplied (precedence), and any failure or not-found 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?

Three tight sentences, front-loaded with the core capability followed by the hard requirement and then the affiliate-tag nuance. Nothing is padded, though the amazon.se sentence reads as an aside rather than an integrated constraint.

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, no annotations, and 7 parameters at 29% coverage, the description is not fully adequate: it never says what the returned deep-link looks like structurally, how conflicting inputs are resolved, or what category/budgetBand do. It is enough to attempt a call, not enough to 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 29% across 7 params, so the description must compensate. It covers the intent of url, asin, keywords, marketplace and locale in prose, but category and budgetBand are never mentioned in either the schema or the description, leaving two parameters with zero documented meaning.

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 names a specific verb (Resolve) and the exact resource (ASIN / Amazon URL / keywords → buy deep-link), which is unmistakably distinct from all the kit-management siblings. It stops short of explicitly differentiating itself, but an agent can tell what it produces without opening the schema.

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

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

Usage is implied by the enumerated input types and the emphasized 'marketplace + locale REQUIRED', but there is no statement of when to prefer this over, say, list_marketplaces, nor any exclusion or prerequisite context. No sibling performs product resolution, so the routing risk is low, yet the guidance is only 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?

With no annotations, the description carries the full burden and does meaningful work: it discloses the output form (deep-links, optional catalog matches) and an important quirk (links omit ?tag= while tagConfigured=false). It stops short of stating side-effect-free/read-only behavior or failure modes, which keeps it from 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?

Four short sentences, front-loaded with purpose then return shape then constraints; no filler. Minor redundancy in repeating 'REQUIRED' that the schema 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?

Eight parameters, no output schema, so the description must characterize the response — and it does (deep-links plus optional catalog matches, tagConfigured=false). The missing piece is guidance on how the room/budget/dorm-rule filters influence results, which matters given no output schema to inspect.

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 100%, so the schema already documents q, limit, locale, marketplace, roomType, dormRules and budgetBand with examples and enums. The description only restates the requiredness of marketplace and locale, adding no semantics for the filter parameters. 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 ('Search dorm / back-to-school essentials') and immediately discloses the return shape (Amazon search deep-links, optional catalog matches). It is clearly distinguishable from create_kit/add_kit_item, though it never names the closest sibling (resolve_product) to route between item-level search vs. product resolution.

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 only implied by the domain framing; there is no explicit when-to-use statement or when-not comparison against resolve_product or the kit-creation siblings. The only guidance given is a parameter constraint (marketplace + locale REQUIRED), which is not the same as invocation guidance.

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