justicelibre

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

The readOnlyHint annotation already declares safety, so the description adds context about what information the tool provides (source mapping, routing rules, identifier compatibility). No contradictions with annotations, and it enriches the agent's understanding of the tool's content.

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 sentences, front-loaded with the core purpose and immediately followed by usage guidance. Every word contributes meaning; no fluff or redundancy.

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 that this is a simple, zero-parameter help tool with an output schema, the description sufficiently explains what the tool tells the user and when to use it. It's complete for the agent to decide when to invoke 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?

The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters and instead focuses on the value delivered, which 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 clearly states the tool's purpose: an overview of the JusticeLibre protocol, covering source mapping and routing rules. It distinguishes itself from sibling search/get tools by being a meta-resource about the protocol itself.

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 instructs calling this tool first ('Appeler cet outil en priorité') to understand the compatibility matrix, search scopes, and database specifics. While it doesn't mention alternatives or when not to use it, the guidance is clear and contextually appropriate for a help tool.

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 tool is annotated readOnlyHint=true, and the description adds substantial behavioral context: it lists recognized identifier patterns, explains the effect of the optional legitext and date parameters (e.g., date appends a suffix to point to historical versions), and specifies that unrecognized formats yield an {'error'} return. 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 relatively long but well-structured: a clear opening purpose, a 'Utile pour' usage line, a bulleted list of recognized identifiers, and a structured Args section. Every sentence contributes necessary detail for a non-trivial mapping tool, though it could be tightened slightly without loss of clarity.

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 tool has a complex mapping table across multiple legal databases, and the description covers all critical aspects: identifier formats, parameter semantics, return shape, and error behavior. The highlighted edge case about date being essential for historical versions shows thoughtful completeness. The output schema is present, so return details are redundant, but the description still mentions 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?

With 0% schema description coverage, the description bears the full burden of parameter documentation. It explains all three parameters: identifier (the ID to convert), legitext (optional parent LEGITEXT for LEGIARTI to distinguish codes vs non-codified laws), and date (optional YYYY-MM-DD to target a historical version). Each is described with format and purpose beyond the bare 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 opens with a specific verb and resource: 'Construit l'URL canonique d'un document à partir de son identifiant.' This clearly defines the tool's function and distinguishes it from the sibling search/get decision tools, which retrieve data rather than construct source URLs.

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 states when to use the tool: 'Utile pour vérifier les sources à la main sur le site officiel ... ou pour inclure un lien cliquable dans un courrier.' It also details recognized identifier formats, giving the agent a checklist of supported inputs. It does not explicitly mention alternatives or when not to use, but the use cases are clear enough.

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 only declare readOnlyHint=true, so the description carries the burden of behavioral disclosure. It does this excellently: fallback behavior without jurisdiction, false 'not found' risk for TA numbers, reused numbers producing homonymes and avertissement fields, controlled jurisdiction matching, and date-sensitive behavior changes.

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 but well-structured with warnings, argument details, return shape, and examples. It earns most of its length, though the historical note about behavior before 23 August 2026 is arguably extraneous for an agent invoking the tool today, preventing a perfect 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?

For a two-parameter tool with significant ambiguity risk, the description is complete: exact-match semantics, jurisdiction disambiguation, fallback limitations, homonym warnings, return shape, error format, and concrete examples. The output schema exists and the Returns section complements it without unnecessary duplication.

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 0%, so the description must fully explain both parameters. It does: numero format and examples, juridiction accepted formats (full names, codes, short forms), ambiguity of bare city names, recommended usage for 7-digit numbers, and the controlled resolution behavior.

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 a specific verb and resource: retrieving an administrative decision by exact request number. It clearly distinguishes this tool from siblings by stating it covers all administrative jurisdictions and uses exact SQL lookup with no FTS5 and no false positives.

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 strong guidance on when to pass the jurisdiction parameter, when it is unnecessary, and what can go wrong if omitted. It stops short of explicitly naming alternative tools for fuzzy search, so the 'when-not-to-use vs alternatives' guidance is slightly implicit rather than fully 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?

The description goes well beyond the readOnlyHint annotation: it discloses exact-number matching, the risk of serving a citing decision instead of the cited one, the requirement to compare numero against numero_demande, and the structured error behavior for ambiguous or missing results. This is strong, actionable behavioral 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?

The description is longer than average, but each section earns its place: format, exact-match behavior, ambiguity warning, the get vs search distinction, and return structure. The key guidance is front-loaded and the bullet-and-warning layout makes it easy to parse.

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 covers input format, disambiguation behavior, the main sibling tool to use instead, return fields, and error responses. For a simple two-parameter read tool with a readOnlyHint annotation, nothing essential for correct 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?

