artemis

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds real behavioral context beyond them: how margin is computed (quantité × (prix de vente HT − PAMP)), that comparer=an_dernier produces écarts and *_avant fields, that the current month is returned separately, and that selected products are surfaced for verification. It does not disclose broader limits such as data freshness or row caps.

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 main purpose and metric definitions are front-loaded and every sentence carries information about scope, formulas, or filters. It is dense and somewhat long for a single paragraph, but appropriately sized for a 15-parameter analytical tool.

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?

Given the complexity and the absence of an output schema, the description explains the main return values (units, revenue HT/TTC, margin in euros and percent, references sold) and the comparison fields. It leaves some gaps around the exact shape of the separate current-month block and the full comparison output, but covers enough for an agent to call 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 coverage is 100%, so every parameter is already documented in the schema. The description synthesizes the filter set (laboratoire, famille, groupe, produit) and the comparer behavior, but this largely repeats schema content rather than adding new semantics. Baseline 3 is appropriate 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?

States a specific verb and resource: month-by-month pharmacy sales, revenue and margin, with explicit metrics (unités, CA TTC/HT, marge_eur, références vendues) and filter options. The intended scope is clear, but differentiation from siblings like ventes_mois or palmares is only implicit; the only sibling named is top_ventes as an analogy, not as an alternative to choose between.

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 an explicit trigger ('À utiliser quand le pharmacien demande l'évolution de ses ventes ou de sa marge, compare un mois ou une saison à l'an dernier') and clear exclusions (medical questions, posology, patient records, market prices). Alternatives among sibling tools are not named, so it stops short of 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?

Goes well beyond the readOnly/idempotent annotations: discloses typo tolerance and word-order insensitivity, the proximity/correspond fallback behavior, molecule expansion to all brands, anomaly listing with sorting by revenue, and the 50-row cap with page paging. Doesn't describe the exact shape of returned objects, but annotations plus this text cover most of what an agent 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?

Front-loaded correctly with the resource and fields, but the prose is a single dense run-on mixing search semantics, anomaly semantics and usage rules, and the closing English sentence 'Searches the pharmacy's own catalogue by name or CIP code, typo-tolerant' duplicates information already given in French.

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 an 11-parameter read tool with no output schema, the description covers what comes back (CIP, nom, laboratoire, famille, DCI, prix, stock, dernier mois vendu), the row cap, the paging mechanism and the anomaly taxonomy. Nothing an agent needs to call it correctly 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 already 91%, so baseline is 3. The description still adds meaning: it explains that q is optional when molecule/anomaly/type_soin is supplied, that multiple words can come in any order with software abbreviations, and gives a concrete molecule example ('molecule=paracetamol rend tous les médicaments qui en contiennent').

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?

