French family benefits (CNAF corpus)

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real semantic value the annotations do not: the matrix describes what is *actually installed* versus declared, and it defines declared_only as 'a schema without an executable witness', which tells the agent how to interpret unconfirmed entries.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, with the content inventory front-loaded and the glossary notion of declared_only appended as a clarifying second sentence. Dense but every clause adds information.

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

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

With no input params and no output schema, the description carries the burden of explaining what comes back, and it does so by enumerating the matrix's sections and defining its key status term. Missing only guidance on when in a workflow to call it relative to sibling inspection tools.

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 takes zero parameters, so the baseline of 4 applies. The description correctly implies a parameterless snapshot by framing the output as a machine-readable matrix rather than a filtered report.

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

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

The description names a specific resource and enumerates its contents (installed Lens producers, replay/projection controls, profiles, limits, contract tests), so the agent knows this is an introspection/capabilities-matrix tool rather than a query tool. It does not differentiate itself from siblings such as law_inspect, law_packages or law_rules, which also sound like introspection endpoints.

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?

There is no statement of when to call this tool, no prerequisites, and no mention of any alternative. The agent must infer from the name and content list that this is the discovery endpoint to use before other Lens calls.

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 read-only/non-destructive, and the description adds substantial context beyond them: what the response carries (applied rules, warnings, provenance with fingerprints, a signature block), the semantics of "non établi" and the why_not report, the no-invention guarantee, MISSING_POLICY behavior for deadlines, and the version-mismatch refusal. It also discloses that responseMode=compact returns the full answer unchanged.

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 purpose is front-loaded in the first sentence, but the remainder is a single dense wall of text that mixes prerequisites, error semantics, and per-kind definitions, and re-explains the why_not report twice. Little of it is filler, yet the size and duplication make it harder to scan than it needs to be.

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 22-parameter tool with nested objects and no output schema, the description covers the workflow, error handling, and rough shape of the return value (rules, warnings, provenance, signature block). It is close to complete, though a tighter statement of the default return payload would remove the last ambiguity.

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

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

With 95% schema coverage the baseline is 3, and the description adds real meaning on top: each kind value is spelled out behaviorally, focused/proof are tied to law_explain and law_prepare_answer, and version/deadlinePolicy/responseMode get operational nuance not present in the schema. The remaining parameter plumbing (args notation, facts shape) is left to 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 opening sentence names a concrete verb+resource ("Poser une question au droit formalisé") and the body enumerates the six question kinds, so the agent knows exactly what the tool answers. It also differentiates itself from siblings by naming law_search/law_packages as prerequisites and law_explain as the consumer of the proof graph. It falls short of 5 only because the core purpose statement is buried under a dense block of behavioral rules.

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

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

Explicitly states the precondition for the first call (obtain predicate names via law_search or law_packages; an invented name is rejected) and names both alternatives with their conditions. It also gives when-not guidance: an error or "non établi" IS the answer and must not be substituted, while "no suitable act found" is not an answer until law_search has been queried.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false and idempotentHint=false, so the safety profile is covered by structured data. The description adds the registry-limited producer constraint and names the produced artifact, but it does not explain why the operation is non-idempotent or what execution entails, which is the one behavioral trait the annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the action, so there is no filler. The terseness tips into under-specification rather than disciplined brevity, and the dense jargon makes the little text present harder 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?

For a tool with a required nested object, no output schema, no parameter descriptions, and a domain-specific artifact ('producerControl/0.2'), the description does far too little. Naming the artifact helps slightly, but the caller still lacks the request shape, expected result, and workflow context needed to invoke 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 coverage is 0% for two parameters, so the description must carry the semantics. It clarifies that 'producer' must come from the delivered registry, which is genuinely useful, but the required nested 'request' object is left entirely unexplained in both schema and description.

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

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

The description names a verb ('Exécuter') and a resource ('un producteur enregistré') plus the returned artifact ('producerControl/0.2'), so it is more than a restatement of the name. However, the vocabulary is opaque jargon (Lens, producerControl/0.2, registre livré) and it never distinguishes itself from sibling tools like law_prepare_answer or law_publish_answer, so an agent cannot readily tell why this step comes first.

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?

