Vocaneo

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

The annotations already mark it read-only and non-destructive, and the description adds substantial behavioral context beyond those hints: matching accepts plain words and does not require exact referential wording, multi-skill phrases are split, commonSkills only contains what the person thought to cite, and the coverage rate must not be turned into a percentage or employability verdict. This is exactly the kind of non-obvious behavior an agent needs to know.

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 purpose and output, but it is long and repeats nearly all content in French and then English. While the warnings are valuable, the bilingual duplication makes it less concise than it could be. It is structured coherently, but length reduces clarity for an agent parsing the definition.

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, so the description must explain return semantics, and it does: matched skills, missing skills, separated know-how and knowledge, raw numbers, commonSkills, jobSkillsCount, and the coverage rate caveat. It also covers the two main misuse risks — computing a percentage and drawing employability conclusions — making it complete for this tool's complexity.

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 already provides 100% parameter coverage, so the baseline is 3. The description adds meaning beyond the schema by explaining that userSkills should be in the person's own words, may contain multiple skills in one phrase, and that targetJobSlug is a required explicit target rather than an auto-suggested job. This enriches both parameters usefully.

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: it compares a list of user-provided skills against a target job's required skills and reports matches, missing skills, and raw counts. It also distinguishes itself from siblings by explicitly saying it does not suggest jobs, so an agent can tell it apart from get_similar_jobs or search_jobs.

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 when-to-use context: answering 'do I have the profile for job X'. It also gives an explicit exclusion: it does not suggest jobs, so a target must be supplied. However, it does not name sibling alternatives directly, so the guidance is strong but not a full alternative-routing instruction.

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 readOnlyHint=true and destructiveHint=false, so the safety profile is established. The description adds value beyond annotations by disclosing the full return payload and the notable behavior that it 'returns the public URL to cite', which agents need for downstream usage.

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 well-ordered: return payload first, then URL behavior, then id sourcing. The French/English duplication doubles length, but each sentence is dense and information-bearing, so the structure 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 one-parameter, read-only fetch with no output schema, the description's detailed field list acts as the return contract and is largely sufficient. The only gaps are edge-case behaviors such as handling of invalid ids or empty results, which are minor for a simple lookup 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?

Schema coverage is 100% — the id property is documented as 'Numeric certification id' — so the baseline is 3. The description adds genuine meaning by telling the agent where the id comes from (search_certifications or get_job_pathways), which the schema alone does not convey.

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 the resource precisely ('Full record of a diploma or certification') and enumerates the returned fields: title, RNCP/RS codes, type, exit level, access routes, average training price, target jobs, and programme count. It also names the public URL behavior and the two siblings that supply the id (search_certifications, get_job_pathways), which distinguishes it from search and training-record tools.

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 routes the caller: 'Get the id from search_certifications or get_job_pathways', which implies the correct lookup-then-fetch workflow before calling this tool. It does not explicitly state when not to use it versus alternatives like get_training, but the certification-specific field list makes the resource boundary reasonably clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds that the tool returns the public URL of the profile to cite, which is useful output context. It does not elaborate on errors, rate limits, or data freshness, but for a read-only lookup with annotations in place, the additional disclosure is adequate without being 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?

The description is front-loaded with the core purpose and content list, then covers input format and return value. The bilingual repetition doubles length, but each sentence earns its place by conveying distinct information. It is longer than strictly necessary but remains structured and readable.

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 read-only, single-parameter tool with 100% schema coverage and no output schema, the description is complete: it details what the tool returns, the accepted identifier forms, and the output URL. There are no significant gaps an agent would need to guess before calling it.

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 the schema already documents the identifier parameter with examples and guidance. The tool description repeats that slugs or ROME codes are accepted but adds no new semantic meaning beyond the schema. This matches the baseline for full schema coverage.

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

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

The description names a specific verb and resource: it retrieves the full profile of a French job, and enumerates the content areas (duties, skills, alternative names, access conditions, labour-market data, AI exposure). It also clarifies the accepted identifiers (slug or ROME code), distinguishing this from search_jobs and other sibling tools that either search or return related jobs.

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 states when to use this tool: to get a full job profile by slug or ROME code. It also gives explicit guidance in the parameter description: when unsure about the exact epicene slug, call search_jobs first to obtain it. It does not contrast with get_similar_jobs or get_job_pathways, but the single-profile purpose is clear and the search_jobs routing is a concrete usage hint.

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à readOnlyHint et destructiveHint. La description ajoute un comportement utile: les codes ROME 4.0 sont résolus en amont par le référentiel, donc aucun prétraitement de code parent n'est nécessaire. Elle précise aussi le contenu du retour, ce qui va au-delà des 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?

