Projet Ariane — Orientation

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

Annotations already declare readOnlyHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the data provenance (Projet Ariane, source DEPP), the geographic aggregation levels, and the special behavior when ville+rayon_km are combined (ranked nationally with straight-line distance).

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, front-loaded with the core noun (palmarès) and the data returned, with the special mode relegated to the end. Dense but without filler; only slight repetition of schema-level detail keeps it from a 5.

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?

No output schema exists, so the description carries the burden of describing returns, and it does list the key returned fields (rang, réussite, valeur ajoutée, lien vers fiche). Combined with annotations covering the safety profile and full schema coverage of inputs, an agent has enough 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 description coverage is 100%, so the schema already documents all seven parameters including enums, defaults, bounds and the ville/rayon_km dependency. The description's second sentence largely restates the ville+rayon_km mode already present in the schema, adding little beyond the baseline.

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 resource (palmarès des lycées/collèges) and scope (millésime le plus récent; national, région, département, ville) with the returned metrics spelled out (rang, réussite, valeur ajoutée, lien vers fiche). This is clearly distinguishable from siblings like fiche_ecole or rechercher_ecole, though the description never names them explicitly, so sibling differentiation is implicit rather than stated.

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 through the description of two operating modes (geographic level vs. ville+rayon_km), which hints at when the tool is appropriate. However, there is no explicit when-to-use guidance, no exclusions, and no pointer to alternative tools for school lookup versus ranking.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful guarantee ('Ne rend jamais un événement passé') and the online-event exclusion in radius mode, but omits result ordering/pagination or output shape detail.

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 dense sentences, front-loaded with the core listing behavior and then the radius variant, with no filler. The parenthetical enumerations and data-source note add length but each carries content.

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 still tells the agent what comes back (dates, lieu, inscription; distance in radius mode), which is exactly the burden it must carry for a read-only listing tool whose annotations already cover safety.

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 baseline is 3, but the description adds relational meaning the schema does not: ville plus rayon_km acts as a center and yields distance-à-vol-d'oiseau results while excluding online events. That interaction is the key semantic not derivable from isolated parameter descriptions.

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 ('événements d'orientation à venir') with enumerated event kinds and the data sources (Projet Ariane, OpenAgenda). The siblings are all fiche_/rechercher_/classement tools over different resources, so the resource itself cleanly separates 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?

Explains the two operating modes: lookup by ville/département/région/type/horizon, versus radius search triggered by combining ville with rayon_km. It does not name exclusions or point to a sibling alternative, so it stops short of full when/when-not 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=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by specifying the exact content of the returned record (description, montant, profils éligibles, liens officiels) and the data source (Projet Ariane), which goes beyond 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 description is a single, front-loaded sentence that states the action and the key content without any filler. It is concise and efficient.

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 one parameter, no output schema, and simple annotations, the description is complete for an agent to invoke correctly. It tells what the tool returns and from where, and lists the fields included, which is sufficient for a retrieval tool.

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 input schema provides 100% coverage for the single parameter slug, including an example. The description adds no additional parameter meaning beyond what the schema already states, so the baseline of 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 clearly states the tool returns the complete record of a financial aid, listing the specific content (description, amount, eligible profiles, official links). This distinguishes it from sibling fiche tools for schools, formations, and métiers, which are separate resources.

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?

While the description doesn't explicitly state when to use this over alternatives, its purpose is unambiguous: it is the tool for retrieving a full financial aid record by slug. The sibling list includes rechercher_aides, which implies this is for direct lookup of a known aid, but the description itself doesn't mention that contrast.

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 and destructiveHint=false, covering safety. The description adds context about the data content, including conditional bac results for lycées and the Projet Ariane data source. However, it does not mention potential limitations, error conditions, or rate limits, which are minor given the read-only nature.

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 a single sentence that front-loads the main action and efficiently lists the types of data returned. There is no filler or redundancy, making it highly concise and well-structured.

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 there is no output schema, the description compensates by enumerating the types of data returned (campus, addresses, formations, selectivity, bac results). It also hints at conditional content for lycées. While it could specify the structure more, it is sufficiently complete for an agent to understand what to expect.

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% for the single parameter 'slug', which is well-documented in the schema as the URL identifier returned by rechercher_ecole. The description does not add any additional meaning beyond what the schema already provides, so it stays at the baseline.

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 clearly states the tool returns the fiche of an establishment and enumerates its content: campus, addresses, formations with Parcoursup selectivity, and bac results for a lycée. This is specific and distinguishes it from sibling tools like fiche_formation and fiche_metier.

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 does not explicitly state when to use this tool versus alternatives. The input schema's parameter description mentions the slug is returned by rechercher_ecole, implying a workflow, but this is not in the tool description itself. Usage 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 establish readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context by naming the specific datasets returned and the time scope ('derniers millésimes', 'données Projet Ariane'), which goes well beyond 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 description is a single, well-structured sentence: the verb and resource come first, followed by a colon and a compact enumeration of the returned content. Every part adds information and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description enumerates the main return content well, but there is no output schema to fall back on and the schema marks 0 required parameters. The description does not clarify that id or slug should normally be supplied to retrieve a specific fiche, nor what happens if neither is provided. This leaves a real invocation ambiguity.

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 id and slug are already documented with their meaning and source (rechercher_formation). The main description does not add new parameter-level meaning beyond clarifying that the tool returns a formation fiche, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Retourne la fiche d'une formation' and lists the exact contents returned (établissement, diplôme, statistiques Parcoursup, insertion, métiers visés). This makes the tool's purpose concrete and differentiates it from sibling tools like fiche_ecole or fiche_metier, which target different entities.

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 this is the detail-view counterpart to rechercher_formation, and the parameter descriptions mention that id/slug are provided by rechercher_formation. However, there is no explicit statement of when to choose this tool over a sibling or of the condition 'use after a search'.

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 this as read-only and non-destructive. The description adds meaningful behavioral context by specifying exactly what the tool returns and its data source, which is especially useful given there is no output schema. It does not address missing-slug or error behavior, but that is a minor gap for a safe lookup tool.

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 a single front-loaded sentence with no filler. The verb and object appear first, and the parenthetical lists the returned content economically. Every element 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 one-parameter, read-only lookup with complete schema coveragechers, the description is largely adequate: it states the return sections, the source, and the required identifier. The only notable gap is that it does not explicitly instruct the agent to use rechercher_metier when the slug is unknown, which would strengthen guidance.

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%: the single required slug parameter is already well documented with an example ('infirmier, developpeur-web'). The description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a precise verb and resource: 'Retourne la fiche complète d'un métier' and enumerates the contained sections (description, rémunération, marché de l'emploi, formations associées). It clearly distinguishes this from sibling tools by resource type (métier vs école, formation, aide) and by 'fiche complète' versus search-oriented tools like rechercher_metier.

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 use case is implied rather than explicit: the slug parameter and the notion of returning a complete fiche suggest the agent should call this when it already knows the métier identifier. However, the description does not name alternatives or state when not to use it, leaving sibling differentiation largely 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 read-only and non-destructive nature of the tool. The description adds a useful data-source context ('données Projet Ariane') and indicates the result is a list, but it does not disclose output format, pagination, or any special query behavior. This is adequate but not rich.

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, compact sentence that front-loads the action and object, then adds the scoping condition and data source. No filler or redundant phrasing.

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 well-described parameters, the description plus schema is largely sufficient. The main gap is that it does not explicitly state that at least one of metier or domaine should be used, and it does not describe the shape of the returned list, though 'Liste' implies a list of diplomas and formations.

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 schema already documents both parameters fully, so the baseline is 3. The description adds semantic value by framing metier and domaine as alternative search dimensions ('un métier donné ou à un domaine'), which clarifies the intended relationship between the two optional 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 uses a specific verb ('Liste'), names the resource ('diplômes et formations'), and clearly scopes the result to a given métier or domaine. This distinguishes it from sibling tools like rechercher_formation and fiche_formation, which target formation lookup or detail rather than mapping a job/domain to training paths.

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 gives a clear usage context: use it to discover diplomas and formations for a target job or professional field. However, it provides no explicit guidance about when not to use it, no mention of alternatives like rechercher_formation or fiche_formation, and no clarification about whether at least one parameter must be provided.

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, non-destructive, closed-world), so the description is free to add substance — and it does: result ordering (most local first), result content (portée, montants, liens vers les fiches), and degradation behavior without a location. This is meaningful behavior beyond 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?

