NodajiMarket

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true) by disclosing the 30-minute link expiry, that the reservation is released if unpaid, that the tool does not itself take payment, and the Canada CAD fixed-rate behavior returned as charged_amount_cents. These are exactly the operational facts an agent cannot get from the structured fields.

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?

Five tight sentences, front-loaded with the core action and outcome, followed by expiry, payment boundary, currency note and idempotency. No sentence is filler; each carries a distinct operational 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?

For a mutation tool with no output schema, it covers the important behavior (expiry, reservation, payment boundary, idempotency) and even names one return field (charged_amount_cents). It stops short of describing error/failure responses or the full returned link structure, leaving a small gap.

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

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

Schema coverage is 75%, covering agent, ship_to and client_request_id, and the description reinforces client_request_id's retry semantics and explains that ship_to drives the Canada CAD conversion. It adds real meaning (currency/charging consequence of ship_to) beyond the schema, though it does not spell out the per-item quantity caps or items array shape.

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 precise verb and resource ('Reserve stock ... and return a Stripe Checkout link') along with the concrete two-step outcome. The sibling tools are all read/retrieval operations, and this is unambiguously the write/payment-initiation path, so it is easy to separate from them.

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 clear context for when to call it and an explicit exclusion ('Shipping address, name and phone are entered on the Stripe page — do not collect them yourself'), plus idempotency guidance for retries. It does not name a comparative alternative, but none exists among the read-only siblings, so the guidance is effectively complete.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds a genuinely useful behavioral caveat — that career details are 'as provided by the artist, not independently verified' — which is provenance context the annotations cannot convey. It stops short of describing pagination or failure behavior for an unknown slug.

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 densely packed sentence front-loads the resource type and then lists return contents, with a compact 'Read-only.' tag at the end. No filler, though the field list is long and could be trimmed where the schema/output already imply structure.

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 correctly carries the burden of enumerating return fields, and it does so thoroughly, including works and their availability. The only gaps are error behavior for invalid slugs and pagination of works, which are minor for a single-entity read.

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 0%, so the schema documents only type/pattern/length for artist_slug with no prose. The description compensates partially by naming 'slug' as the identifier, clarifying the parameter's role, but gives no format guidance (lowercase, max 40 chars) beyond what the schema's pattern supplies.

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 ('Profile of one artist by slug') and then enumerates exactly what is returned — names, tagline, story, career, portrait, seal, certificate, works with availability. No sibling tool covers artists, so there is no ambiguity to resolve, and an agent knows precisely what this fetches.

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 rather than stated: you call it when you have an artist slug and need the full profile. There is no explicit when-to-use, when-not-to-use, or pointer to an alternative (e.g. search_products vs this). Adequate but leaves the agent to infer the trigger condition.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond by disclosing currency behavior (Canada charged in CAD at a fixed rate, with charged.amountCents reflecting the actual charge), the shape of the returned figures, and an explicit failure mode listing unsupported destinations (South Korea, sanctioned countries). This is exactly the kind of behavioral context annotations cannot express.

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 dense, front-loaded sentences with no filler — the core cost definition comes first, then currency behavior, then the failure case. The middle sentence is slightly garbled ('at a fixed rate; charged.amountCents shows that'), a minor readability cost but not enough to derail an agent.

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

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

With no output schema, the description carries the return-value burden and does so by naming the returned components and the failure payload (supported:false with a message). Combined with the destination restrictions and currency handling, an agent has everything needed to call this correctly and interpret the result.

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%, and the description adds genuinely new semantics the schema lacks: which destinations are unsupported at all (South Korea, sanctioned countries) and the CAD fixed-rate charging behavior. It also restates the 10-product cap already in the schema's maxItems and says nothing about the quantities array, so it does not fully close 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 description states a specific verb and resource — the delivered (landed) cost for up to 10 products to one destination — and enumerates the components (items, shipping, duties estimate, tax, DDP total in USD cents). The phrase 'the same numbers the store's own checkout charges' implicitly separates it from nodajimarket_create_checkout, which actually places the order, so an agent can distinguish the estimate tool from the mutation 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?

Usage is implied rather than stated: the agent can infer this is a pre-purchase estimate versus create_checkout, but the description never explicitly says 'call this before checkout' or names alternatives. It does give one exclusion — unsupported destinations return supported:false — which is a failure condition rather than routing 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?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered; the description reinforces this with the domain-specific 'does not reserve or buy', which matters for a commerce tool. It also discloses the returned payload fields, useful since there is no output schema.

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, field list front-loaded and the usage hint placed last; no 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?

For a single-parameter, read-only lookup with rich annotations and no output schema, the description covers purpose, safety, returned fields, and id provenance — everything needed to invoke it correctly.

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% for product_id, so the description must carry the meaning; it supplies the id's source (search_products) and thus the format implicitly. It does not give length or shape details, but the origin hint compensates for the undocumented parameter.

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 ('Full detail for one product') and enumerates the fields returned, letting an agent distinguish it from nodajimarket_search_products at a glance.

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?

Explicitly tells the agent where the required id comes from ('Use the product id from nodajimarket_search_products'), which is genuine routing guidance. It stops short of stating when not to use this tool, but the read-only clarification removes the main ambiguity.

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

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

Annotations already establish read-only, idempotent and non-destructive behavior, and the description goes well beyond that: 20-result cap, next_cursor pagination, USD-cents pricing, DDP duties-included checkout, certificate-of-authenticity flagging, and the explicit statement that no tool here takes payment and a human completes Stripe Checkout. This is behaviorally rich.

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 sentences, front-loaded with purpose then returns, pricing/shipping and payment boundary. The customs/DDP detail is slightly tangential to searching but is defensible as shopping-context and does not bury the core action.

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

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

With no output schema, the description carries the return-value burden and does so: result count cap, returned fields, pagination cursor, currency unit, and the payment hand-off. Nothing needed to call and interpret the tool 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?

Schema coverage is 83% so the baseline is 3, but the description adds real meaning: pricing is in USD integer cents and results include price, artist, availability and lead time. It also confirms the free-text/Korean-or-English nature of the query, giving the agent guidance on how to phrase searches.

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 (Search) and resource (NodajiMarket's curated catalogue of Korean handcrafted goods and artworks), giving the agent a precise target. It distinguishes itself from siblings by content type (browse/search the catalogue) rather than a single record or artist.

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: this is the discovery entry point, with get_product/get_artist as natural follow-ons, but the description never explicitly says when to search versus fetching a known product. It does route the agent to nodajimarket_create_checkout for payment, which is a useful boundary but not a full when-to-use statement.

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