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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description goes beyond by explaining field semantics: appellateFate (with definitions), caseChronology, and commentaires, including warnings about interpretation ('read it before citing', 'absent fate never proves no recourse', 'context, never the ruling'). It also explains markdown link behavior and multi-article citation handling. 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 long but each sentence adds critical usage or interpretation context. It is structured logically: purpose, link behavior, field semantics, then warnings. While not terse, the density justifies the length and it remains readable and front-loaded with the core action.

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

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

With an output schema present, the description goes beyond by explaining the meaning of fields and how to interpret them, including caveats. It also covers how to open linked resources. Nothing essential is missing for an agent to call it correctly; it even warns about potential misinterpretations.

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 single parameter `url` is fully described in the schema (100% coverage), including where to obtain it (from search_decisions hit or citation link). The description repeats this but adds no new semantic detail beyond the schema. Baseline 3 applies.

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

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

The description states a specific verb and resource: 'Fetch the full text and metadata of a decision by its `url`.' It clearly distinguishes from search_decisions (search) and get_legal_text (articles) by specifying the action and input. The purpose is unambiguous and immediately understandable.

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

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

The description explicitly tells when to use this tool versus alternatives: it says to use search_decisions first if you don't have a URL, and to use get_legal_text for article links. It also references get_decision for decision links, making the decision tree clear. No inference is required.

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 the tool as read-only and idempotent, so the bar is lower for adding behavior context. The description goes well beyond this: it details how versioning works (inline links point to the same date when served at a date), how `commentaires` are delivered (inline or by link), and how absent `num` indicates the whole text. It also clarifies that `section` entries return all articles at once, adding genuinely useful behavioral nuance.

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 efficient. Every clause serves a purpose: the core function, the date semantics, the output contents, linking behavior, commentary handling, coverage scope, and special cases. It is front-loaded with the main purpose and uses compact, technical language without fluff. The length is justified by the tool's 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 5 optional parameters and an existing output schema, the description covers most operational details: versioning, date handling, link semantics, and edge cases like texts without articles. It does not mention the response format (but the output schema covers that). It could be slightly more explicit about exclusions (e.g., that it does not search or return lists of texts), but it is otherwise complete for correct invocation.

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

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

Schema description coverage is 100%—every parameter already has a detailed description in the schema. The description adds some context about composing URLs and the distinction between text-level and article-level requests, but this is largely already captured in the parameter descriptions. The baseline of 3 applies because the schema carries the load, and the description does not need to compensate.

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 begins with a clear verb and resource: 'Fetch a legal text, or one of its articles, as it stood on a given date.' It states exactly what is returned (version in force, status, validity dates, timeline) and is easily distinguishable from siblings like search_legal_texts, which is for searching rather than fetching a specific 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 tells the agent where to obtain URLs ('take it from a search_legal_texts hit or an inline citation link'), implying a workflow with its sibling. It also explains when to omit the date ('omit for today') and how to handle texts without articles. However, it does not explicitly state when to prefer this tool over search_legal_texts or get_decision, though the context makes it fairly obvious.

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, idempotentHint=true, and destructiveHint=false. The description goes beyond by explaining the return structure (shortlist with aiSummary/snippet, facets block, metadata), how filters combine (OR within, AND across), how to reuse facet keys verbatim, and the reranking latency trade-off. It also discloses the semantic matching limitation with negations. No contradictions with annotations; the description adds substantial 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 long but meticulously structured: it opens with the core purpose, then covers return format, filter semantics, facet usage, and ends with parameter-specific guidance. Every section earns its place given the 17 parameters and complex filtering logic, and the most important points (query regimes, filter combination) are front-loaded. No fluff; all sentences contribute to correct tool usage.

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 (17 parameters, rich filters, output schema), the description is thorough: it defines the return shortlist, the facets block, how to refine queries, the behavior of each mode, and how to interpret hit metadata. It also points to `get_decision` for full text, covering the workflow. Nothing essential for calling the tool correctly is missing, and the output schema's presence allows the description to avoid re-explaining return types.

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

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

Schema description coverage is 100%, yet the description adds significant meaning: it explains the two query regimes with examples, the mode behavior (auto switching to keyword-only on operators), how seat expresses both jurisdiction_type and jurisdiction_code, how legal_article requires an instrument prefix, and how facets map to filter values. This is far beyond the schema's basic parameter descriptions, providing actionable guidance for proper parameter usage.

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: 'Search decisions by meaning and keywords combined.' It clearly differentiates itself from siblings by noting 'get_decision reads the full text,' and 'search_legal_texts' is implied as a different search over legal texts. It also explains the scope of filtering for legal issues versus query semantics, making the tool's 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 provides explicit when-to-use guidance, including separating natural-language queries from exact-phrase/operator queries, explaining when to use `mode` (auto/lexical/semantic) and when to disable `ai_rerank`. It also instructs to 'Put constraints in the structured filters... keep the query for the legal issue,' and points to `get_decision` for full-text reading. This fully routes the agent to the right usage and 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds substantial behavioral context: returns a ranked shortlist with snippets and exact total, includes a facets block with per-filter article counts, and explains the point-in-time semantics of the date parameter (same as get_legal_text). 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?

Two dense sentences with zero filler. The opening states the purpose, then immediately gives usage, then facets, then chaining – all high-value information. No redundancy with the schema. The structure is front-loaded and every clause carries weight.

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 5-parameter search tool with a documented output schema, the description covers everything an agent needs: purpose, query construction, filter usage, facet-based refinement, and integration with the sibling tool. The point-in-time date semantics are explained. Nothing essential 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 coverage is 100%, so each parameter has a baseline description. The description adds value beyond the schema by advising how to structure the query ('put the code in the code filter, keep the query for the subject'), clarifying the code filter as 'as in facets.code', and explicitly tying date semantics to get_legal_text. This meaningfully enhances parameter usage, so above the baseline 3.

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

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

States a specific verb (Find), resource (legal articles), and the precise condition (when article number is unknown). Clearly distinguishes from siblings: search_decisions is for case law, get_legal_text is for retrieving a known article by URL. The purpose is 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?

Provides explicit, actionable guidance: query in French with descriptive terms, put the code in the code filter, keep the query for the subject. Explains how to reuse facets keys verbatim for refinement and how to chain hits into get_legal_text with url and date. This is far beyond vague 'when to use' – it is a usage manual.

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