La description est bien organisée: fonction, contenu du retour, formats d'entrée, conseil de résolution. Le bloc bilingue est dense et utile. Seule la métaphore « pont entre une question d'orientation et l'offre de formation » est légèrement redondante avec la première phrase.

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?

Il n'y a pas de schéma de sortie, mais la description énumère suffisamment le contenu retourné: diplômes, certifications, nombre de formations, niveau de sortie dominant et voies d'accès. Le schéma d'entrée couvre les paramètres et le repli sur search_jobs ferme l'ambiguïté sur les identifiants. Rien d'essentiel ne manque pour invoquer l'outil correctement.

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%, donc le niveau de base est 3. La description apporte une information supplémentaire réelle: les codes ROME récents sont résolus en amont, ce qui évite de chercher un code parent. Le schéma documente déjà abondamment les slugs épicènes et la recherche préalable via search_jobs.

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?

La description ouvre sur la question concrète « comment devenir X » et énumère précisément ce que retourne l'outil: diplômes/certifications, nombre de formations, niveau de sortie dominant et voies d'accès. Cela la distingue clairement des frères comme get_job (détails d'un métier) ou search_jobs (recherche d'identifiants), même sans les nommer.

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 cas d'usage est explicite: répondre à une question d'orientation. Le schéma ajoute une consigne actionnable: en cas de doute sur un slug, appeler search_jobs d'abord, qui fournit le code ROME et le slug exact. La phrase « inutile de chercher un code parent » élimine aussi une étape superflue.

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 declare read-only behavior, and the description adds significant behavioral depth: proximity is a verifiable calculation from reference skills, not advice; the tool has no knowledge of the user; results include sharedSkills and a public URL; and there is an explicit warning against misuse. This 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 front-loaded with the core purpose and is well organized, but the French and English versions largely duplicate each other, which adds length. The content is still focused, and every substantive point serves either selection, invocation, or safe use.

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 two-parameter tool with one required parameter, the description is complete: it explains the ranking logic, what each result contains, what the identifier should be, and what the output must not be used for. The absence of an output schema is compensated by describing the key result 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?

Schema coverage is 100%, and the schema itself already documents both parameters, including the limit range/default and the identifier slug format with a note about ROME codes. The description adds no extra parameter-level meaning beyond what the schema provides, so 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: returns jobs closest to a given job, ranked by shared skills. It explicitly names the user question it answers and differentiates itself from siblings like search_jobs and get_job by focusing on proximity rather than search or details.

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?

Clearly identifies the intended use case: career reconversion questions like 'what jobs are close to mine?'. It also provides a firm exclusion, telling agents not to present results as individual career guidance or combine them into psychometric advice. It does not explicitly enumerate sibling alternatives, but the use context is strong.

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 mark the tool as readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by stating that it returns the public URL to cite and by enumerating the record fields returned, which gives the agent a clear expectation 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 structured and information-dense, with the main purpose stated first and follow-up details about the URL and id source. The bilingual FR/EN duplication doubles the length but is understandable given the likely audience; overall every sentence 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 getter with one required parameter, the description covers the returned content, the public URL return value, and the id acquisition path. The output schema is absent, so the description appropriately compensates by listing the record elements. Nothing critical is missing for an agent to invoke 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?

The schema already fully describes the id parameter with 100% coverage, so the baseline is 3. The description adds value by explaining that the id comes from search_trainings, which tells the agent where to obtain a valid value rather than just what the parameter type is.

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 ('get' / 'fiche complète') and identifies the resource as a training programme, then enumerates exactly what the record contains: objectives, syllabus, prerequisites, admission, price, CPF eligibility, diploma, and establishment. It also distinguishes itself from search_trainings by clarifying that search_trainings is for discovering the id while this tool retrieves the full record.

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 explicitly tells the agent to obtain the id from search_trainings before calling this tool, which provides clear usage context. It does not explicitly contrast this tool with siblings like get_certification or get_job, but the domain-specific resource (formation/training) makes the intended use unambiguous.

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 and destructiveHint, but the description adds meaningful behavior beyond that: the disambiguation of url versus website and the note that phone is only included when known. This gives the agent practical interpretation guidance that structured annotations cannot 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 long and bilingual, but each component earns its place: the field list, the id-source note, the URL disambiguation, and the routing to search_trainings. The dual-language format lengthens it, but the content is information-dense and front-loaded with the essential record summary.

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 single-parameter read-only tool, this description is complete: it enumerates the returned fields, explains how to get the id, clarifies ambiguous fields, and tells the agent what to use for related operations. No output schema exists, so the detailed field enumeration in the description is especially valuable.

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 fully documents the numeric id parameter with 100% coverage, so the baseline is 3. The description adds genuine value by stating that the id is obtained from search_training_centers, which tells the agent where the identifier comes from and how to acquire it.

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 that this tool returns the full record of a training establishment, enumerating the exact fields included. It also orients the agent by saying the identifier comes from search_training_centers and that listing programmes belongs to search_trainings, distinguishing it from those siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly explains how to obtain the required id via search_training_centers and when to call search_trainings instead for programme listings. It also gives practical guidance about the two URL fields, telling the agent which one to cite and which one to use for user referrals.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds that the tool returns sector identifiers and serves a filtering purpose, but does not disclose deeper behavioral traits such as ordering, pagination, or whether inactive sectors are included. This is modest added context 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 two concise sentences per language: the first states the purpose and output, the second states the exclusion and alternative. There is no filler, and the bilingual duplication is justified for the intended audience.

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

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

