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 read-only/idempotent/non-destructive safety, and the description goes further by disclosing the unsupported-destination behavior (supported:false, South Korea/sanctioned countries) and the CAD fixed-rate charging quirk with charged.amountCents. That is genuinely useful behavior beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense, front-loaded sentences covering scope, output contents, and edge cases. There is a slightly garbled fragment ('charged.amountCents shows that') but no wasted sentences.

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 listing the returned fields (items, shipping, duties, tax, DDP total, supported flag, amountCents). Complete enough for an agent to call and interpret the result, though postal_code's optional role could be restated.

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% and the schema already documents ship_to format, postal_code's tax role, and quantities defaults. The description only adds the 10-product ceiling, so it does little beyond the schema — baseline 3 is appropriate.

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 ('Delivered (landed) cost') plus scope (up to 10 products, one destination) and enumerates the computed components. It is clearly distinct from siblings like create_checkout, get_product and search_products.

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 phrase 'the same numbers the store's own checkout charges' implies this is a cost-preview step relative to create_checkout, but no explicit when-to-use or when-not-to-use guidance is given. Usage is implied rather than stated.

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 declare readOnly/idempotent/non-destructive, yet the description still adds substantial behavior: a 20-item cap, next_cursor pagination semantics, USD integer-cent pricing, COA marking on artworks, DDP for US/CA versus DAP elsewhere, and that payment happens out-of-band via Stripe. That is materially more than the safety hints cover.

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?

Roughly four dense sentences, front-loaded with purpose and free of filler; each sentence carries a distinct fact (pricing, shipping terms, return shape, payment boundary). It reads as a single block rather than a structured list, which slightly hurts scanability but not content efficiency.

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 correctly compensates by naming the returned fields (price, artist, availability, lead time, next_cursor) and the result cap. It also covers cross-cutting concerns an agent would otherwise guess at: shipping incoterms and the fact that payment cannot be completed here. Minor gap: it never mentions the category filter or limit parameter behavior.

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 schema already documents query, ship_to, cursor, category and max_price_usd; the description adds only the ship_to-to-incoterm link and the cents convention for returned prices. It does not resolve the unit ambiguity of max_price_usd (schema says 'US dollars' while the prose says prices are integer cents), which is the one place extra clarity was needed.

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 NodajiMarket's curated catalogue of Korean handcrafted goods and artworks by named artists'), which an agent can immediately separate from nodajimarket_get_product or nodajimarket_get_artist. The scope (curated catalogue, named artists) is precise enough that no schema inspection is needed to understand intent.

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

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

It gives real routing context: nodajimarket_get_landed_cost is named as the authority for incoterm per destination, and nodajimarket_create_checkout is named as the payment path, with an explicit boundary that 'no tool here takes payment.' What it lacks is an explicit when-not rule (e.g. use nodajimarket_get_product when you already hold a product id), so the alternative-selection logic is inferred rather than stated.

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