Diplomètre

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

Annotations already cover readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses that no ranking or global score is produced, that every figure carries producer/year/reliability or 'non communiqué', that the taux d’accès is not a prediction of admission, and that the response ends with a Diplomètre link. That is substantive behavioral and output-shape context.

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?

Purpose and scope are front-loaded in the first sentence, and the rest is packed with relevant caveats. It runs long with several subordinate clauses, but nearly every sentence carries a distinct constraint (no ranking, provenance, non-prediction, footer link), so little 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?

An output schema exists, yet the description still usefully characterizes the content and the trailing link without over-specifying the return format. Combined with full schema coverage and annotations, an agent has everything needed to call this tool 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 100%, so the identifiants field, its 2–4 bounds, and the id-format rules are already fully documented in the schema. The description's 'dans votre ordre' merely echoes the schema's 'dans l’ordre voulu', adding no new syntax or format guidance.

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 ('Comparez de 2 à 4 formations côte à côte') and enumerates exactly what dimensions are compared (accès, réussite, poursuite d’études, emploi, salaire, frais, reconnaissance). It also fixes its scope against siblings by specifying 'sans classement ni note globale', so an agent can tell it apart from lire_formation or rechercher_formations.

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 opening 'Vous hésitez entre plusieurs formations ?' gives a clear situational trigger and the body constrains the count to 2–4. However, it never names an alternative tool for the single-formation case (lire_formation) or the search case (rechercher_formations), so routing is implied rather than explicit.

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 (readOnlyHint, idempotentHint, non-destructive), so the bar is appropriately lower. The description adds meaningful context: it clarifies that no personal data is required, no formation-specific figures are provided, and that official verification is the user's responsibility—going beyond what annotations convey.

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 relatable example questions that immediately orient the reader, followed by a concise explanation of what the tool provides and its limitations. It is slightly long but every sentence earns its place by clarifying purpose, scope, and constraints.

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 a single required enum parameter, rich annotations, and an output schema, the description is nearly complete. It covers what the tool does, what it does not do, and the expected data-handling stance. The only minor gap is that it does not explicitly differentiate from sibling tools by name, but the context is otherwise sufficient 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% with an enum of 21 values, so the schema already documents the parameter thoroughly. The description adds value by framing what the 'sujet' represents (the person's need) and explicitly noting that the raw question and personal data should not be transmitted, complementing rather than repeating 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 description conveys a specific purpose: explaining orientation questions and pointing to relevant pages, with a clear intent to explain rather than evaluate. It distinguishes itself from data-lookup siblings (lire_formation, comparer_formations) by explicitly stating it does not evaluate a dossier or predict admission, though it does not name those siblings directly.

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 mentions the categories of topics handled (choix, comparaison, accès, réussite, etc.), providing an implicit sense of when to use the tool, but it does not explicitly state when not to use it or name alternative tools for distinct needs. The negative constraints (no dossier, no admission prediction) provide some boundary 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: each figure carries its producer and year or 'non communiqué', reliability is flagged, and it warns that 'le taux d'accès ne prédit pas votre admission' – a caveat that prevents an agent from misinterpreting the metric. Provenance and data-quality semantics are spelled 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 three opening questions act as an intent-matching hook rather than pure filler, and the core purpose statement backed by the field list is dense with information. It is slightly back-loaded – the actual 'consultez la fiche' purpose arrives after the questions – but no sentence is truly 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 an output schema present, return structure needn't be explained, and annotations cover safety. The description still completes the picture by describing data provenance, reliability caveats, and the metric-interpretation warning, leaving little an agent would need that isn't already in the structured fields.

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 schema description coverage is 100%, so the schema already fully documents 'identifiant' including its lowercase/dash format and full-URL alternative. The description adds nothing about the parameter, making the baseline 3 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?

The description states a specific verb and resource ('Consultez la fiche d'une formation') and enumerates the exact fields returned – accès, réussite, poursuite d'études, emploi, salaire, frais, reconnaissance du diplôme – so an agent knows precisely what this tool yields. It is clearly distinguishable from sibling tools like rechercher_formations or comparer_formations by its single-formation 'fiche' scope, though it never names those siblings 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?

Usage is only implied, via the framing questions (cost, employment outcomes, diploma recognition), which suggest the situations that call for this data. There is no explicit when-to-use statement, no exclusion, and no pointer to the alternative tools for searching or comparing formations.

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 (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, yet the description still adds substance: each figure carries its producer, year and reliability, and it warns that 'les places pour 100 candidatures ne sont pas vos chances d'admission'. This interpretive caveat is genuinely useful context an agent would otherwise get wrong.

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 need-recognition questions are front-loaded and the payload list follows, then the caveats. It is slightly long for a single-parameter lookup and the rhetorical questions add some padding, but every sentence carries informational load and nothing is redundant.

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 an output schema present, the description need not detail return values, and it doesn't need to. Combined with annotations covering the safety profile and 100% schema coverage on the sole parameter, this is nearly complete; only the lack of sibling routing keeps it just short of full marks.

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 meaning: it explains the disambiguation behavior ('Si le nom correspond à plusieurs mentions, la réponse vous propose de préciser'), which tells the agent the input may be ambiguous. That goes beyond the schema's example-value hint.

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 — 'Consultez ... les repères d'une mention de master' — and enumerates the concrete data points returned (places per 100 candidatures, études suivies, emploi, salaire, masters proposés, licences compatibles). It is clearly about a 'mention' rather than a 'formation', which separates it from lire_formation/rechercher_formations, 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?

Usage is only implied through the framing questions ('Quel master après ma licence ?', 'Quels emplois et salaires...?'), which sketch the scenario but stop short of explicit when-to-use vs. alternatives. No exclusions or routing to comparer_formations or lire_formation is given, so the agent must infer the boundary 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, so the bar is lower, and the description still adds real behavior: a hard cap of 10 results, result ordering rules (search-term relevance, then formations with a published figure, then alphabetical), and the neutrality note. It omits what happens with zero matches, but the substantive behavioral context is present.

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 capability and ordering rules are useful, but two of the five sentences are rhetorical marketing questions that don't help an agent invoke the tool correctly. The ordering rule is dense and placed after the purpose, which is acceptable but not front-loaded cleanly.

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 an output schema present, the description needn't explain return structure, and it still covers result count, ordering, and neutrality. Parameter semantics are covered by the schema. Only edge cases (no results, behavior when multiple parameters conflict) are left unstated, which 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 all three parameters (type, texte, ville) are already documented with examples. The description's phrase 'par nom, spécialité, école, ville ou type de diplôme' loosely maps to those parameters but adds no syntax, format, or combination guidance beyond the schema, so the 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?

The description names a specific verb (Trouvez/Rechercher) and resource (formations en France dans Diplomètre) plus the searchable facets: nom, spécialité, école, ville, type de diplôme. It is clearly a search tool, implicitly distinct from comparer_formations and lire_formation, but no sibling is named explicitly, and the opening rhetorical questions add noise rather than precision.

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 the framing ('Quelles études après le bac ? … Trouvez des formations'), so an agent can infer this is the entry point for discovery. However, there is no explicit when-to-use vs. when-not, and no pointer to siblings like lire_formation for detail or comparer_formations for comparison.

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