Opens with a specific verb and resource ('Trouve des produits de l'officine') and enumerates the searchable keys (nom, CIP, molécule) plus the returned fields. It is clearly distinguishable from siblings like fiche_produit or lister.

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 when to use it ('avant tout outil qui prend un code CIP', when the pharmacist names a product or asks what is wrong in the software) and when not to (medical questions, posology, patient records, market prices). Also names the alternative route implicitly via fiche_produit.

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 description's job is to add operational detail, and it does: a 200-row cap, the response summary buckets (already out of stock, 7 days or less, set aside), tri=debit prioritising high-volume items to order first, and the fact that jours_min inverts the whole query and regroups excess by laboratoire and famille. It also warns that season-end and one-off sales are set aside, which materially changes how results should be read.

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 substance is front-loaded and dense with no filler, but the clauses are strung into long run-ons that mix the two modes, the summary, the filters and the exclusions in one block. The trailing English sentence 'Products about to run out, given their recent sales, with a summary.' restates the opening in another language and does not earn 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 15-parameter, no-output-schema analytical tool, the description covers both modes, the summary contents, the row cap, the grouping, and the when-not-to-use cases. Minor gaps remain: it does not reconcile the stated 200-row ceiling with the much lower default of 50, nor explain how 'mois pleins' is computed, but none of these would cause a wrong 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 73%, so the schema carries much of the load, yet the description adds real meaning for the non-obvious parameters: ruptures value semantics ('exclure montre ce qui va tomber à zéro, seules ce qui manque déjà'), tri=debit, and jours_min with a concrete example (jours_min=180 ≈ six months of stock). It names the filter dimensions (laboratoire, famille, groupe) but leaves molecule, type_soin, generiques, associations and sous_rayon entirely to 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?

The definition identifies the resource and the two analysis modes precisely: products sold over N full months whose stock covers at most X days, or, with jours_min, the inverse (excess stock). It deliberately carves out stock_dormant for products that no longer sell at all, which separates it from its closest sibling. It opens with an oblique nominal phrase ('Ce qui va manquer') rather than a verb+resource statement, but the intent is unambiguous by the second clause.

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 explicit user-intent triggers ('le pharmacien demande ses ruptures, ce qu'il doit commander, ce qui risque de manquer, ou ce qu'il a en trop') plus a named alternative for the adjacent case ('ce qui ne se vend plus du tout : stock_dormant'). It also states exclusions ('Pas pour une question médicale, une posologie, un dossier patient ni un prix du marché'), which no sibling name alone would convey.

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 genuinely new behavioral context: scope is limited to officine prices, market/zone prices are unknown here, and proposed prices are not advised. It does not cover result size or latency for up to 20 products, hence not 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?

The content inventory is front-loaded and useful, but the text is a single very long sentence that bundles return fields, usage rules and caveats together. The trailing English sentence ('Full sales, stock and margin detail...') duplicates the French description and adds no new information, which is avoidable 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?

There is no output schema, yet the description enumerates the return payload in detail (per-product figures, totals, averages, cover in days, rank only for a single product, aggregated family totals for multiple). Combined with annotations covering safety, an agent has everything needed to call it 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 only 50%: cips is documented in the schema, mois is not. The description compensates by explaining that the tool returns 'N mois de ventes' and that multi-product totals are computed 'mois par mois', giving the agent the meaning of the unlabeled parameter. It still does not state the 1-24 range or default 12 in prose, but those are 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?

Names the resource (produit) and enumerates precisely what the tool returns: identity, catalogue price, PAMP, margin rate, stock state, N months of sales, totals, averages, cover in days and family rank. It also contrasts with siblings by pointing to chercher_produit for CIP codes and by excluding pricing/market questions, so an agent can tell it apart from ventes_mois, palmares or stock_dormant.

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?

Explicit when-to-use ('détail d'une référence précise, en comparer quelques-unes ou additionner une famille de produits') plus explicit when-not ('Pas pour une question médicale, une posologie, un dossier patient ni un prix du marché'). It even names the missing capability needed instead (a pricing tool tracking the pharmacy's zone), which is strong 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?

The annotations already establish read-only, idempotent, non-destructive behavior, and the description adds important operational context beyond them: the period logic, row cap of 200, comparison behavior, pharmacy-only pricing scope, and the limitation that it does not advise on proposed prices.

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 description is front-loaded with the core scope and output metrics, and its length is justified by the tool's complexity. It loses a little sharpness from the redundant final English sentence and the somewhat verbose pricing caveat, but the structure remains usable.

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 eight parameters, the description still explains the returned metrics, period scope, comparison behavior, row limit, and usage boundaries well enough for an agent to select and 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 coverage is high at 88%, so the schema already documents most parameters. The description still adds useful meaning about how period selection and comparison work together, especially that comparer adds compared-period values and evolution of sales and purchase price per product and for the whole range.

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: returning a laboratory's full product range in the pharmacy over a period, product by product, including references with no sales and aggregate totals. It names the exact metrics returned and distinguishes this from adjacent tools by emphasizing laboratory-level range analysis rather than generic product listing or medical questions.

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 explicit when-to-use guidance: preparing a laboratory meeting or reviewing its range. It also gives explicit exclusions: not for medical questions, dosage, patient files, or market pricing, and notes that comparing two laboratories requires two calls.

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 and non-destructive, so the safety profile is covered. The description adds useful behavioral context beyond that: a hard result cap of 150 lines, that counts of references/sold/stock are returned, and what codes_changes reports (old and new code, dates). It does not discuss pagination or result ordering, hence not 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?

One long run-on sentence with semicolons carries all the meaning, followed by a redundant English restatement ('Lists the exact supplier, family or group names used by the pharmacy'). The enumeration is front-loaded after a noun-phrase opening, but the structure is dense and the duplicated final line does not earn 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 3-parameter read tool with no output schema and annotations already covering safety, the description is nearly complete: it explains what categories are returned, includes reference/sold/stock counts and a 150-row cap. The gaps are the undocumented q filter and the unexplained types_soin enum value.

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 parameter meaning. It explains most of the quoi enum values (laboratoires/familles, groupes, molecules, rayons/sous-rayons, codes_changes) and implies limite via 'Au plus 150 lignes', but it never explains the q search parameter and omits the types_soin enum value.

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 read resource and enumerates every domain it covers: supplier/family spellings, product groups (parapharmacie, médicaments, LPP), molecules, SyderaAI rayons/sous-rayons, and code changes. It explicitly marks what it is not for (medical questions, posology, patient records, market prices), which sets it apart from siblings like chercher_produit and fiche_produit.

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 states the two concrete triggers: get the exact spelling of a supplier/family/molecule before filtering another tool, or find products that changed code. It also lists explicit exclusions, so an agent can decide both when to call it and when not to.

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, non-open-world, so the safety profile is covered. The description adds real behavioral context beyond that: the figures are scoped to the last twelve full months ('mois pleins'), a data-quality signal is included, and it tells the agent to surface the measurement date, which matters for interpreting stale figures. It does not discuss failure modes or what happens if the pharmacy is unidentified.

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 priority instruction ('À appeler en premier') is front-loaded, followed by the payload list, then the exclusions and a one-line English restatement. The middle sentence is a dense enumeration, but each listed field (PAMP valuation, margin, data quality, software-change date) earns its place by telling the agent what it can answer with.

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 zero parameters and no output schema, the description carries the full burden of describing what comes back, and it does so completely: identity fields, historical context, twelve months of financials, and a data-quality indicator plus the reference date. Nothing an agent needs in order to decide to call it or to interpret the answer 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?

The tool takes zero parameters, so the baseline of 4 applies; the description correctly implies no input is needed by framing the call as 'call it first' to discover which pharmacy the user is talking about. No parameter meaning is missing because there are none.

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 concrete verb+resource (identify the pharmacy and return its identity plus twelve full months of key figures), enumerating the exact payload: name, address, phone, identifiers, software-change date, stock value at PAMP, revenue, margin in euros and percent, and data quality. It also fixes its position against the siblings ('À appeler en premier') and excludes medical/patient/market-price territory, so an agent can separate it from bilan_mensuel, ventes_mois or chercher_produit 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?

Usage is explicit: call it first, and use it whenever a pharmacist talks about their pharmacy, sales, stock or margin, to establish which pharmacy and at what date figures were measured. Negative guidance is also explicit (not for a medical question, dosage, patient record or market price). It stops short of naming the sibling tools to redirect to, so routing beyond the exclusion list is left 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 cover the safe read profile, yet the description adds real behavior: the 50-row cap, the rule that a name list is one row per name in a single call and never one call per name, the extra fields added by comparer (*_avant, evolution_ca_pct, evolution_pamp_pct), and that ca_min filters rows while the total still covers everything. Missing only finer detail such as ordering of the returned rows or empty-result 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?

It is front-loaded with the grouping modes, which is the right priority, but the body is a single run-on sentence chained with semicolons that is hard to parse, and the final English sentence duplicates the French scope statement. Content mostly earns its place; the packaging does not.

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 21-parameter, output-schema-less tool, the description compensates well by enumerating the output metrics (unités, CA TTC/HT, marge €/%, stock, PAMP, jours de stock, total) and the comparison fields. It does not describe how rows/keys are labeled when grouping by several dimensions at once, which is the main remaining 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 95%, so nearly every parameter already carries its own explanation; the prose largely restates par, produit, comparer and tri. Baseline 3 applies, with only marginal cross-parameter guidance added (liste needs multiple names, filter-then-verify for molecule classes).

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?

Opens with a specific verb+resource ('Le classement des laboratoires, des familles... des molécules...') and enumerates every grouping mode it covers, so an agent can immediately differentiate it from top_ventes or gamme_laboratoire. The scope (period, metrics, ranking) is stated concretely rather than tautologically.

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 names the intended questions ('quels laboratoires, quels rayons ou quelle part... pèsent le plus', 'préparer un rendez-vous avec un laboratoire') and explicit exclusions ('Pas pour une question médicale, une posologie, un dossier patient ni un prix du marché'). It also routes within itself for the molecule case (try molecule first, then fall back to produit).

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, non-destructive, closed-world behavior. The description adds meaningful behavioral context beyond that: sorting by value, row cap of 200, totals and breakdowns across all dormant stock, and seasonal products separated out.

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 definition is front-loaded with what the tool returns and is appropriately detailed for an 11-parameter analytical tool. The English sentence repeats the French summary, which is mildly redundant but not confusing.

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?

Given the complexity and lack of an output schema, the description is complete enough: it explains the return content, aggregation behavior, row limit, seasonal exception, filters, use cases, and exclusions. The parameter schema supplies the remaining detail at high coverage.

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 high at 82%, so the schema already carries most parameter meaning. The description only mentions the laboratoire, famille, and groupe filters plus the N-month window, adding little beyond the structured parameter documentation.

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 and condition: in-stock products with no sale for N months, including tied-up value, sorted by value, with totals and breakdowns. It is clear what the tool returns, but it does not explicitly differentiate itself from sibling tools such as couverture_stock or top_ventes.

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 clear when-to-use triggers: the pharmacist asks what is not moving, how much money is dormant, preparing destocking, or a lab meeting. It also gives explicit when-not-to-use cases, though it does not name alternative sibling tools for adjacent questions.

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 and non-destructive, so safety is covered. The description adds useful behavior beyond that: the 100-row cap, that totals always cover everything filters retain even when rows are trimmed, that comparer adds *_avant fields and evolution_ca_pct, and a pricing-scope disclaimer (pharmacy prices only, no market pricing, no advice). However, it does not describe pagination interaction with totals or the vente_ponctuelle/saisonnier detection heuristics in enough precision for the agent to anticipate row-level flags; solid but not fully transparent – a 3.

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 scope and outputs, which is good, but the paragraph is very dense: the return columns are effectively listed twice ('classés par…' then 'unités, chiffre d'affaires TTC et HT…'), and the closing pricing-scope caveat plus the English echo sentence add length without new decision-relevant content. Justified by 24 parameters, but tighten-able.

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 24 optional parameters, 96% schema coverage, no output schema and no nested objects, the description supplies the missing pieces: what the totals mean, the row cap and page behavior, the comparison fields, and the domain limits (officine prices only). An agent can call this correctly without further context.

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 96%, so the schema carries parameter semantics and the baseline is 3. The description nevertheless adds meaning beyond it: it explains what comparer produces (comparison period and evolution), what stock_max=0 signals, how ponctuelles/saisonniers behave, and how tri options pair with comparer. Marginal but real added value over 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?

Opens with a specific verb+resource+scope: products over a period, ranked by units, revenue, margin, margin rate or growth. It enumerates the exact return columns (TTC/HT, marge, PAMP, stock) so an agent can separate it from siblings like ventes_mois or palmares 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?

Provides an explicit mapping of natural-language questions to parameter combinations ('ce qui me rapporte le plus' → tri=marge; 'prépare-moi l'hiver' → du/saisonniers; 'ce que je vends à perte' → marge_pct_max=0) and explicitly excludes medical/prescription/patient/market-price questions. Nothing is left to inference about when to select this vs 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?

Beyond the readOnly, idempotent, non-destructive annotations, the description discloses pagination by 100, sorting by revenue, a special first-page summary by rayon versus the previous month, filter dimensions, and the exact metrics returned. No statement contradicts 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?

The core behavior is front-loaded and each part of the description carries useful information. The long metric parenthetical is dense but justified, while the final English sentence partly duplicates the opening.

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 five-parameter analytics tool with no output schema, the description explains the returned metrics, pagination behavior, first-page summary, available filters, and usage exclusions. An agent has enough context to call it and interpret the results 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 high and already documents mois, groupe, famille, and laboratoire well. The description adds useful operational semantics for page results, notably 100 rows per page sorted by chiffre d'affaires, though it does not add much beyond the schema for the filter parameters.

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: all sales for one month, reference by reference, with named metrics. It implicitly distinguishes the complete detail from summary/top views through 'référence par référence' and 'détail complet', but it does not explicitly name sibling tools such as bilan_mensuel or top_ventes.

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 a clear usage condition: use when the pharmacist wants the complete detail for a given month. It also lists explicit exclusions (medical question, dosage, patient record, market price), but it does not route the agent to specific alternative tools.

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