eglise.shop — Christian bookstore (FR/EN)

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

Annotations already flag a non-idempotent, non-destructive write, so the bar is lower; the description still adds the concrete capacity ceilings that annotations cannot express. It does not say what happens when a cap is exceeded (error vs. partial add), which is the one behavioral gap.

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 zero filler: the action and the id provenance come first, then the hard caps. Everything stated is actionable.

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 three-parameter mutation with a well-described schema, the description covers action, valid id sources and limits. The missing piece is failure behavior on cap violation and confirmation of what the response contains, though the currency field already notes the XOF price is always returned.

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 schema already documents cart_id, currency and quantity bounds in detail. The description still adds meaning beyond the schema by declaring the cart-level limit of 20 distinct books and by pinning the id source, which the nested items.id field leaves unqualified.

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 pairs a specific verb ('Ajoute') with a precise resource ('un ou plusieurs livres ... au panier') and even names the sibling tools that produce valid inputs (search_books, get_book). This makes it distinguishable from create_cart, which provisions the cart rather than filling it.

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 tells the agent what inputs to use (book ids from search_books/get_book) and states the operating envelope: 20 distinct books, 10 copies per book. It stops short of naming alternatives or exclusions (e.g., that remove_from_cart handles reductions, or that create_cart must run first), so usage is strongly implied rather than fully enumerated.

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?

Beyond the annotations (which only tell the agent this is a non-idempotent, non-destructive write), it discloses the anonymity of the cart, a concrete rate limit (10 per hour) and hard quotas (20 distinct books, 10 copies per book). It also discloses the return value cart_id, which matters because 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?

Three short sentences, front-loaded with purpose, then return contract, then limits. Every sentence carries distinct information with no padding or repetition.

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 one-parameter creation tool with no output schema, the description covers purpose, the return contract, rate limits and quotas — everything needed to call it correctly. Minor omissions such as cart lifetime/expiry or authentication expectations keep it from being fully complete.

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 single 'site' parameter is fully documented in the schema (100% coverage, enum with default and catalogue sizes). The description's restatement of the fr/en domain mapping adds nothing beyond that, so the baseline of 3 for high schema coverage 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 concrete verb and resource ('Crée un panier anonyme') plus the two storefronts it applies to, which immediately distinguishes it from read-oriented siblings like get_cart. The scope ('anonyme', site fr/en) is specific enough that an agent can select it 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?

The description routes the agent forward by explaining the returned cart_id is meant to be reused 'dans les autres outils du panier', which clarifies its position as the entry point of the cart flow. It stops short of explicit when-not conditions (e.g. what to do if a cart already exists) and names no sibling as an alternative, so it is clear context rather than full 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, non-destructive and non-openWorld, so the safety profile is covered. The description adds genuinely useful context beyond that: payments are handled externally via Stripe/Mobile Money links on an external page and the author pays themselves, meaning the tool never initiates a transaction.

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 content is front-loaded with the offer name and what it contains, and the payment constraint is stated last. It is dense with useful detail, though the full bilingual duplication roughly doubles the length for the same information.

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 zero-required-parameter, read-only informational tool with no output schema, the description tells the agent what data it will get back (plans, prices, lead times, inclusions, payment links) and where payment happens. Little else is needed 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 description coverage is 100% and both parameters (lang, site) are fully documented there with enums and defaults, so the description adds nothing about them. Baseline 3 applies when the schema does the heavy lifting.

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 a specific resource (author website offer) and enumerates what it returns: plans, prices in three currencies, lead times, inclusions and payment links. This clearly separates it from transactional siblings like create_cart or start_checkout, but it never names the closest sibling (get_isbn_offer) as a distinct alternative.

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: the agent can infer this is the lookup tool for author-website offer questions. There is no explicit when-to-use statement and no mention of how it relates to siblings such as get_isbn_offer or start_checkout, so the agent must infer the routing.

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 safety (readOnly, idempotent, non-destructive), so the description earns credit for adding real behavior: the fallback to newest catalogue items when no id is given, the fact the XOF base price is always returned alongside the requested currency, and that the link carries the currency to the site. It omits error behavior for an invalid id, but the added operational context is substantial.

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 what is returned, then the input options in a single compact sentence. Dense parenthetical asides make it slightly harder to scan, but no sentence 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?