The schema gives no descriptions for numero or nature, so the description has to compensate. It explains the expected format with examples, marks nature as optional, and explains why nature matters for ambiguous numbers, although the full set of nature values is left vague by 'QPC, DC, L, etc.'.

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 explicitly identifies the tool as retrieving a Conseil constitutionnel decision by its number, and clarifies the exact input format. It also distinguishes itself from the full-text search behavior, making the tool's scope unmistakable.

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 explicitly separates the two main uses: getting a decision itself via get_cc_decision, and searching for cases that cite that decision via search_cc. It also warns against full-text lookup and explains how ambiguity with respect to nature is handled, so an agent can route correctly.

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 annotation, the description discloses significant behavior: the dual-source JADE DILA/ArianeWeb fallback, the risk of reused pourvoi numbers, the homonymes and avertissement fields, and the structured not_found error category. This is rich, non-obvious behavioral context that prevents a potentially serious false-negative conclusion.

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 but every section earns its place: purpose, lookup strategy, alternative routing, the reused-number warning, and return/error contracts. It is well-structured with Args and Returns labels, and the critical ambiguity warning is clearly highlighted.

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 lookup tool with one required parameter, the description fully covers how to call it, what sources it consults, what the response may contain (homonymes, avertissement), and what an error looks like. The output schema exists, and the description explains the semantics that schema metadata alone would not convey.

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 0%, so the description carries full responsibility for parameter meaning. It defines numero as "numéro de pourvoi" and gives concrete examples ("497566", "358109"), which is exactly what an agent needs beyond the bare schema type string.

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 a precise verb and resource: "Récupère une décision du Conseil d'État par son numéro de pourvoi." It clearly differentiates the tool from get_decision_text, which is used for DCE_* identifiers, and the sibling list confirms it is the dedicated pourvoi-number lookup.

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 exactly when to use this tool (by pourvoi number) and explicitly redirects DCE_* lookups to get_decision_text. It also clarifies the lookup strategy across two complementary databases, giving an agent clear expectations about how the tool behaves when it searches.

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 readOnlyHint=true, so the read nature is covered. The description adds error return structure (full_text vs. error dict with not_found), which is helpful. However, it fails to mention the 'id' parameter present in the schema, leaving ambiguity about which parameter to use. This incomplete disclosure reduces transparency.

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 brief (two short paragraphs) and front-loaded with purpose. Args and Returns are separated. It could be more structured (e.g., bullet lists), but it is efficient for the content provided.

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

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

Given the context (output schema present, annotations present, sibling list large), the description covers purpose and return format but lacks full parameter documentation (missing 'id' parameter) and no usage guidance relative to siblings. It is adequate but incomplete.

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

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

Schema description coverage is 0%, so the description must explain parameters. It explains decision_id (format and example) but completely omits the 'id' parameter. For two parameters, only one is documented. This partially compensates but leaves the other parameter unexplained.

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 extracts the full text of a European Court of Human Rights decision based on its system identifier (itemid HUDOC). This distinguishes it from sibling tools for other courts (e.g., get_cc_decision, get_cjue_decision) or search functions. The verb 'extraction' and the resource are specific.

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 usage when you have an itemid HUDOC ID, but does not explicitly tell the agent when to use this vs. alternatives like search_cedh for finding IDs. No mention of prerequisites or exclusions. Guidance is implicit only.

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, so the description only needed to add contextual behavior. It discloses that a decision with full_text is returned or a structured error dict with error category 'not_found' for unknown CELEX. This complements the annotation without contradicting it.

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-structured: purpose, constraint, alternative, then args and returns. It is concise with minimal redundancy. However, the 'Args:' section repeats information already in the schema, and the example could be integrated more compactly.

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 provides the core usage context: input format, data source, return shape. The output schema exists, so detailed return specification is less necessary. However, failing to explain the 'id' parameter leaves a critical gap, making the description incomplete for a tool with two parameters and zero schema-level descriptions.

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

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

Schema description coverage is 0%, yet the description only documents one of the two parameters (decision_id) with an example. The second parameter 'id' is completely unexplained, and its purpose or relationship to decision_id is unclear. This is a significant deficiency for a tool with two parameterized inputs.

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 verb ('Extraction') and resource ('texte intégral d'une décision de la Cour de justice de l'Union européenne'), specifying the required identifier type (CELEX). It distinguishes this tool from siblings like search_cjue by explicitly limiting input to CELEX identifiers and directing users to search_cjue for ECLI-based lookup.

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 provides explicit when-to-use (when a CELEX identifier is already known), when-not-to-use (if only an ECLI is available), and the exact alternative (search_cjue to find the CELEX). It also states a prerequisite: the CELEX must first be retrieved via that sibling tool.

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 discloses the need for OAuth2 authentication and notes that credentials must never transit through the conversation, adding behavioral context beyond the `readOnlyHint` annotation. It also states the tool's inoperability for certain decision formats. Minor deduction as it does not describe any other traits like rate limits or error handling, but the annotation already covers safety.

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 concise and well-structured with a clear purpose, usage notes, and parameter explanations. It is front-loaded with the core action and uses bullet-like structure for constraints. Slight wordiness in the authentication section, but overall efficient for the complexity.

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

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