For a zero-parameter, read-only list tool with no output schema, the description fully covers what the tool returns (sectors with identifiers) and when to use it (filtering on a whole sector). It also routes the agent to the correct sibling for simpler questions. Nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema is an empty object, so schema coverage is complete. No parameter explanation is needed; the description confirms this is a parameterless listing tool and expresses its intended use.

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 the specific verb 'Liste' with the resource 'secteurs d'activité du référentiel des métiers', states that identifiers are included, and explicitly distinguishes itself from search_jobs. An agent can immediately tell what this tool does and how it differs from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says the tool is for filtering a search on a whole sector, and explicitly warns it is not needed for simple thematic questions, pointing to search_jobs as the alternative that already searches sector labels. This gives clear when-to-use and when-not-to-use 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 mark the tool as read-only and non-destructive, but the description adds substantial behavioral detail beyond that: output values must be passed verbatim, the result includes latitude/longitude intended for aroundLat/aroundLng, and arrondissement postcodes like 69003 resolve to Lyon. This gives the agent a clear model of what the tool does with the input and what it returns.

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 well organized and front-loaded, but it repeats nearly the entire content in both French and English, making it much longer than needed for a one-parameter resolver. While bilingual text can be intentional, the duplication means many sentences do not earn their place in an otherwise compact tool definition.

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 is complete for this tool's complexity: it explains accepted input formats, resolution behavior, the exact output fields to reuse, and how to use coordinates with radiusKm. Since there is no output schema, the description compensates by naming the relevant return values and their intended downstream usage.

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 already documents the single query parameter with 100% coverage, including examples and arrondissement behavior. The description restates some of this but does not add significant new meaning about the query parameter itself; its extra value is more about how to use the resolved outputs, which belongs to behavior rather than parameter semantics.

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 action: 'Résout un lieu français à partir d'un code postal ou d'un nom de ville' and explains that it returns values to reuse in searches. This makes the tool's resource and purpose unambiguous, and it clearly distinguishes the tool from the search/get siblings by focusing on location resolution as a prerequisite step.

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 explicitly tells when to call the tool: 'À appeler avant toute recherche "près de chez moi"' and explains how to use its outputs for both verbatim city/department values and aroundLat/aroundLng radius searches. It also gives a concrete fallback strategy: use the coordinates when a small town yields nothing. This is strong usage guidance even without naming sibling 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?

The description goes well beyond the readOnly/destructive annotations by disclosing pagination (at most 20 results), the meaning of total, the null-total and totalAtLeast edge case, exactly how to phrase the count ('more than N', never 'N'), and the error behavior for unknown type values. This is rich behavioral context an agent needs to interpret results correctly.

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?

Each substantive point is purposeful and front-loaded, but the full French description is then repeated in English, which roughly doubles the length. The duplication is understandable in a bilingual context, yet it prevents a top conciseness score.

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 present, the description compensates thoroughly by defining the returned fields (total, results, URL), the page limit, the totalAtLeast edge case, and the follow-up call to search_training_centers. Nothing essential for correct invocation and interpretation 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?

Input schema coverage is 100%, with each parameter already documented in detail including accepted values and examples. The description restates the search dimensions at a high level but does not add meaningfully beyond the schema, 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 names an explicit verb and resource: searching recognized French diplomas/certifications (RNCP, RS). It enumerates concrete search dimensions (name, code, type, exit level, target job) and states the output includes a public URL, clearly distinguishing it from sibling tools such as get_certification or search_training_centers.

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 usage context and explicitly instructs chaining to search_training_centers with the certificationId to find where a diploma is taught. It does not explicitly exclude alternatives like get_certification, so it stops short of a full when/when-not comparison.

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 readOnlyHint=true annotation, the description discloses several genuinely non-obvious behaviors: results are capped at 20 per page, « total » is always null because the API provides no count, each item carries a public URL to cite, and query results rank the generalist job first followed by its specializations. These are exactly the traits an agent needs to avoid hallucinating totals or mis-reporting the first result.

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: the first sentence establishes resource and search dimensions, then return format, then ordering semantics, then the results/total contract. The bilingual FR/EN duplication doubles length, but each language copy is tight and every clause carries information rather than 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?