There is one implicit constraint – 'Le producteur n'est choisi que dans le registre livré' – but no statement of when to call this versus the many prepare/publish/ask siblings. No prerequisites, ordering, or exclusions are given, leaving the agent to guess at the workflow position.

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, destructiveHint=false, idempotentHint=false and openWorldHint=false, and the description adds real behavioral context on top: the default response is a projection without the proof graph, proof:true/full returns the canonical document with proof and manifest, and a preparation refusal surfaces as an LDC-* error rather than an empty response. The explicit error contract is particularly valuable, though return-field specifics remain thin.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and default behavior are front-loaded, but the single dense paragraph chains multiple semicolon-separated clauses (response modes, four input forms, error contract) that would read better as discrete sentences. No obvious filler, yet the run-on structure reduces scanability.

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 9-parameter, no-output-schema, read-only tool, the description covers the response-shape distinction, input-mode combinations, and failure semantics. What it omits is guidance on the sibling-tool landscape and the concrete contents of the projection beyond a few named fields, but overall it is sufficient to call 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 100%, so baseline is 3, but the description adds cross-parameter semantics the schema does not: 'evaluate' requires queryId, queryId alone selects a registered query, and card+args is an alternative input mode. These interactions help the agent assemble a valid call beyond what per-field descriptions convey.

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

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