Given the tool's moderate complexity (3 parameters, no required ones, no enums, with output schema), the description is complete. It covers purpose, alternatives, exclusions, authentication, and parameter semantics. The output schema exists, so return values need not be explained. No gaps remain for an agent to misinvoke the 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 schema description coverage is 0% (no schema descriptions), so the description must compensate. The description explains the `decision_id` as a Judilibre identifier and `session_token` as a temporary token, adding meaning beyond the schema's empty defaults. However, `id` (a third parameter) is not explained in the description, leaving a semantic gap. Baseline 3 with moderate compensation.

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 it extracts the full text of a judicial decision via the restricted PISTE API, specifying the exact resource ('décision judiciaire') and the action ('extraction du texte intégral'). It differentiates from the sibling tool `get_decision_judiciaire_libre` by clarifying that the latter should be used for open-access DILA decisions.

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 provides explicit when-to-use guidance: it should be substituted by `get_decision_judiciaire_libre` when the decision is in DILA open archives, and it is explicitly inoperative for administrative court decisions (formats DCE_*, DTA_*, etc.). It also details authentication prerequisites and alternatives, giving clear context for use.

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 provide readOnlyHint=true, so the description adds value by stating no authentication needed and specifying accepted ID formats. It does not cover error behavior or what happens on invalid IDs, but the output schema exists to describe return values, making this a minor gap. No contradiction with 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 well-structured with a clear purpose sentence, followed by constraints and an explicit exclusion. The Args section is somewhat redundant with the schema but adds clarity. No wasted words, though the missing parameter documentation reduces efficiency.

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

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

Given the tool's complexity (2 parameters, 0% schema coverage, many siblings, output schema present), the description covers most key aspects: purpose, ID formats, exclusion. However, it fails to explain the 'id' parameter, which is a significant gap. The output schema likely covers return values, so that is acceptable.

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 0% and the description only explains the 'decision_id' parameter with format examples. The 'id' parameter is entirely undocumented, leaving the agent uncertain about its purpose or whether it is an alias. Given the low schema coverage, the description should clarify both parameters but fails to do so.

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 extracts full text of a judicial decision from an independent index without authentication. It explicitly distinguishes itself from sibling tools by specifying it is inoperative for administrative decisions and only works with specific ID formats (JURITEXT*, CONSTEXT*, JURI*), which differentiates it from get_admin_decision, get_ce_decision, etc.

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 provides explicit when-to-use guidance: it accepts only judicial free IDs returned by search_judiciaire_libre. It also gives a strong when-not-to-use statement: it is formally inoperative for administrative decisions. This helps the agent select the correct tool among many siblings without naming alternatives explicitly.

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 discloses a critical caveat not visible in annotations: when texte_integral is false, full_text is only the summary, and warns never to cite it as an extract. It also documents the structured not_found error dict and alternative tools. The readOnlyHint annotation is consistent with 'extraction', so there is no contradiction.

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 but tightly structured: purpose, accepted identifiers, incompatibilities, args, returns. It is front-loaded with the core purpose, and every section carries necessary operational detail rather than 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?

For a complex lookup tool, the description covers identifier variants, incompatibility routing, return semantics, a data-availability caveat, and the error contract. The only notable gap is the undocumented id parameter in the input schema; otherwise an agent has enough context to invoke the 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?

With 0% schema coverage, the description must document the parameters. It richly explains decision_id's accepted formats (DCE_..., DTA_..., DCAA_..., CETATEXT..., ArianeWeb) and the .xml suffix tolerance, but it never mentions the schema's other parameter, id. An agent may be uncertain whether id is an alias, a deprecated field, or a separate identifier.

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 a specific verb and resource: 'Extraction du texte intégral d'une décision relevant de l'ordre administratif (Conseil d'État, TA, CAA)'. It clearly distinguishes accepted identifier types and explicitly routes incompatible identifiers to sibling tools, so the tool's role is unambiguous.

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?

A dedicated 'Identifiants acceptés' section enumerates valid inputs, and 'INCOMPATIBILITÉS MAJEURES' states exactly when to use get_decision_judiciaire_libre/get_decision_judiciaire, get_decision_cjue, or get_decision_cedh. This is explicit when-to-use/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?

Beyond the read-only annotation, the description discloses important behavioral traits: a 1992 citation actually returns the pre-2016 rewritten text, the returned text may differ from requested date and then a `note` is provided, `titre_texte` names the parent code, and the LEGISCTA hierarchy is unavailable. This is rich, metadata-adding context that prevents incorrect agent interpretation.

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 moderately long but every sentence adds necessary context. It is organized into a summary, a Justicelibre-specific caveat, supported-code guidance, Args, Returns, and a warning section. Nothing is redundant or filler; the most important purpose is front-loaded.

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 tool with three parameters and rich historical/corpus edge cases, the description answers all likely agent questions: what inputs mean, how output is structured, what caveats apply, how to handle unsupported identifiers, and what information is intentionally absent. The output schema exists and the description reinforces it without unnecessary repetition.

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 has no per-parameter descriptions (0% coverage), so the description fully compensates. It explains `code` with supported examples, `num` with concrete values like '1128' and 'L1152-1', and `date` as optional ISO YYYY-MM-DD with user instructions. Every parameter is given meaning beyond its type.

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 a concrete verb, target resource and temporal scope: 'Renvoie le texte d'un article de loi à une date donnée'. It also clarifies a non-obvious historical-version behavior, which removes ambiguity about what 'version' means, and distinguishes this tool from sibling tools like get_law_versions or search_legi.

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 guidance on when to use the tool, how date should be set ('Utiliser la date de la décision citante'), and what to do outside the supported corpus: for unsupported texts, pass a LEGITEXT/JORFTEXT identifier and use resolve_law_number(). It even tells the agent to redirect to Légifrance rather than inventing LEGISCTA hierarchy.

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 readOnlyHint annotation already signals a safe read operation, and the description adds meaningful behavior: versions are returned ordered by date_debut ascending, with each version carrying date_debut, date_fin, etat, and texte. This gives the agent a clear model of what the operation returns and how it behaves.

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 structured into a one-line purpose, a practical use-case example, Args, and Returns. Each section earns its place, and the example adds clarity without unnecessary length.

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, two-parameter retrieval tool with an output schema, the description covers selection context, parameter semantics, code-source lookup, and result ordering. It also explicitly supports the historical-version use case, so a capable agent has what it needs to choose and invoke the 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 input schema has 0% description coverage, so the description must compensate. It does that well enough: code is explained as a short code with a pointer to get_law_article and the ~80 supported codes, while num is described as the article number. The num explanation is terse, but both parameters are meaningfully clarified beyond the bare property names.

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 first sentence states a specific verb and resource: it returns all historical versions of a law article, ordered oldest to newest. The historical scope clearly differentiates it from the sibling get_law_article and other search 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?

