Lons Publishing ISBN

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds no behavioral context of its own - nothing about result shape, matching/narrowing behavior, or whether a non-matching keyword yields empty or fallback content.

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 no filler, and the core purpose is front-loaded. It is efficient, though the second sentence is a fragment that could carry a bit more useful detail without bloat.

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 trivial one-optional-param read tool with full annotations this is close to adequate, but with no output schema the description should at least hint at what comes back (list of Q&A entries, single answer, etc.). That gap is minor but real.

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 a single optional parameter and 100% schema description coverage (including examples like 'delivery', 'format', 'pay' in the schema itself), the schema carries the burden. The description's 'optional keyword filter' merely restates that the parameter exists and is optional.

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+resource: it answers common questions about the ISBN service. An agent can immediately tell this is a documentation/FAQ lookup, distinct from the sibling offer/link/info tools, though it never explicitly contrasts itself with 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?

'Optional keyword filter' implies you may call it with or without a query, but there is no explicit when-to-use guidance, no mention of what to do when no keyword matches, and no routing against sibling tools. Usage is only implied.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is fully covered by structured data. The description adds some value by enumerating what comes back (delivery delay, payment methods, contact), but says nothing about auth, rate limits, or whether the offer data is static or time-sensitive. Moderate credit against a low bar set by 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?

One dense sentence, front-loaded with the verb and the resource, then a well-ordered enumeration of the payload. No filler or redundant restatement of the tool 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, the description usefully compensates by enumerating the response fields, and the single optional parameter is fully covered by the schema. The main gap is operational context — when an agent should reach for this versus the faq sibling — which keeps it short of a 5.

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% with a full 18-value enum and a default of 'fr', so the single parameter is already fully documented. The description's only tie-in is mentioning 'supported languages' as returned content, which does not explain how the lang parameter changes the response. 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 ('Returns') and a precisely enumerated resource: the three ISBN packs (simple, barcode, premium), their USD/FCFA prices, inclusions, delivery delay, payment methods, languages and contact. This is far more specific than the sibling names (faq, get_order_link, get_required_book_info), but it never explicitly distinguishes itself from them, 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?

No explicit when-to-use or when-not-to-use guidance is given, and siblings are never named as alternatives. Usage is only implied by the payload description — an agent can infer this is the pricing/offer lookup versus faq or get_order_link, but must make that inference itself.

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, and closed-world. The description adds meaningful safety context beyond that: it never performs or initiates a payment and collects no payment data, which is exactly the compliance concern for a payment-link tool. It also clarifies what the return actually is (a link vs an order page).

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 purpose, then the variant semantics, then the safety caveat. 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?

With no output schema, the description appropriately explains the return (secure page/link) per payment method and covers the critical safety posture. It stops short of specifying URL format or whether the link expires, but it is complete enough 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 coverage is 100%, so the baseline is 3, but the description adds real semantic value for payment_method by explaining that card returns a Stripe Checkout link while mobile_money returns an order page containing the Mobile Money form. That goes beyond the schema's terse 'card (Stripe) or mobile_money'.

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: returns the secure page where the customer pays for an ISBN pack. It distinguishes the two return variants (Stripe Checkout link vs Mobile Money order page). It does not explicitly differentiate from the 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?

Usage is implied by describing the payment-method variants (card vs mobile_money), but there is no explicit statement of when to call this instead of get_isbn_offer or get_required_book_info, nor any prerequisites. Adequate but leaves routing 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 readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds the useful fact that these fields appear on the post-payment thank-you page, but says nothing about the shape of the returned list (field keys, labels, required vs optional), which is the behavior an agent actually needs.

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 well-formed sentence with the resource and its purpose front-loaded; no filler. It is arguably too terse given the missing return-shape detail, but nothing in it 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?

For a read-only, zero-required-parameter lookup with no output schema, the description tells the agent what it retrieves and why. The remaining gap is that it does not describe the structure of the returned field list, but the core need for calling the tool is covered.

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 only one parameter and the schema documents it fully (100% coverage, enum of 18 languages with default). The description never mentions the lang parameter or what changing it affects, so it adds nothing over the schema — 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 (lists) and resource (the fields the customer fills in on the thank-you page after payment), which is much more concrete than the tool name alone. It does not, however, contrast itself with the siblings (faq, get_isbn_offer, get_order_link), so an agent must infer that this is the post-payment form-field lookup.

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 clause 'so an agent can help prepare them in advance' implies the usage context (pre-payment preparation support), but there is no explicit when-to-use/when-not guidance and no mention of the sibling tools as alternatives. Usage is inferable rather than stated.

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