States a specific verb and resource ('exécuter une affaire enregistrée d'un paquet-affaire') and describes the returned artifact (projection vs canonical evaluation document). It references the sibling law_ask for shape parity but never explicitly differentiates this case-scoped tool from law_ask or law_query, so an agent must infer the distinction.

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 enumerates the accepted input forms (query, evaluate+queryId, queryId, card+args) but gives no when-to-use guidance relative to the many sibling tools (law_ask, law_query, law_prepare_answer). It never states when this tool should be chosen over an alternative or any precondition beyond 'an enregistrée affaire'.

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

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

Annotations already declare readOnly/non-destructive/openWorld=false, so the safety bar is met. The description adds genuine behavioral detail beyond that: the server repeats the computation and compares fingerprints, explicitly refusing when something changed; nodeId returns up to 24 Ko or refuses; and answerResource explains a stored snapshot with no recomputation. These are meaningful operational traits an agent needs.

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?

It is a single dense paragraph but front-loads the core purpose before enumerating the input modes, and each sentence carries a distinct piece of information (recompute/refuse, snapshot path, nodeId selection, hash semantics). It leans toward run-on density rather than clean separation, but there is little 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?

Given an existing output schema, the description need not explain return values, and it covers the complex oneOf input mode well: the three accepted shapes, the hash-verification/refusal contract, and the nodeId size limit. For a nested-object, multi-mode tool this is nearly complete, with the only loose end being the stray proofHash/scope references.

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 only 50% schema description coverage, the description usefully compensates: it explains question as the original law_ask arguments (truth/collect), resultHash/codeHash as coming from the answer provenance, nodeId as selecting a node plus all its premises with a 24 Ko cap, and answerResource as fullAnswer.uri. It does mention proofHash and scope, which do not appear in the schema properties, which could mildly confuse, but the documented parameters are well clarified.

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

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

The description gives a specific verb and resource — 'Déplier la preuve d'une réponse law_ask en une chaîne règle ← prémisses → conclusion' — and names law_ask as the originating sibling, so the agent can distinguish it from plain answer retrieval. It is clear what the tool produces (a proof chain), though it does not contrast itself against other siblings like law_inspect or law_query.

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 lays out three distinct invocation modes with their conditions: the compact question/resultHash/codeHash path (server recomputes and verifies hashes), passing the evaluation from law_ask(proof=true), and answerResource=fullAnswer.uri for a stored snapshot without recomputation. That is explicit when-to-use guidance, though it stops short of stating when to prefer another sibling tool instead.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavioral semantics beyond them: nothing is evaluated or recalculated, and absent data is a limit state, never a negation. That last point is a meaningful caveat an agent would otherwise get wrong when interpreting empty results.

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?

One dense paragraph, front-loaded with the operation breakdown and closing with the limit-semantics caveat. Every clause carries information, though the long compound sentences make it harder to scan than a short bulleted breakdown would.

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 and annotations present, return values and safety need not be restated, and the description covers operations and limit semantics. However, for an 11-parameter nested schema at 0% coverage, several structural parameters remain undocumented anywhere, leaving the definition incomplete 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 0% across 11 parameters, so the description must carry the load. It clarifies the operation modes, the select targets (question, rule, position, node), the two-document nature of diff, StableId lookup for locate, and the evaluation/answerResource source — but leaves page, budgetBytes, index, bundle, context, sources and snapshot entirely 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 names a specific read-only inspection tool over a recorded evaluation document and then defines each of the four operation modes (summary, slice, diff, locate) with the resource each one acts on. It even signals provenance (law_ask(proof=true) or answerResource), which helps separate it from sibling tools like law_explain or law_query.

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 text states the accepted input source and that nothing is recomputed, which implies when the tool applies, but it never explicitly contrasts usage against siblings such as law_explain, law_query or law_rules, nor states when not to use it. Usage is inferable rather than prescribed.

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 safety hints (readOnly/openWorld/destructive), so the description carries the real behavioral load: it discloses the three modes, pageUnit semantics, per-mode defaults (20/20/20/300), the `showing a–b of N; k more` text and structuredContent fields (total, truncated, next with a ready continuation call). This is rich context well beyond the annotations, and it is internally consistent with readOnlyHint.

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?

It is long and dense, but for a six-parameter, multi-mode catalog almost every clause carries operational facts (modes, pagination, catalog types, guide handling). Purpose is front-loaded in the first sentence; structure would benefit from lists, but there is little pure 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 tool with no output schema and six optional parameters, the description is complete enough to call correctly: it covers all modes, pagination units and defaults, the structuredContent continuation fields, the catalog list types, and the relationship to MCP Prompts for task-guides.

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 3 is the baseline; the description exceeds it by giving per-mode defaults and caps for limit, explaining that offset's unit is the response's pageUnit, and clarifying what package vs. query vs. catalog select. It adds operational meaning (defaults, caps, mode interactions) that the schema alone does not convey.

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

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

States a specific resource and scope ("Le catalogue du droit formalisé : actes, prédicats avec signatures, frontières de couverture") and explicitly distinguishes itself from the sibling law_search, explaining that predicate NAMES come from here and must never be invented. An agent can tell this apart from law_search/law_query without opening a schema.

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

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

Gives explicit when-not guidance ("ne commencez PAS par le catalogue... Une question dans vos propres mots va d'abord à law_search") and the precise condition for using it ("le catalogue sert à la signature exacte de ce que vous avez trouvé"). It even gives the selectable modes by argument. Nothing is left to inference.

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

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

The readOnlyHint/destructiveHint/openWorldHint annotations already cover the safety profile, and the description usefully adds that records are paginated by JSON Pointer with a 'next' cursor and that reports retain failures. It does not disclose permission requirements, response size limits, or cost. Adds value beyond annotations but not rich 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?

Three short sentences that are front-loaded with the resource definition, then pagination behavior. Little waste, though the metaphor 'passeport' and the section enumeration add some density without precise operational meaning.

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 6-parameter tool with 0% schema coverage and no output schema, the description should explain the required identity parameters (name, version, contentHash) and the sections selector, but it does not. Pagination and the reports retention note are helpful but far from complete.

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% across 6 parameters, so the description carries the full burden and only partially compensates: it hints at the pagination parameters (limit/offset via 'enregistrements sont paginés' and 'next') and at the 'sections' parameter via the mention of 'reports'. It says nothing about the required name/version/contentHash triple or the sha256 pattern constraint.

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

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

The description names a specific resource ('passeport d'une publication exacte') and enumerates the content it returns (objet, interface, frontières, contrôles, performance), so an agent knows what data it yields. However, it never names a verb explicitly and gives no differentiation from the many sibling tools (law_inspect, law_search, law_query, 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?

There is no statement of when to use this tool versus alternatives; the closest is a note that 'reports' retains measurement history, which is about content, not usage context. The agent is left to infer that this is the go-to retrieval for a specific immutable publication.

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?

Goes well beyond the annotations by disclosing the core mechanism: the client never supplies the answer, the server re-executes, and any discrepancy in input/law/resource/server code/engine library/result rejects the entire document. The 24-hour non-public frozen-document lifetime is also new information. This is genuinely useful behavioral context for a readOnlyHint=false tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences, front-loaded with the triggering action and with the rejection rule last. Every sentence carries substantive meaning for a tool with this much machinery, though the prose is heavy and could be split for scanability.

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

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

An output schema exists, so return-value detail is not required, and the description covers the replay/compare/freeze workflow well. Still incomplete on parameter usage (documentVersion choice, calculations vs producerRuns) which matters for correct invocation of this nested, oneOf-constrained 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?

Schema description coverage is only 33% across 6 parameters, so the description must compensate, yet it only indirectly maps to the schema ('1 à 12 appels' matches the maxItems=12 arrays and it names replayControl). It does not explain question, language, assistant, documentVersion, or the oneOf exclusivity between calculations and producerRuns.

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 compound action: replay 1–12 prior law_ask/law_process_run calls, strictly compare their replayControl, and produce a frozen non-public document for 24h. The verb+resource+scope are identifiable and it names the input source tools, though the density and French phrasing make it somewhat harder to parse than a crisp one-liner.

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 one gating condition ('à la demande explicite de l'utilisateur') which is useful context, and references law_ask/law_process_run as the runs to replay. However it never contrasts itself with siblings like law_publish_answer, law_capture_answer or law_ask, so an agent must infer when this is the right tool over those.

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=false, destructiveHint=false, openWorldHint=true and idempotentHint=true. The description adds meaning beyond them by specifying what idempotency actually yields: the same URL and the same distinct revocation secret on repeated calls with an identical preparationId. It still does not disclose permission requirements or what the returned revocation secret is for.

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 short sentences with the core action front-loaded and the idempotency caveat immediately after. No filler, and the reader gets the essential contract in the first clause.

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

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

An output schema exists, so return values need not be enumerated, and annotations cover the safety profile. The description supplements this with the idempotent-return guarantee. The remaining gap is the absence of workflow linkage to the prepare and revoke siblings, which matters given the large sibling set.

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 carry the burden for the single preparationId. It does add real semantics — that the same value produces the same idempotent result — but never states where preparationId comes from or that it identifies the artifact produced by the preparation step.

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

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

States a specific verb and resource ('Publier un document préparé'), which is clear and action-oriented. It does not, however, distinguish itself from siblings such as law_prepare_answer or law_revoke_answer, so an agent must infer the prepare→publish→revoke pipeline rather than being routed explicitly.

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

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

Usage is only implied: the phrase 'document préparé' and the required preparationId suggest this must be called after a preparation step. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g., revoke_answer for the inverse operation), leaving the agent to infer the workflow position.

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 cover the safety profile (readOnly, non-destructive), and the description adds substantial behavior beyond them: queryPage pagination with resultHash/snapshot/rowCount/rowLimit/rowOffset, per-row CLIR provenance, the empty-response explain funnel, and explicit error codes (CORPUS_EMPTY, QUERY_TOO_BROAD, SNAPSHOT_CHANGED, LDC-Qxxxx). This is exactly the extra context an agent needs.

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 definition is front-loaded with the core purpose, and most sentences carry real information, but it is an extremely dense single block that mixes query syntax, relations/functions, scope, examples, pagination and error codes, making it hard to scan. Structure suffers even though little is truly redundant.

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

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

For an 11-parameter, nested, no-output-schema tool, the description covers the return structure (queryPage fields), continuation protocol, scope resolution, and error taxonomy well enough to call correctly. Only minor details such as the full catalog of named questions remain to be discovered via the referenced CLI.

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%, establishing a baseline of 3. The description goes further by clarifying scope semantics (package.name or glob, whole profile slice when absent), URN typing for predicate/node/type, and continuation semantics that tie snapshot across calls, adding meaning beyond the field-level text.

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+resource ("Une requête LawQL déterministe sur le CLIR d'une formalisation") and immediately scopes it as "une question sur le modèle de l'acte lui-même, pas sur une affaire", distinguishing it from case-oriented siblings. An agent can identify the operation and its domain without opening the schema.

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

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

The exclusion "pas sur une affaire" implicitly routes case questions elsewhere, and named-question alternatives (anchors-of, producers, readers, type-step) are listed. However, no sibling tool is named explicitly as the alternative, so the when/when-not guidance is clear but not fully mapped to 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 destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description still adds concrete value by specifying exactly what the destructive action shuts down (the HTML page, the API, and the download), which the annotations do not 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?

Two tight sentences with no filler; the purpose is front-loaded and the credential requirement and effect follow in order of importance.

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 mutation with an output schema present, the description covers purpose, the mandatory credential, and the blast radius of the action. Remaining gaps (reversibility, failure modes) are minor given the idempotent and destructive hints.

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 carry the load. It does clarify the roles: publicId is an identifier that confers no control on its own, and revokeSecret is the distinct credential that authorizes revocation. It does not give format, length, or error behavior for either parameter, so it only partially compensates.

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 (révoquer) and resource (un document publié), plus the scope of the effect. It is clear what the tool does, but it never names the counterpart sibling law_publish_answer, so the differentiation from siblings is left implicit.

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

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

Usage is implied rather than stated: the description makes clear the operation applies to an already-published document and that a distinct revoke secret is mandatory ('L'identifiant public à lui seul ne donne aucun contrôle'). There is no explicit when-to-use/when-not or named 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?

Annotations already declare read-only, non-destructive, closed-world behavior, and the description adds real context on top: large acts return a table of contents rather than full text, package listings are paginated, and truncation is surfaced in both text ('showing a–b of N; k more') and structuredContent with a ready-made continuation call. It does not explain the idempotentHint=false or any auth constraints, so it stops short of a 5.

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?

Front-loads the core purpose and the law_ask ordering before pagination mechanics, and every sentence carries information. The pagination/truncation behavior is stated twice (narrative and structuredContent), which is slightly redundant but defensible.

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 lookup tool with an output schema and full schema coverage, the description covers the main retrieval paths, ordering guidance, and truncation recovery. The lang, contract, inputLimit, and inputOffset modes exist only in the schema, so the description is not exhaustive for all 8 parameters.

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

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

Schema description coverage is 100%, so baseline is 3; the description goes further by explaining what package (table of contents for large acts) and predicate (full text) actually return, and by restating the working pagination defaults (20, 500 max) that govern limit/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?

States a specific verb+resource: it returns inference rules showing how exactly a predicate is derived (premises, source articles). It also distinguishes its scope from the sibling law_ask by framing itself as the rule source that precedes fact supply.

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

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

Gives explicit sequencing guidance ('Appelez ceci AVANT de fournir des faits à law_ask') along with the reason (rules say which facts are needed instead of leaving them to invention). It also routes between the two main modes: package= for a table of contents of large acts, predicate= for full text.

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 annotations (readOnlyHint, openWorldHint=false, idempotentHint=false), the description discloses that sourceSchemaContentHash is compared loudly against the pin, that the confidence number is consumed by the package's EvidencePolicy rather than this tool or the engine, and that downstream rows are fully computed with a proof graph on the same snapshot. That is meaningful behavioral context not derivable from annotations. No auth/rate-limit detail, so not a 5.

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 scope and exclusions are front-loaded and each sentence carries boundary or behavioral information rather than filler. Density of jargon (arbre typé, manifeste des extensions jusqu'à TRUE) makes it heavier than needed, but nothing is redundant.

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

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

An output schema exists, so return values need not be spelled out, yet the description still frames the output shape (typed tree + manifest). Given 5 parameters, 4 required, and nested objects, the description covers the workflow and responsibility boundaries adequately. Minor gaps around lifecycle/idempotency expectations (idempotentHint=false) remain.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds role context for two parameters (binding as a pinnable object, sourceSchemaContentHash as the real schema fingerprint compared with the pin) but says nothing about goal, package, or legalTime beyond the schema. The marginal gain is real but limited, so it stays at the baseline.

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

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

Front-loads a specific verb and resource: build a necessary condition (superset) for pre-selecting rows from an external source, and clarifies the output is a typed tree plus manifest, not a legal answer and not SQL. This cleanly separates it from answer-producing siblings like law_ask and law_answer_capabilities. It does not fully distinguish it from data-oriented siblings such as law_query or law_search, keeping it short of a 5.

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?

Explicit exclusions are stated: it is NOT a legal answer and NOT SQL, and business facts with provenance (origin, document, citation, extractor) are directed to law_ask rather than here. This gives real routing context. It lacks an explicit positive 'use this when...' statement contrasting with law_query/law_search, so it falls just under 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 already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=false, but the description adds meaningful context beyond them: ranking uses a deterministic lexical embedder, text similarity is not norm applicability, and results are non-authoritative (establish neither fact nor norm). It does not cover return format or pagination, but the output schema carries that.

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 front-loaded: purpose first, then the discovery-vs-answer framing, then the routing caveat. Every sentence contributes (the empty-result warning and embedder note are non-trivial), though the phrasing is somewhat verbose.

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 search tool with a full output schema, the description need not explain return values, and it covers purpose, routing, and behavioral caveats thoroughly. Nothing essential for correct invocation or interpretation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including enums for kinds and the limit hint. The description adds no syntax or format details for query, kinds, limit, or package beyond what the schema provides, so the baseline 3 is appropriate.

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

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

States a specific verb and resource (semantic search over formalized law) and precisely defines the scope: returns candidate predicates, rules, and article fragments rather than answers. It explicitly distinguishes itself from siblings by naming law_ask, law_rules, and law_sources, so an agent can route correctly without opening schemas.

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?

Explicit when-to-use (discovery layer for exploring a notion in your own words) and when-not (if you know the exact name, go directly to law_packages/law_ask). It also names the follow-up alternatives (law_ask by signature, law_rules, law_sources) and warns that an empty result does not imply the norm is absent.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds genuinely non-structured behavioral detail: the default view yields short extracts, continuations require contentHash, textOffset/textLimit are only valid with fragment, and the fingerprint covers the ENTIRE source rather than the extract. The only unmentioned trait is whether content can shift between pages (relevant given idempotentHint=false).

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?

Defaults are front-loaded, followed by the full-view mechanics, then constraints, then pagination — a logical order with almost no filler. The single dense paragraph is slightly run-on, which is the only cost.

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 10-parameter read tool with no output schema, the description supplies what an agent needs: default behavior, page sizing, the fragments[].full and fragments[].next continuation fields, hash scope, pagination, and the oneOf-style requirement that the schema (0 required params) cannot convey. Nothing material 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 already 80%, yet the description adds cross-parameter constraints the schema cannot express: one of package or fragment is required, textOffset/textLimit require fragment, and a continuation requires contentHash. It also clarifies limit semantics per view (5 for summary, 1 for full) and notes the budget may lower it.

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

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

The description names the resource (official source texts) and specifies its scope precisely: default short extracts via view=summary, 5 texts per page, full text address at fragments[].full, and view=full returning exact text parts. The retrieving verb is only implied ('Sources : par défaut...'), but the behavior is unambiguous and clearly distinguished from the ID-producing siblings law_search/law_rules.

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 states a prerequisite ('package ou fragment est requis') and points to law_search/law_rules as where the StableId comes from, which is useful routing. However, it never says when to choose this tool over law_packages, law_inspect, or law_query, so usage is only implied rather than delimited.

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