The description explicitly frames the tool as useful for building an article timeline and understanding its evolution over time, with a concrete 1964/1994/2016 example. It does not explicitly say when not to use it or name get_law_article as the alternative for the current version, so it lacks an explicit when-not statement.

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=true; the description adds meaningful behavioral detail: exhaustive coverage, 51 instances broken down by type, the JADE-bulk-only caveat for TC and CDBF, and accepted name formats. This goes well beyond the structured 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 compact, front-loaded with the main output, and every sentence earns its place: scope, contents, consumer tools, and special cases. 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?

For a zero-parameter, read-only list tool with an output schema, the description covers scope, counts, exclusions, aliases, and downstream consumers. Nothing an agent needs to decide to call it 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, so the baseline is 4; there is no parameter semantics for the description to add. The schema already covers everything.

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 ('Restitue les 51 instances couvertes') and a precise resource (exhaustive jurisdictional codes), distinguishing it from sibling search/get tools by explicitly naming which tools consume those codes. It is more than a restatement of the name and title.

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 clearly conveys the tool's role as a source of valid jurisdictional vocabulary for `search_admin`, `get_admin_decision`, and `search_admin_recent`, and notes that full names and short forms are also accepted. It does not explicitly state when not to use it, but the 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?

The readOnlyHint already signals a safe read operation, and the description adds useful behavioral detail: the tool returns a structured object including article count and source URL, and returns {error} when not found. This goes beyond the annotation and gives the agent expectations about failure modes.

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-structured and front-loaded: what the tool returns, when to use it, how to use it after, and concrete examples. Every sentence earns its place, and the parameter and return format sections are scannable.

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

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

For an input schema with a single undocumented string parameter, the description covers input format, output shape, error case, supported text types, and integration with related tools. Nothing important is missing for an agent to select and 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?

Schema coverage is 0%, so the description must fully explain the lone parameter, and it does: it specifies the expected format 'YY-NNNN' or 'YYYY-NNNN' with concrete examples. The examples (68-1250, 79-587, 2000-321) make the input semantics unambiguous.

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 — resolving a law/ordonnance/décret number to a LEGITEXT or JORFTEXT identifier — and clearly distinguishes it from the many search/get sibling tools. It also clarifies the scope (non-codified texts, not the ~80 short codes), so an agent can tell this tool apart from search_legi or get_law_article.

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 says this is useful for non-codified texts that are not in the list of ~80 short codes, which is a clear when-to-use signal. It also explains the follow-up workflow with get_law_article, giving the agent a concrete integration path and an implicit alternative.

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?

With readOnlyHint=true, the annotation already signals safety, and the description adds substantial behavioral context: BM25 ranking, full-text corpus size, FTS5 operator support, jurisdiction filter aliasing, and the documented fallback behavior for unrecognized jurisdiction values where the value becomes a keyword and the response notes it.

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?

Although long, every section earns its place: purpose, sibling differentiation, a high-value routing warning, and a structured Args block. The most important operational caveats are front-loaded, and the format follows the schema's parameter order.

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

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

Given the tool has 7 parameters, zero schema description coverage, and a non-trivial jurisdiction filtering quirk, the description is complete. It covers ranking behavior, filters, pagination, result shape, sibling alternatives, and malformed input handling, leaving no critical gap for an agent to call it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it fully compensates. Every parameter is explained with types, defaults, accepted values, and practical examples, including a detailed warning about `juridiction` normalization and the `note` field behavior.

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 pondérée par pertinence BM25 sur la jurisprudence administrative complète', enumerating the exact courts covered. It also distinguishes itself from `search_admin_recent*` by explaining the relevance-based ordering, making it easy to select among 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 contrasts with `search_admin_recent*` tools and tells the agent this tool is for finding the best decisions on a topic regardless of age. It also gives a clear exclusion: for 7-digit request numbers, use `get_admin_decision` instead, because FTS5 only finds citations, not the ruling 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?

Beyond the readOnlyHint annotation, the description reveals that results are sorted by read date descending, the API is live, the coverage is since ~2022, and generated IDs are compatible with get_decision_text. It also discloses the edge case where isolated 'TA' or 'CAA' codes return empty results. This significantly exceeds annotation-only 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?