A single dense sentence, front-loaded with the verb and resource, followed by the scoping and fallback clauses. Every clause carries information; the parenthetical example lists are the only mild 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 no output schema, the description does the work of describing returns (portée, montants, liens) and the ordering, so an agent knows what to expect. Nothing critical is missing, though result volume/pagination is unaddressed.

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 each parameter is documented there, including the accepted categorie values and the code_postal disambiguation role. The description only restates that location may be a city, department or region and that situation is free text, adding little beyond the schema; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: "Trouve les aides financières (bourses, logement, mobilité…)" with the input mode (free-text situation + location). It is clearly distinguishable from fiche_aide (detail view) and the rechercher_* siblings by being a situational search, though it never names an alternative 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?

Gives clear conditions of use — a free-text situation plus an optional location — and states the fallback when no location is given (national aid only). It stops short of naming alternatives such as fiche_aide for consulting a specific aid, so it is context-rich but not exclusionary.

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?

Les annotations couvrent déjà le profil sécurité (readOnlyHint=true, destructiveHint=false, openWorldHint=false), donc la barre est plus basse. La description ajoute du contexte comportemental utile : l'ordre des résultats ('classés par pertinence') et la composition du retour ('avec lien vers l'article'). Aucune contradiction avec les 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?

Une phrase unique d'environ 24 mots où chaque segment apporte une information : type de contenu, éditeur, domaine thématique, modes de recherche, tri, lien de sortie. Aucun remplissage, et l'information clé ('Trouve des articles et guides') est en tête.

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?