For a 7-parameter read-only search tool with 100% schema coverage and no output schema, the description covers the top-level return contract (results, total), the per-item URL to cite, and the API's null-count quirk. The remaining gaps are explicit sibling routing (get_job for a single profile, get_similar_jobs for similarity) and per-item fields beyond the URL.

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% and all 7 parameters are richly described in the schema, so the baseline is 3. The description adds value beyond the schema by explaining the query-dependent ranking semantics (generalist first, then specializations, first result targets « comment devenir X »), which the schema's query entry does not mention.

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: « Recherche des métiers dans le référentiel français Vocaneo », and enumerates the search dimensions (keywords, sector, salary, accessibility, themes) plus the list-shaped return of at most 20 jobs. This structurally separates it from siblings like get_job or search_certifications, but no sibling is ever named, so differentiation remains implicit rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use vs alternatives guidance is present; none of the 12 siblings are mentioned and no exclusions are given. Usage context is implied through the query-ordering note (« le premier résultat est celui que vise une question comment devenir X »), and the schema rather than the description points to list_job_sectors for sector identifiers.

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

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

Annotations only declare readOnlyHint and destructiveHint. The description adds substantial behavioral context: results are capped at 20, 'total' can be null with a 'totalAtLeast' lower bound, certificationId mode returns no bound at all, radius replaces city/postalCode, results are sorted by distance and carry distanceKm, and certificationId ignores other filters. This far exceeds what the 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 dense, front-loaded with purpose, and every caveat about q, radius, certificationId, and total semantics is operationally valuable. It is long, partly due to bilingual FR/EN duplication, but the structure is logical and the length is justified for an 11-parameter tool with no output schema.

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

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

With no output schema, the description must explain return semantics, and it does: 'total', 'results', the 20-item page cap, null behavior and totalAtLeast, certificationId's no-bound case, and radius-specific fields. It also covers parameter precedence and the dependency on resolve_location. No essential calling information appears 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 100%, so the baseline applies and the description does not need to document each parameter. The top-level description adds useful global semantics around total/totalAtLeast and certificationId behavior, but it does not add per-parameter meaning beyond what the input schema already provides.

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: 'Recherche des établissements de formation français', enumerates the establishment types covered, and clearly contrasts the certificationId search mode ('plutôt les établissements qui préparent ce diplôme'). This makes it easy to tell apart from singular tools like get_training_center and from search_trainings.

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 explicit when-to/when-not-to guidance: use q alone for establishment names, never combined with city/postalCode; use certificationId for 'où préparer ce diplôme'; resolve a city with resolve_location before using radiusKm. However, it does not explicitly name or contrast sibling tools such as search_trainings or get_training_center, so alternative-selection guidance is implicit rather than direct.

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 and destructiveHint, but the description adds substantial behavioral detail: each result carries establishment, price and a public URL; results are capped at 20; total may be null with totalAtLeast as a lower bound; and certification:null must not be interpreted as non-certifying. This goes far beyond what annotations provide.

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 long and bilingual, which adds bulk, but every sentence carries operational value—scope, result fields, pagination caveats, and the certification:null warning. It is front-loaded with the main purpose before diving into warnings, and the structure is logical.

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 complex tool with 17 parameters and no output schema, the description covers the essential runtime behavior: pagination limits, total semantics, null handling, result contents, and the ambiguous certification field. The parameter schema handles formats and enums, and the description compensates for the missing output schema.

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?

Even though schema coverage is 100%, the description adds critical semantics: radius replaces city/postalCode and results are distance-sorted, apprenticeship programmes are free, department format must be 'code - name', CPF eligibility is only a hint, and establishmentId ignores other filters. These enrich the schema meaningfully.

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 action—searching training programmes actually delivered in France—and enumerates the full range of filters, so an agent knows exactly what the tool does. It also distinguishes itself from siblings like search_training_centers by focusing on programmes, and from get_training by being the multi-criteria search entry point.

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 guidance on when to use the special establishmentId mode versus searching by school name in q, and explains response-page semantics. It does not explicitly name sibling tools or state when to prefer get_training or search_training_centers, but the context is clear enough for correct selection in most cases.

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