The description is moderately lengthy but well-structured with a bold summary, usage guidance, scope, compatibility note, and an Args section. Some redundancy exists between the opening line and the explanation of date sorting, but overall every section earns its place and the structured format improves scannability.

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 tool has three parameters, an output schema, and a readOnly annotation. The description fully covers all parameters, provides explicit use cases and exclusions, describes the scope and sorting behavior, and includes a compatibility note with get_decision_text. With an output schema present, the description does not need to explain return values, and it provides comprehensive context to guide correct 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 provides only names/types/defaults with no descriptions. The description compensates by explaining the query semantics, providing detailed juridiction code examples (CE, CE-CAA, TA69, TA75, CAA69), noting the empty-result edge case, and clarifying the default for limit. This adds substantial meaning beyond 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 clearly states the tool searches recent administrative decisions sorted chronologically via a live API. It explicitly distinguishes it from search_admin by noting the focus on 'actualité' rather than relevance, and specifies the scope and ID formats. This leaves no ambiguity about what the tool does.

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 states when to use the tool (for recent decisions of a jurisdiction) and when not (for finding relevant jurisprudence), naming search_admin as the alternative. It also provides detailed examples for the juridiction parameter and warns about empty results for isolated TA/CAA codes, with a pointer to list_juridictions for full nomenclature.

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 provide readOnlyHint=true. The description adds valuable behavioral details: simultaneous querying, merging, chronological sorting by reading date, and limit behavior (per-court default 5, total limit cap). No contradictions with 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 appropriately sized, with a clear two-sentence overview followed by a structured Args section. Every sentence adds value and there is no redundancy.

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 covers the tool's core behavior and parameters; an output schema exists, so return values need not be explained. It is complete for a search tool, though it lacks explicit notes on edge cases or prerequisites beyond what the schema implies.

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

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

Schema description coverage is 0%, so the description must fully compensate. It explains all three parameters (query, limit_per_court, total_limit) with meaningful context, including defaults and the meaning of total_limit=0, going well beyond the bare 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 clearly states the tool performs a simultaneous query of all 9 Cours Administratives d'Appel, with fusion and chronological sorting. This specific verb+resource distinguishes it from siblings like search_admin_recent and search_admin_recent_all_ta.

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 clearly conveys the context: use this tool to search across all 9 CAA simultaneously. It does not explicitly name alternative tools or exclusions, but the context is unambiguous given the sibling list.

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 explains behavior beyond the readOnlyHint annotation: it reveals that results are merged and sorted by decreasing date, explains the effect of total_limit (truncation to N most recent entries), and states that the return dict includes per_court_totals, decisions, and errors. This provides substantial context for expected behavior without contradicting 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 well-structured: a one-sentence summary, a fusion/sorting explanation, a use-case statement, and clearly separated Args/Returns sections. Every sentence contributes new information with no fluff, making it appropriately concise for the complexity.

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 covers the tool's complete behavior: scope (all 40 TAs), sorting, parameter semantics, limit interactions, and return structure. The mention of 'eventuelles errors' addresses error handling. Despite having an output schema, the description adds enough context to fully understand the tool's operation.

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?

Despite 0% schema description coverage, the description dedicates an Args section to fully explain query, limit_per_court (default 5, up to 200 results before total_limit), and total_limit (default 60, 0 = no cap). This adds critical meaning that the schema's bare titles lack.

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 a specific verb and resource: 'Requête simultanée de l'ensemble des 40 Tribunaux Administratifs' (simultaneous query of all 40 administrative tribunals), clearly distinguishing it from sibling tools like search_admin_recent_all_caa. It also explains the fusion and chronological sorting, making its function unambiguous.

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 a clear intended use case: 'Pertinent pour cartographier rapidement les éventuelles divergences d'appréciation territoriale sur une même question de droit' (useful for quickly mapping potential territorial divergences in legal interpretation). It does not explicitly list alternatives or exclusions, but the context strongly implies when to use this tool over general search_admin.

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

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

Beyond the readOnly annotation, the description discloses crucial non-obvious behavior: there is deliberately no global score, BM25 scores are not cross-source comparable, results are interleaved with authority ordering, and the old score field was removed. It also explains source_rank, per-source caps, error handling, and truncation signals, giving an agent a complete behavioral model.

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?

Though long, the description is densely informative and well-structured with bold warnings, an Args block, and a Returns block. Every sentence adds value: the no-score explanation prevents a common misinterpretation, the synonym caveat prevents query failure, and the output contract saves the agent from guessing. It is front-loaded with purpose and the most dangerous pitfalls.

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

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

Given the tool's complexity, schema with no descriptions, and output schema that only exists as a prose Returns block, the description is complete. It covers what the tool does, when to use it, how the parameters behave, what the interleaved results mean, and how failures are reported via source_errors and warning. Nothing essential for correct 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?

The input schema's property descriptions provide no coverage, but the description fully compensates with an Args section covering all seven parameters. It explains defaults, the synonym-expansion behavior with explicit examples and exclusions, the optional sources list, the sort modes, date format, and the limit cap including the per-source maximum of 50.

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 a specific verb and resource: 'Recherche fédérée sur toutes les sources' and positions itself as a ONE-STOP tool for when the user does not know where to look. It names the five federated sources explicitly, which clearly distinguishes it from the many single-source sibling tools like search_legi or search_cedh.

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

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

It gives clear when-to-use guidance: use it as a one-stop when unsure which source holds the answer. It also provides actionable search-strategy advice (prefer 2 to 5 distinctive words, avoid natural-language queries) and explains the implicit-AND constraint. It does not explicitly name sibling tools as alternatives when the user already knows the source, so it stops short of full exclusion 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?