Pas de schéma de sortie : la description assume l'essentiel du retour ('avec lien vers l'article') mais ne précise pas la structure complète des résultats ni le comportement en cas de zéro résultat. Comme l'outil est simple, les paramètres à 100 % couverts et les annotations sécurité présentes, la description reste quasi suffisante.

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?

La couverture du schéma est de 100 % : les trois paramètres (recherche, tag, limite) ont déjà leur propre description dans le schéma. La mention 'par mots-clés ou par tag' ne fait que reformuler ces descriptions sans ajouter de sémantique nouvelle (format attendu, défauts, exemples supplémentaires). Baseline 3 justifié.

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?

Le verbe 'Trouve' est spécifique, suivi d'une ressource précise ('articles et guides publiés par Projet Ariane') avec méthode ('par mots-clés ou par tag'), tri et type de sortie. La ressource 'articles et guides' distingue clairement l'outil des frères structurés (rechercher_ecole, rechercher_metier, rechercher_aides) qui visent des fiches/records, pas du contenu éditorial.

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?

Le contexte d'usage est implicite : la liste thématique (Parcoursup, alternance, métiers, aides, vie étudiante) et le type 'articles et guides' suggèrent quand l'utiliser, notamment par contraste avec les outils frères. Mais la description ne nomme aucune alternative et n'exclut rien ; un agent doit inférer qu'il faut rechercher_metier pour les fiches métiers plutôt que cet outil.

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 a safe read-only, closed-world operation, so the description only needs to add context. It does so well: it discloses the data source (Projet Ariane), the geo semantics (distance à vol d'oiseau, nearest-first ordering), and the shape of results (campus, formation counts, links to fiches). It stops short of stating result caps or pagination, which the schema covers via limite.

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, front-loaded with the core search scope and then the special geo mode. No filler or repetition of the title. It is information-rich rather than padded.

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 correctly carries the burden of describing return content (campus, nombre de formations, liens vers les fiches), and all seven parameters are schema-documented. It is complete enough to invoke safely; only the result-set limit/default is left to the schema rather than restated.

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 every parameter is already documented in the input schema, including the ville+rayon_km dependency ('Exige ville'). The description echoes that geo combination but adds no syntax or format detail beyond what the schema already supplies; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Trouve des écoles et établissements') and enumerates the axes of search (nom, sigle, type, ville, département, région) plus what comes back (campus, nombre de formations, liens vers les fiches). The plural, multi-result nature implicitly separates it from the single-record sibling fiche_ecole, but 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?

The sentence 'Avec ville et rayon_km : écoles ayant un campus autour de la commune' gives conditional behaviour for one parameter combination, which is useful orientation. However there is no explicit when-not guidance or routing to alternative tools such as fiche_ecole or rechercher_formation; the caller must infer the boundary between searching and looking up a known school.

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 a safe read operation (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description doesn't need to repeat that. It adds that results are ranked by relevance, include Parcoursup access rates and links, and when ville+rayon_km are given results are sorted by distance with the distance shown. It doesn't mention pagination or rate limits, which is acceptable for a read-only search.

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 efficient sentences: the first describes the core search and output, the second describes the geographic mode. No filler, and key mode-switching info is front-loaded in the second sentence.

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 explains the main return fields (relevance, access rate, links, distance) and the geographic sorting mode. It is complete enough for an agent to call the tool correctly; only minor gaps like exact default limits remain.

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 schema already documents all parameters well. The description reinforces the behavior of ville+rayon_km and the notion of relevance ranking, but it adds little about parameter syntax or defaults beyond what the schema provides. Baseline 3.

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 (Trouve) and resource (formations) with the covered fields (intitulé, ville, niveau, type), and distinguishes itself from fiche_formation by returning ranked lists with link destinations. It also names sibling-like alternatives to open the fiche details (fiche_formation).

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 clarifies that ville+rayon_km selects a geographic proximity mode sorted by distance, which is a clear usage context. It does not explicitly say when to use this tool versus fiche_formation or rechercher_ecole, but the context implies it is the search entry point.

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 signal readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: it names the data source (Projet Ariane) and the return shape (list with links to fiches), though it does not discuss limits 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?

The description is a single, front-loaded sentence with no filler. It packs in the action, criteria, source, and output shape efficiently, and the parenthetical data-source note 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 search tool with fully documented parameters and safety annotations, the description is nearly complete: purpose, source, and output are all covered. It could be more explicit about whether both criteria can be combined and what fields appear in the returned list, but nothing essential to invocation 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 description coverage is 100%, so the baseline of 3 applies even though the description adds little parameter detail. The description restates the two criteria but does not clarify how required 'interets' and optional 'domaine' combine; 'ou' could imply domain-only searching even though 'interets' is required.

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 ('Trouve'), a target resource ('métiers'), and the matching criteria ('centres d'intérêt ou un domaine'), then specifies the output as a list with links to fiches. This clearly differentiates it from sibling fiche_metier, which presumably returns a single job sheet.

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 gives clear search context: use it to discover careers from interests or a domain, and expect a list back. It does not explicitly name alternatives or state when not to use it, but the context is sufficient for an agent to route a broad career-search query here.

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 (readOnlyHint=true, openWorldHint=false, destructiveHint=false), and the description adds real behavioral context: only active offers, results sorted most-recent-first, distance measured as the crow flies, and the upstream sources. It stops short of mentioning pagination limits or auth, but the added traits are substantive.

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, and the primary capability is front-loaded before the geo-mode detail. The first sentence is heavily packed, but every clause (sources, filters, returned fields) 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?

With no output schema, the description usefully enumerates returned fields (contrat, salaire, date, lien) and covers the geo/radius behavior for a 7-parameter tool. It is largely complete, missing only edge-case behavior such as empty results or how metro/region strings are resolved.

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 semantics the schema lacks: the interaction between ville and rayon_km, the recency sort order, and the returned distance metric. This is meaningful meaning beyond the per-field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb (Trouve) plus resource (offres d'emploi et d'alternance actives), names the data sources (France Travail, La Bonne Alternance, Projet Ariane) and the fields returned. This resource is clearly distinguishable from siblings like rechercher_formation or rechercher_metier without opening any 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 explains a concrete usage mode ("Avec ville et rayon_km : offres autour de la commune, les plus récentes d'abord") which tells the agent how to combine geo parameters for a radius search. However it names no alternatives and gives no when-not guidance, so it stops 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.