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.