Beyond the readOnlyHint annotation, the description discloses the aggregation of multiple data sources, the alpha status with no BM25 ranking, the simple relevance ordering (mail > organisme > service), and the full traceability fields for PDF-sourced entries. It even mentions licensing and the need to cite archived copies if originals disappear. This is exemplary transparency with no contradictions.

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-structured with a one-line purpose, a bulleted list of sources, search behavior, parameter details, and return format. It is dense with no filler, and the sections are clearly separated. The minor '3 vs 4 sources' inconsistency does not harm conciseness.

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 covers everything needed to invoke the tool correctly: purpose, data sources, search semantics, all parameters, and the complete return structure, including special fields for scraped PDF entries. It also notes the alpha status and ranking limitation. No significant gaps remain for this complexity level.

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

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

Schema description coverage is 0%, but the description fully compensates with an 'Args' section that explains each parameter with concrete examples and constraints, including default and max for limit, allowed category and source values, and keyword examples for query. This far exceeds what the schema 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 opens with a specific verb and resource: 'Recherche dans l'annuaire agrégé des adresses électroniques publiques des juridictions et administrations françaises.' It clearly distinguishes itself from sibling legal-document search tools by focusing on public email addresses. The only minor flaw is the '3 sources' label followed by 4 bullets, but this does not obscure the purpose.

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 provides clear context about the tool's domain and search behavior, such as 'Recherche : substring case-insensitive sur mail, organisme et service' and practical query examples. However, it does not explicitly state when not to use it or compare it to alternative tools, so it falls 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.

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

Annotations declare readOnlyHint=true, and the description adds substantial behavioral context: it covers the number of decisions, the nature filter options and their meanings, the use of FTS5 operators in query, and the return object structure. It does not mention rate limits or authentication, but these are not critical 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?

The description is well-structured with clear sections for Args and Returns, and it is appropriately sized for the tool's complexity. The contextual sentence about the court is useful but slightly extends beyond the core purpose, though it does not become wasteful.

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 tool with 6 parameters (1 required) and a read-only annotation, the description covers all parameter meanings, defaults, constraints (limit max 50), and the response structure. No significant gaps remain, making it fully self-contained.

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 has no descriptions (0% coverage), and the description fully compensates by explaining every parameter: query keywords with FTS5, nature with an enumerated list of values, date range format, limit max/default, and offset for pagination. This transforms the schema from bare names to actionable 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 clearly states 'Recherche dédiée au Conseil constitutionnel (7 112 décisions)' as the first sentence, immediately identifying it as a search tool specific to French Constitutional Council decisions. It distinguishes from sibling tools by naming the court and explaining its role, making the purpose unambiguous.

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 provides clear context about when to use this tool: for searching decisions of the Constitutional Council, including constitutional review and election disputes. It does not explicitly mention alternatives or exclusions, but the dedicated scope implied by the description and sibling tool names gives sufficient 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?

Beyond the readOnlyHint annotation, the description discloses pagination behavior (truncated/next_offset), dataset size, and access conditions (free access, local index). This provides actionable information for the agent to correctly handle large result sets.

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 concise and well-structured, starting with a clear purpose statement, followed by context about the index, and ending with a clear Args list. Each sentence adds value without redundancy.

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

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

Given the tool's moderate complexity and the presence of an output schema, the description covers all essential aspects: scope, parameters, pagination, and access. No critical gaps are apparent.

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 provides no descriptions for parameters (0% coverage). The description fully compensates by explaining query keywords with examples, limit default/max, and offset's role in pagination, including the use of next_offset.

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 performs textual search in the case law of the European Court of Human Rights, specifying the resource (~76,000 HUDOC French-language documents). The name and description distinguish it from sibling search tools targeting other jurisdictions (e.g., search_cc, search_cjue).

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 provides clear context for when to use this tool (for ECHR case law) and gives example queries ('article 8 vie familiale', 'garde à vue'). However, it does not explicitly mention alternatives or when not to use it, unlike the TDQS 4.3 example which names a specific alternative.

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?

While the readOnlyHint annotation already indicates a safe read operation, the description adds useful behavioral details: pagination via offset/next_offset, truncation handling, and the note about free access. It does not mention any rate limits or additional side effects, but the core search behavior is transparent.

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 efficiently structured: a one-line purpose, a coverage note, a free-access note, and a clear Args list. Every sentence contributes necessary information, and the format is scannable.

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 search tool with an output schema, the description covers the essential aspects: scope, query syntax, result limits, and pagination behavior. It even anticipates the truncated response and next_offset, making it self-sufficient for an agent.

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?

With 0% schema description coverage, the description fully compensates by explaining each parameter: query with examples, limit with default and maximum, and offset with pagination logic. This adds meaning far beyond the bare schema types.

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 'Recherche textuelle dans la jurisprudence de la Cour de justice de l'Union européenne', clearly identifying the tool as a text search over CJEU case law. It further specifies coverage (CJEU, General Court, orders, AG opinions) and distinguishes it from sibling search tools targeting other courts (e.g., CEDH, CC).

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 provides clear context: it searches a localized index of CJEU decisions and is free to access. It gives example queries ('CJUE C-72/24') implying intended use, but does not explicitly state when not to use it or mention alternative tools for retrieving a single decision.

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 declare readOnlyHint=true, which is consistent with the read-only 'Recherche' action. The description adds the source bulk size (~27,000 deliberations), giving some context about the corpus, but doesn't disclose other behaviors like pagination limits or result formatting. This is acceptable for a read-only search but lacks depth.

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 extremely concise: two sentences, with the purpose front-loaded in the first sentence and supplementary context in the second. No unnecessary words or redundancy.

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

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