With five optional parameters and no output schema, the description does the necessary work by listing the returned fields and the currency rule. The remaining gap — identifier precedence and behavior on a nonexistent id/slug — is minor for a read-only lookup.

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 already 100%, and the description still adds meaning: it explains that id comes from search_books and that omitting all identifiers changes the result set entirely. The url/site relationship is only echoed from the schema, so it is not a full 5.

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 ('Fiche complète d'un livre') and enumerates exactly what the record contains (résumé, auteurs, ISBN, éditeur, prix, lien). It also names search_books as the source of the id, so an agent can separate this detail-fetch tool from the search sibling without opening a 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?

It gives concrete invocation paths — id from search_books, or slug, or product URL — and even describes the degenerate case where no identifier yields the catalogue's latest releases. What it lacks is an explicit ordering/precedence when several identifiers are supplied, and it never says when to prefer this over search_books in so many words.

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 and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the base-currency XOF total is always returned regardless of the requested currency, and shipping fees are deliberately excluded (deferred to payment). It does not cover error cases such as an invalid or expired cart_id.

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 zero filler, front-loading what the tool returns before the currency behavior and the shipping exclusion. Every clause carries information.

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 must carry the return-value burden and does so reasonably (contents, subtotal, total, mandatory XOF total). Combined with annotations covering the safety profile and 100% schema coverage on inputs, the main remaining gap is error/edge-case behavior for an invalid or expired cart.

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 both cart_id and currency are already documented in the schema, including the enum list and the XOF-always-returned rule. The description restates the currency/XOF behavior but adds no new syntax or format detail, which is the expected baseline of 3 when the schema does the heavy lifting.

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 (panier) and enumerates the returned data (contenu, sous-total, total, plus a mandatory XOF total), so an agent knows exactly what this read tool yields. It does not explicitly differentiate itself from siblings like add_to_cart or start_checkout, but the resource noun makes the distinction obvious in context.

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: 'Les frais de livraison sont calculés au paiement' hints that shipping costs belong to the checkout step, weakly routing the agent toward start_checkout rather than this tool. There is no explicit when-to-use statement, no prerequisites, and no named alternatives.

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 and non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond them: the tool performs no payment (the author pays externally), and the offer includes delivery time and localized order pages. It does not describe rate limits or response shape, but that is minor given 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?

The content is front-loaded with the most important facts (what the offer is, prices, delivery). However, the description is duplicated wholesale in French and English, roughly doubling its length without adding information, which is a real conciseness cost even if intentional for i18n.

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 full schema description coverage on only two optional enum parameters, the description carries the burden for return content and does so adequately: it explains what the offer contains (ISBN-13, prices, delivery, order pages). It could be more explicit about the response structure, but the core is complete for a simple read-only lookup.

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 both 'lang' and 'site' (including enum values and the FR/EN site mapping), which sets the baseline at 3. The description does not explain the parameters at all, and its mention of order pages in FR/EN/ES/PT/DE could mildly mislead, since the enum accepts only fr and en.

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 resource — the ISBN-13 offer for authors via Lons Publishing — including prices, 6-hour email delivery and the order pages. An agent can tell it returns offer/pricing information rather than performing a cart or purchase action. It does not, however, differentiate itself from the sibling get_author_website_offer, which likely serves a parallel 'offer' purpose.

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: 'Read-only; the author pays on the order page' signals this is an informational lookup, not a purchasing step. No explicit when-to-use or when-not-to-use guidance is given, and no alternative sibling is named (e.g. get_author_website_offer) even though one exists.

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 (read-only, idempotent, open-world, non-destructive). The description adds valuable output context – article counts, slug, parent category – which is important because there is no output schema, though it omits pagination or sorting 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?

A single, front-loaded sentence that delivers purpose, scope, and output fields without waste. Every clause 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 read-only list tool with full parameter descriptions and safety annotations, the description covers purpose and output well. It could mention return ordering or pagination, but that is a minor 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 description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds no parameter-level meaning, which is acceptable given the high 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?

States a specific verb ('Liste') and resource ('catégories') for a named site, and names the sibling search_books as the consumer of the slug output. An agent can distinguish it from all cart/book siblings 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?

The description implies a use case by noting the slug is usable in search_books, but it never states when to call this tool versus alternatives, nor any exclusions. Usage must be inferred.

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, open-world, and non-destructive behavior. The description adds only that the order key appears in the confirmation email or URL, which is a useful sourcing hint but not a rich behavioral disclosure such as authentication/verification details, rate limits, or return 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?

Two short sentences front-load the purpose and then list prerequisites. Every clause earns its place, with no repetition or structural waste.

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 read-only status lookup, annotations cover safety and the schema covers the 'site' enum well. The description supplies required parameters and order-key origin, though without an output schema it could say more about the returned status payload.

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 low at 25%, so the description must compensate. It names the three required parameters and explains where to find the order key, but it omits the optional 'site' parameter and adds little semantic detail for order_id beyond 'numéro de commande'.

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 'Statut d'une commande', clearly identifying the order-status retrieval resource. It does not name a sibling or explicitly differentiate itself, but the resource is unambiguous and distinct from all listed cart, book, and checkout siblings.

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 lists the required inputs (order number, order key, billing email) and implies use when checking an order's status. However, it gives no explicit when-to-use/when-not-to-use guidance or named alternatives, so usage remains 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.

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered by structured data. The description adds useful scope detail (one book vs. the entire cart), but says nothing about behavior when both key and all are supplied, or about permission/auth requirements.

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 front-loaded sentence with no filler; the primary action precedes the alternative mode. Every clause 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 three-parameter destructive mutation with no output schema, the description covers both modes and the key's provenance. Minor gaps remain (precedence when both key and all are given, error behavior for an invalid key), but nothing critical 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 only 33% ('all' and 'key' are undocumented in the schema), so the description must compensate: it explains that 'key' is the identifier returned by get_cart and that all=true empties the whole cart. That meaningfully disambiguates both optional parameters beyond the bare schema types.

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 ('Retire un livre du panier') and distinguishes two distinct modes of operation (single item by key vs. full clear via all=true). An agent can tell it apart from siblings like add_to_cart and get_cart immediately.

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 states the two usage modes and the condition selecting each (key for one book, all=true to empty the cart), and routes the agent to get_cart as the source of the key. No explicit exclusions or error-case guidance, but context is clear.

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=true, so safety behavior needs no restating. The description adds useful context about output (XOF always returned alongside the requested currency, a link is produced, availability is reported), but says nothing about pagination limits or result ordering 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?

Two sentences, zero filler: the search axes come first, the return payload second. Every clause earns its place and nothing is repeated from the structured fields.

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, zero-required search tool with no output schema, the description covers purpose, searchable fields and return shape adequately. However, it never mentions that 'site' selects between two separate catalogs (~5 600 FR vs ~2 800 EN books) or that per_page caps at 20 — meaningful constraints an agent could miss.

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?

At 70% schema description coverage the baseline is 3, but the description adds real meaning beyond the schema: it specifies that keywords are matched against titre, résumé and auteur, and that the price filter is a 'fourchette' mapping to min/max. It still leaves the site (fr/en shop), orderby and page/per_page parameters unelaborated.

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 ('Recherche dans le catalogue d'eglise.shop') and enumerates the search axes (mots-clés, catégorie, fourchette de prix) plus the returned fields. This cleanly separates it from get_book (single record lookup) and list_categories (taxonomy listing) without ambiguity.

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 statement, and no sibling is named as an alternative (e.g. use get_book when the ISBN/ID is already known). Usage is only implied by the available filtering dimensions, which lands at 'implied 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?

Goes well beyond the annotations by disclosing link lifetime (30 min), a hard rate limit (5 links/hour), that the merchant sees no payment data, and that no order is created — exactly the operational context readOnlyHint/openWorldHint cannot convey. No contradiction with idempotentHint=false, since each call yields a fresh link.

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 short sentences, front-loaded with what is returned and how long it lasts, then the interaction model, then the limit. Every sentence carries a distinct fact; nothing is padding.

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 only two well-documented parameters, no output schema, and annotations covering the safety profile, the description fills the remaining gaps an agent needs: what comes back, its validity window, who pays, and the throughput cap.

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 already 100%, but the description adds real meaning: it explains the currency is forwarded to the site via ?wmc-currency= and that the XOF base price is always returned alongside. It does not name cart_id or spell out the currency enum's FR/EN variation, which lives in 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 concrete verb+resource: returns a payment link (valid 30 minutes) that opens the site's payment page for a given cart and currency. It also scopes what it does NOT do (no order created, no payment data seen), which separates it from the order/status siblings, though no sibling is named 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?

'À donner au client. C'est le client qui paie lui-même' makes the usage context clear, and 'Le connecteur ne crée aucune commande' tells the agent not to expect an order afterwards. There is no explicit pointer to which sibling to use instead or when to prefer order_status, so it falls short of 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 already declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds genuinely new behavior: the full status enum and the 7-day expiry rule ('expired after 7 days without confirmation'), which is not derivable from annotations or 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 dense sentences with no filler: the first gives purpose plus status values plus expiry, the second gives required inputs. Front-loaded with the most decision-relevant information.

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 two-parameter read-only lookup with no output schema, the description covers purpose, states, expiry, and required inputs. Minor gaps remain: error behavior for unknown submission_id and whether the email must match the original submitter are not stated.

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%, so the description must carry the load; it names both required parameters and clarifies that author_email is the submitting author's address, implying an identity/ownership check. It does not explain format constraints (e.g., the sub_ prefix pattern) or what happens on mismatch, so it only partially compensates.

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 ('Status of a book submitted with submit_book') and enumerates the exact possible return states, so an agent knows precisely what this returns. Naming submit_book distinguishes it from the similarly-named sibling order_status, which covers a different domain.

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 'submitted with submit_book' implies the prerequisite (a prior submission), which is useful context, but there is no explicit when-to-use/when-not guidance and no alternative tool named (e.g., order_status for purchases). 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 only flag a non-idempotent open-world write; the description goes far beyond that by disclosing the full human workflow (e-mail confirmation within 48 h, manual team review, nothing auto-published), the quota limits (3/day per author e-mail, 5/day per IP), 30-day duplicate refusal, and 7-day expiry of unconfirmed submissions.

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 English block is dense but front-loaded and every sentence carries operational weight (workflow, requirements, limits, expiry, terms link). The appended French paragraph duplicates the same content, which is defensible for a bilingual store but adds length.

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 17-parameter mutation tool with no output schema, the definition covers what an agent needs: consent precondition, required content constraints, quotas, failure/expiry semantics, a terms URL, and a pointer to submission_status for result tracking.

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 35% across 17 parameters, and the description compensates for the highest-risk ones: summary must be plain text, ≥200 characters, no HTML, at most 2 URLs; manuscript/cover must be public https links to pdf/epub/docx/audio and jpg/png/webp; rights_confirmed=true; author e-mail must be real. Several fields (price, currency, agent_name, notes, subtitle, isbn, category) remain undocumented in both places.

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?

Starts with a specific verb+resource ('Submit a book on behalf of its author') and scopes it to two named storefronts with concrete context (25% commission, paper/PDF/audio). It is immediately distinguishable from siblings like get_book, search_books or submission_status.

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 a hard precondition ('Only submit with the author's explicit consent, using their real e-mail') and routes tracking to the sibling 'submission_status'. It stops short of an explicit when-not-to-use-this-instead rule, but the preconditions and limit/duplicate rules define the usage envelope well.

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