Given the tool's simplicity (search with query/limit/offset) and the presence of an output schema, the description covers the main purpose and usage context. However, it doesn't explain pagination behavior or any specifics about the return format, and the lack of parameter documentation leaves gaps, but not critical ones for a search 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 description coverage is 0%, and the description provides no parameter explanation. The agent must infer that 'query' is a search term, and 'limit'/'offset' are pagination controls, but these are not stated. The description adds no value beyond the parameter names in the schema.

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

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

The description clearly states the tool searches CNIL deliberations, with a specific verb and resource. It distinguishes itself from the many sibling search tools by explicitly targeting CNIL deliberations, a unique jurisdiction/topic.

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 provides useful context: 'Utile pour le droit des données personnelles, RGPD, traitements algorithmiques' indicates when to use it. It doesn't explicitly mention alternatives or when not to use, but the context is clear enough for the agent to choose this tool for CNIL-related searches.

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 indicate readOnlyHint=true. The description adds significant behavioral context: the engine uses Sinequa with context extraction, IDs are now usable by get_decision_text, coverage limitations, and query behavior (full sentences return zero results). This goes well beyond what annotations alone 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 relatively long but well-structured with bold text, emojis, and sections. Every sentence adds value (purpose, usage, caveats, parameters). It could be slightly more concise, but the detail is justified given the need to cover multiple important aspects.

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 tool with 3 parameters, an output schema (existence signaled by context), and many sibling tools, the description comprehensively covers purpose, usage context, coverage limitations, parameter semantics, and alternatives. The presence of an output schema means return value details are handled separately, so the description is complete for the agent's decision-making.

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?

Despite 0% schema description coverage, the description includes an 'Args' section that explains each parameter: query with examples, limit with default, offset with pagination instructions. This fully compensates for the schema's lack of 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?

The description clearly states the tool performs 'Recherche sémantique ciblée sur la jurisprudence du Conseil d’État' (semantic search on Conseil d'État case law), naming the database (ArianeWeb, ~270k decisions). It distinguishes from siblings by stating it should be systematically preferred for public law and by explicitly contrasting coverage with search_admin and get_decision_text.

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 advises when to use this tool ('À privilégier systématiquement pour le droit public') and when not to (for old decisions before ~1990, directing to search_admin). It also provides an alternative if the user already has a Légifrance ID, and gives search query constraints (2-5 keywords, avoid full sentences).

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 annotation, the description discloses concrete behavior: it exploits FTS5, matches common citation formulations, and explains failure behavior (source outages are absent from per_source and listed in source_errors). It also documents what the tool does NOT capture, which is critical for managing expectations.

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-structured: a clear opening purpose, a bolded limitation section, organized Args, and a Returns dictionary. It is longer than average but every part provides necessary operational detail, and the structure makes it easy to scan.

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

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

Given the tool's complexity, the description is complete: it covers purpose, usage, parameters, return format, limits, and failure modes. The output schema is indicated as present, and the Returns section in the description nicely complements it. No critical information 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?

With 0% schema description coverage, the description compensates fully. It explains each parameter: code with examples ('CT', 'CC'), num with examples ('L1152-1', '1240'), sources with allowed values and default, and limit with default and maximum. This is far beyond the bare 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 opens with a specific verb and resource: 'Cherche les décisions qui citent EXPLICITEMENT un article de loi donné.' It clearly distinguishes itself from siblings by emphasizing the inverse cross-referencing approach and explicitly contrasting with search_all for conceptual searches.

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 tool states when to use it (explicit citation lookup) and when not to use it, directing users to search_all with thesaurus expansion for conceptual queries. It also documents the known limitation, giving clear decision criteria for tool selection.

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 declare readOnlyHint=true, so safety is already covered. The description adds valuable behavioral details: source (bulk JORF DILA, 1.1 GB), content type (non-codified), and a hard limit on results ('limit: max 50'). This enriches understanding beyond the annotation alone.

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 concise and well-structured with an Args list and Returns line. Every sentence adds information without redundancy. It is easy to scan and understand.

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 covers purpose, source, content, all key parameters, and the return structure. Given that an output schema exists, the explicit 'Returns' line is a bonus. It is sufficiently complete for an agent to select and invoke the 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 coverage is 0%, so the description carries the burden. It explains query (FTS5 keywords), nature (with examples), date_min/date_max (ISO), and limit (max 50). Offset is not mentioned, but it is a common pagination parameter and has a default, so the description compensates well for most 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 clearly states the tool's function: 'Recherche dans le Journal officiel (JORF post-1990)'. It specifies the resource (JORF), the action (search), and the scope (post-1990) while listing content types (lois, décrets, arrêtés, circulaires, ordonnances). This distinguishes it from sibling tools like search_legi or search_admin.

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 provides clear context on what the tool searches (non-codified JORF texts) and the available filters (nature, date range). It does not explicitly name alternatives or say when not to use it, but the scope is unambiguous enough to guide selection.

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?

Although readOnlyHint=true already signals a safe read operation, the description adds substantial behavioral context: OAuth2 authentication is required, credentials never pass through the conversation, and there is an external technical constraint ('entrave technique'). It also details two authentication paths, which is valuable 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 longer than average but well-structured with sections for scope, usage guidance, authentication, and parameters. Each sentence contributes necessary information, especially given the authentication complexity. Slight verbosity is justified, though it could be tightened.

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

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

Given the tool's complexity, the presence of an output schema, and readOnlyHint annotation, the description is complete. It covers purpose, scope, usage conditions, authentication steps, parameter semantics, and even mentions alternatives. There are no significant gaps.

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

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

Schema description coverage is 0%, so the description carries full responsibility for explaining the parameters. It provides meaningful semantic meaning for each argument: query (keywords), session_token (temporary token obtained via the site), juridiction (with specific code mappings), and limit (default 20, max 50). This fully compensates for the bare 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 clearly states the tool performs a search in judicial case law (jurisprudence judiciaire) via the official PISTE API, with an explicit scope listing the covered courts. It also distinguishes itself from the free DILA base and from sibling tools like search_judiciaire_libre by emphasizing it is a last-resort option for recent decisions.

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 provides explicit usage guidance: use only as a last resort or for recent decisions missing from the DILA free base. It also mentions the technical hurdles imposed by the Cour de cassation, which helps the agent decide when this tool is appropriate versus alternatives.

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

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

Beyond the readOnlyHint annotation, the description discloses critical behavioral traits: results contain only truncated snippets, not full text; coverage is a subset of open data with known counts; false negatives do not imply absence; sorting is chronological descending despite BM25 availability; and the database is locally executed without authentication. This substantially exceeds what annotations already 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 but every section earns its place: bold headers separate coverage, RG lookup, snippet warning, and argument details. It front-loads the core purpose and usage distinction, then provides dense but non-redundant parameter documentation.

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 search tool with no schema descriptions, the description is remarkably complete: it covers coverage limitations, snippet-only behavior, pagination, decision_id formats for follow-up calls, and fallback alternatives. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden for all 7 parameters. It compensates thoroughly: query syntax examples, juridiction enum values with aliases, numero_rg normalization variants, ISO date formats, limit defaults/max, and offset pagination behavior including truncated and next_offset.

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 a specific verb and resource: full-text search of judicial case law, executed locally with no government authentication. It clearly distinguishes itself from siblings by naming search_judiciaire (PISTE) as the authenticated alternative and get_decision_judiciaire_libre as the full-text retrieval companion.

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 states when to use this tool versus alternatives: use PISTE or Légifrance when this search returns nothing, and call get_decision_judiciaire_libre for full decisions. It also gives precise routing guidance for RG numbers versus Cass pourvois, leaving no ambiguity about tool selection.

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 provide readOnlyHint, and the description adds valuable context about the data source size, coverage, and IDCC identification. This goes beyond the annotation's safety hint, though it doesn't detail result ordering or pagination 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 compact and well-organized, with a clear purpose first, then source context, then parameter guidance. Every sentence is informative, no fluff.

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 covers purpose, source, relevant parameters, and includes limit constraints. It lacks explicit mention of offset and doesn't differentiate from siblings beyond domain, but overall is sufficiently complete for a search tool with an 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?

With schema description coverage at 0%, the description compensates by explaining query, idcc (with a concrete example), and limit (max 50). It omits offset, a minor gap, but otherwise adds meaningful semantic detail beyond 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 clearly states the tool searches collective agreements (KALI), specifying the resource type, source (bulk KALI DILA), and coverage. The verb 'Recherche' and the specific domain distinguish it from sibling search 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?

The description provides clear context on what is searched (national collective agreements, branch agreements, riders, identified by IDCC), implying when to use it. However, it does not explicitly mention alternatives or exclusions, so it falls short of a full 5.

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?

Even with readOnlyHint=true, the description adds substantial behavioral context: weighted search, deduplication by parent text, the meaning of returned vs total, the titre_texte caveat about LEGI section hierarchy, explicit error behavior for unknown code sigles, limit max 50, and date filter semantics. It even discloses a past misleading behavior (titre_section).

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 but well-structured, with purpose, source, caveats, args, and returns clearly separated. Each sentence adds value, and the warnings are important. It is slightly long but not 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 an output schema present, return values need not be explained, but the description still includes them. It covers source context, deduplication semantics, field caveats, parameter constraints, and error behavior. An agent has everything needed to select and 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?

Schema description coverage is 0%, and the description fully compensates with an Args section explaining every parameter: query (FTS5 keywords), code (sigle or LEGITEXT/JORFTEXT, error on unknown), date_min/date_max (ISO version start date), limit (max 50), and offset (pagination). This goes well beyond the bare 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 states a specific verb and resource: 'Recherche pondérée dans les codes et lois consolidés français' and 'Trouve les articles dont le texte ou le titre contient les mots-clés.' This clearly distinguishes it from decision-focused or journal-officiel search tools, though it does not explicitly name a sibling alternative.

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 intended use is implied through the resource description (LEGI codes/laws) and extensive notes about filtering and deduplication. However, there is no explicit guidance about when to use this tool versus siblings like search_all, get_law_article, or search_jorf.

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