BGB (Germany)

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 clear. The description adds useful semantic context by explaining that 'declared_only means a schema with no executable witness,' which helps an agent interpret the returned matrix without contradicting the annotations.

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

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

The description is two sentences and contains no obvious filler, with the main purpose stated first and the term 'declared_only' defined second. It is dense with domain terminology but appropriately sized for the amount of information it conveys.

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

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

There is no output schema and no parameters, so the description carries the burden of explaining what the tool returns. It lists the matrix contents and defines one key term, though it does not specify the exact output format or structure of the matrix.

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 there are no parameter semantics for the description to clarify. Per the rubric, a zero-parameter tool receives a baseline of 4.

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 resource: a machine-readable matrix of installed Lens producers, checks, profiles, limits, and contract tests. It clearly describes what the tool returns, though it does not explicitly differentiate it from sibling tools such as law_packages or 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?

The description gives no explicit when-to-use guidance, no conditions for choosing this tool over alternatives, and no exclusions. It only describes the content of the matrix, leaving usage context to be inferred from the tool name.

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

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

The annotations already establish that this is read-only, non-destructive, and closed-world. The description adds substantial behavioral context: the four robustness classes, construction of all arguments including non-fired chains, attacks and defeats, and a possible cap refusal with remediation.

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 and the four result classes are compactly described. The paragraph is dense and jargon-heavy, but most sentences add distinct information about output classes or operational limits.

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?

This is a complex tool with nested parameters and no output schema, so the description must explain returns and behavior. It does so by defining the four result classes and cap behavior, while annotations and the rich schema cover safety and parameter details.

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 still adds meaning by stating that predicate names come from law_packages and by explaining the limits.maxArguments cap and how to respond to a refusal.

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

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

The description clearly states that the tool measures how robust a conclusion is under an argumentation profile and enumerates four result classes. It distinguishes the operation from ordinary querying by focusing on argumentation, but it does not explicitly name or contrast sibling 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?

Usage is implied by 'How robust a conclusion is', and the description gives operational guidance about predicate names and cap handling. However, it does not explicitly say when to use this tool instead of siblings such as law_ask, law_query, or law_explain.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description is free to add the behaviour that matters: "not established" answers carry a whyNot report with candidate rules and conjunct states, answers carry rules, warnings and provenance hashes, version pinning causes refusal rather than silent substitution, and the server never assumes a missing norm or deadline policy. These are non-obvious traits an agent cannot get from 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?

Front-loaded with the core purpose, then prerequisites, then kind semantics, then return shape — a sensible order. It is long and somewhat repetitive (the "not established is the answer" point is made twice, once in capitals), but nearly every sentence carries operational content.

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

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

For a 22-parameter, nested-schema tool with no output schema, the description still covers the prerequisites, the meaning of the answer modes, the content of the returned answer (rules, warnings, provenance hashes, signature block) and the failure semantics. Only the calc path is left entirely to the schema, which is a small residual gap.

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 95%, so the baseline is 3, but the description adds genuine meaning by explaining the semantics of the kind values (truth vs collect vs deadline vs positions vs why_not) and the role of law_search/law_packages in filling predicate and args. It omits kind='calc' from that enumeration even though a dedicated calc parameter exists, leaving the most structurally complex branch unglossed.

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 ("Put a question to formalised law") and enumerates the question kinds, so an agent knows this is the main evaluation entry point. It does not, however, contrast itself with close siblings such as law_case_ask, law_query or law_argue, so the agent must infer the boundary.

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 prerequisite (obtain predicate names via law_search or law_packages before the first call, because an invented name is rejected), what to do with errors and "not established" results (pass to the user, do not substitute general legal knowledge), and the trap that an empty catalogue search is not a negative answer. That is a when/when-not/alternative map rather than a hint.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, and idempotentHint=false. The description adds the registry constraint but conspicuously leaves the tension between 'Run a producer' and readOnlyHint unexplained, and says nothing about why idempotentHint is false or what a failed run looks like. It adds only marginal context over 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?

Two short sentences with no filler and the key constraint placed last. It is not bloated, but the density of undefined jargon means the brevity comes at the cost of comprehension rather than from 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?

For a tool with a nested request object, no output schema, and 0% parameter documentation, the description is far too thin. It never defines 'producer', 'producerControl/0.2', or 'Lens', nor does it explain what the request must contain or what the caller receives, leaving an agent unable 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 description coverage is 0% with two required parameters, one of which ('request') is a nested object that is entirely undocumented. The description adds a little meaning to 'producer' (must come from the shipped registry) but gives no insight into the structure or contents of 'request', so it fails to compensate for the coverage gap.

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

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

The description names an action ('Run a registered producer') and an output ('producerControl/0.2'), but both are opaque domain jargon that a fresh agent cannot decode. It never states in plain terms what the tool actually does, and it does not differentiate itself from siblings like law_prepare_answer, law_publish_answer, or law_answer_capabilities beyond implying a 'later verifiable preparation' step.

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

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

The only guidance is a constraint ('The producer is chosen only from the shipped registry'), which says what inputs are legal, not when to pick this tool over the many siblings. No when-to-use, no when-not-to-use, and no named alternatives are offered.

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/no-destructive/closed-world, and the description adds genuinely new behavior: the default response is a projection without proof graph, responseMode full or proof:true yields the canonical document with proof and manifest, and a failed preparation returns an error with an LDC-* code rather than an empty answer. That error-contract sentence is exactly the kind of context annotations cannot carry.

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 but well-ordered block: purpose first, then output shape, then accepted input forms, then failure semantics. No filler sentences, though the German sentences are long and jargon-loaded, and the language mismatch with the English tool/parameter names adds friction.

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 9 parameters, nested objects, and no output schema, the description carries the return-value burden and does so by distinguishing the compact projection (results, positions, conflicts, manifest, hashes, proofGraph collapsed) from the full canonical document. Missing only a plain-language statement of what the answer content represents for a first-time caller.

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

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

Schema coverage is 100%, so the baseline is 3. The description does add the mutually-exclusive invocation combinations (query alone, evaluate+queryId, stored queryId alone, card+args), which the per-parameter schema does not state, but its responseMode and proof explanations largely duplicate the schema 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?

The description states a verb ('ausführen') and resource ('eine registrierte Sache eines Fallpakets'), but 'Sache' and 'verankerte Abhängigkeiten' are internal jargon that does not tell an outside agent plainly that this answers a question against a case package. It never contrasts itself with the very similar sibling law_ask (which it only mentions in a parameter description), so discrimination relies on the agent reading 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?

No statement of when to choose this tool over law_ask, law_query, or law_argue, and no exclusions or prerequisites. The input-form list (query / evaluate+queryId / stored queryId / card+args) hints at usage shapes but is parameter guidance, not tool-selection 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?

The annotations already declare read-only, non-destructive, non-open-world behavior, so the description's main addition is the NOT_DATED caveat and the mention of output categories like edition state and semantic diff. It still does not explain output structure, limitations, or why idempotentHint is false, leaving meaningful behavioral context undisclosed.

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 short and front-loads the main purpose in the first sentence. Some internal shorthand ('O-2', 'D1 projections') is less useful than plain language, but the text is not bloated.

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

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

There is no output schema, so the description must carry more weight in explaining return values. It names the output categories and one important verdict caveat, but leaves undefined terms and the full shape of results or error cases unexplained.

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

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

Schema description coverage is 100%, and the description only conceptually frames the parameters as an instrument and two law dates. It adds no format or constraint details beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the core operation: showing what changed in an instrument between two law dates, including edition state, norm dating, and semantic diff. This distinguishes it from law_ask for point-in-time questions, though jargon such as 'axis of editions (O-2)' and 'D1 projections' is opaque without context.

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 an explicit routing rule for a key alternative: a particular question on a date should use law_ask with legalTime. However, it does not compare against other possibly relevant siblings such as law_inspect, law_query, or law_packages.

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?

Adds real behavior beyond the annotations: the server repeats the computation and explicitly refuses on hash mismatch, nodeId output is capped at 24 KB with an explicit refusal beyond that, answerResource mode avoids recomputation and client page loading, and the default is proofRef-chain only. The annotations only cover read-only/destructive/idempotent/openWorld, so this failure-mode and limit disclosure is genuinely additive.

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?

Information-dense and front-loaded with the purpose, but written as telegraphic fragments ('The compact input: question..., resultHash and codeHash from the provenance of the answer.') that blend parameter semantics with behavioral constraints in run-on sentences. Size is reasonable for a 6-parameter multi-mode tool, but scanability suffers.

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 described, and the description covers mode selection, verification semantics, size limits, and node-scoped selection. Given the nested-object oneOf schema, this is close to complete; the only loose end is the unexplained proofHash/scope references that do not map to schema properties.

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 still accounts for all six parameters: question (original law_ask arguments), resultHash and codeHash (from the answer's provenance), evaluation (from law_ask proof=true), answerResource (fullAnswer.uri of a stored proof=true answer), and nodeId (selects one node plus its premises). It also conveys the mutual exclusivity of the oneOf modes, though it mentions proofHash and scope, which do not appear in the schema properties, adding slight ambiguity.

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 (unfold/explain) and resource (the proof of a law_ask answer) and even names the output shape, the 'rule ← premises → conclusion' chain. It anchors itself to the law_ask sibling as the producer of its inputs, so an agent can place it in the workflow, though it never contrasts itself against an alternative tool.

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

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

Gives clear conditional context for the three input modes: pass question/resultHash/codeHash to have the server recompute and verify, pass the evaluation from law_ask(proof=true), or use answerResource to explain a stored snapshot without recomputing. There are no explicit exclusions or sibling alternatives, but the mode-selection guidance is concrete.

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, closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: it operates purely over a saved document with no evaluation or recomputation, and it defines the semantics of absent data as a limit state rather than a negation. It does not cover pagination or rate/latency 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 resource and read-only framing are front-loaded, and little is pure filler, but the operation breakdown is delivered as one dense, dash-separated run-on that is hard to parse. Structure suffers even though information density is high.

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 format need not be explained. But for a complex 11-parameter tool with nested objects and a oneOf constraint at 0% schema coverage, the description omits pagination, indexing, bundling and source-selection semantics, which an agent would need to invoke it correctly in non-trivial cases.

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 carries real weight: it maps each operation to its inputs (slice selectors for query/rule/position/node, diff via against, locate by StableId). However, several top-level parameters — page/cursor/budgetBytes, index, bundle, sources, context, snapshot — are never mentioned, leaving meaningful gaps.

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

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

The description names a specific verb (inspect, read-only) and resource (a SAVED evaluation document) and enumerates the four operations — summary, slice, diff, locate — each with its own scope. It does not directly contrast with siblings like law_ask or law_explain, but it does name law_ask(proof=true) as the upstream source, which implicitly differentiates inspection from evaluation.

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

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

It gives a clear when-to-use condition: the source must be an evaluation from law_ask(proof=true) or an answerResource, and it emphasizes that nothing is evaluated or recomputed here. It also supplies interpretation guidance ('missing data is a limit state, never a negation'), though it states no explicit when-not or named 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, openWorldHint=false and destructiveHint=false, so safety is covered; the description goes further by disclosing pagination behaviour (limit/offset, 'showing a–b of N; k more') and the structuredContent fields it returns (total, truncated, next as a ready-made continuation call), plus default and maximum page sizes. It does not explain why idempotentHint is false, but that is a minor omission against an otherwise rich behavioural account.

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 and most sentences carry real information, but the prose is sprawling, dense with em-dashes and parentheticals, and restates some defaults already carried by the schema (20/300 limits). The mode enumeration is hard to skim, which costs it against a genuinely concise definition.

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

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

There is no output schema, yet the description compensates by describing the return shape (one line per instrument with key, title, legal order and counters; page metadata in structuredContent). For a six-parameter, multi-mode, read-only catalogue tool the description covers modes, defaults, caps and continuation calls adequately; only the precise field list of the structuredContent payload is left implicit.

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 100% schema description coverage the baseline is 3, but the description adds genuine cross-parameter semantics the schema cannot: how package, catalog, query and the paging pair combine ('package=… together with catalog=… pages a separate list'), which argument switches the page unit from instruments to signatures, and the fact that catalog='task-guides' is legal without package. That interaction logic is the value-add beyond the per-parameter 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?

The description names the resource precisely (the catalogue of formalised law: instruments, predicate signatures, coverage boundaries) and explicitly distinguishes itself from the sibling law_search, which it tells the agent to use for keyword questions. It is a catalogue/browse resource rather than a clean verb+resource pair, and only one of fifteen siblings is differentiated, so it stops 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?

It gives an explicit when-NOT: 'do NOT start from the catalogue when looking for the right instrument', justified by the size of the overview and title/query word mismatch, and routes the agent to law_search first, with the catalogue reserved for resolving the exact signature of something already found. It also states which mode to use under which argument combination.

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

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

Annotations already establish that this is a read-only, non-destructive, closed-world operation, so the description does not need to restate safety. It adds useful behavior beyond annotations: the reports section includes failed measurements, entries are paged by JSON Pointer, and a next value continues the answer. It still leaves the exact pagination contract and response shape somewhat cryptic, but it provides meaningful operational 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 short and front-loads the passport contents before adding the reports and pagination notes. Every sentence is relevant, though terms like 'JSON Pointer' and 'next continues the answer' are compressed enough to be ambiguous.

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 seven parameters, low schema description coverage, and no output schema, the description should do more to explain required release identity, section selection, index behavior, and return structure. It mentions paging and some sections but leaves the agent without enough detail to confidently construct calls or interpret results.

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 14%, so the description must compensate for undocumented parameters. It does not explain name, version, contentHash, limit, offset, or the full sections enum; it only alludes generally to an exact release, a reports section, and JSON Pointer paging. That is insufficient for a seven-parameter tool with low schema coverage.

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

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

The description identifies a specific resource: the passport for an exact release, with sections for purpose, interface, boundaries, checks, performance, and reports. It is clear what kind of artifact is being fetched, but it never states an explicit verb such as retrieve or return and does not distinguish this tool from siblings like law_inspect or law_report.

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 no guidance about when to use law_passport versus alternatives such as law_inspect, law_sources, law_report, or law_query. It implies that the tool is used to inspect an exact release passport, but does not state prerequisites, exclusions, or routing conditions.

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 does add real behavior beyond annotations: a 24-hour non-public freeze, server-side re-execution ('The client never supplies the machine answer'), and all-or-nothing rejection on any divergence in input/law/resource/server code/engine library/result. However, this directly conflicts with the annotation title 'Prepare a public write-up', which claims public output where the description says non-public. That inconsistency undermines trust in the stated 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?

Three sentences with no filler and the user-request trigger front-loaded, so nothing is wasted. But the sentences are dense and grammatically awkward ('compare their replayControl strictly'), forcing re-reading of the central mechanism.

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 described, and the description covers the verification/rejection model and the 24-hour non-public lifetime. Still missing for a nested, oneOf-constrained tool: what the produced document actually is, what documentVersion 0.1 vs 0.2 means, and the role of the assistant payload.

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%, so the description must compensate. It does explain the key semantic that replayControl is strictly compared and that client-supplied answers are never trusted, and it matches the schema's 1–12 item bound. It says nothing about question, language, assistant or documentVersion, leaving a large share of the six parameters undocumented.

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 concrete verb+resource: 'prepare a non-public frozen document for 24 hours' from 1–12 earlier law_ask or law_process_run calls. It implicitly separates itself from law_publish_answer (non-public, frozen, 24h) but never names that sibling, and the jargon 'replayControl' and the reference to law_process_run (not in the sibling list) cloud the picture.

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 one trigger condition clearly: 'At the explicit request of the user'. It does not say when NOT to use it, nor route the agent to alternatives such as law_publish_answer, law_capture_answer or law_ask for the non-verification path. Usage is implied rather than fully specified.

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 annotations, the description explains that results are reconstructed from a formalization and that checks include unreachable stages, dead transitions, and transitions entering no stage. It also usefully states that a stage with no exit is reported but not counted as a defect, which is important 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 reasonably sized and front-loads the core purpose, but the first sentence is grammatically awkward and the repeated reference to formalisation makes it slightly harder to parse 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?

Given one optional parameter and no output schema, the description provides a solid account of what is returned: stages, transitions, transition conditions, and specific graph defects. It could be more explicit about result formatting, but the essential call behavior is covered.

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 package parameter already has 100% schema description coverage, and the description adds only the same behavior: omitting package lists instruments whose procedure is formalized. It does not significantly extend the schema's 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 that the tool reports the stages of a procedure and checks for structural defects in the procedure graph. It is specific about the resource and analysis performed, though it does not explicitly distinguish itself from the sibling tool law_process_run.

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: pass a package to analyze that instrument's procedure, or omit it to list instruments with formalized procedures. However, it gives no explicit guidance on when to use this tool instead of related siblings such as law_process_run or law_inspect.

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 read-only safety, so the description appropriately adds substantive behavioral context: what the answer reports, how stages-entered differs from current state, and that without probeTime the tool does not compute available next steps. It also discloses a significant limitation—that this does not compute points of the current state. It does not explain error behavior, but the additional disclosure is strong.

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

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

The description is front-loaded with its purpose and avoids obvious filler, but it is a dense, run-on paragraph with nested parentheticals and jargon that makes it harder to parse than necessary. Several clauses are useful, but the structure could be clearer and more 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?

Given six parameters, 100% schema coverage, no output schema, and a complex domain, the description does a substantial job explaining the returned information, the temporal rules, and the tool's limits. It lacks explicit guidance on error cases or when to prefer it over siblings, but it is close to complete for the core behavior.

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

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

Schema coverage is 100%, so the schema already documents the parameters, including the complex steps structure and the probeTime semantics. The description adds little parameter detail beyond what is in the schema and instead focuses on output and conceptual behavior. This fits the baseline of 3 when the schema does the heavy lifting.

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 states a specific function—executing a dated log of case events frame by frame to determine procedural effects—which is more than a restatement of the name. It also distinguishes itself from law_process by noting that transition names come from that tool. However, the purpose is expressed in dense domain jargon ('frame', 'core 0.1') that weakens immediate clarity.

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 that this tool is used when you have a case log to evaluate, but it gives no explicit when-to-use guidance, no when-not conditions, and no comparison against alternatives beyond noting that transition names come from law_process. An agent must infer the selection criteria.

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 flag idempotentHint=true and readOnlyHint=false, but the description adds concrete behavioral detail beyond that: the repeat call returns the *same URL* and the *same separate revocation secret*, which is exactly what an agent needs to know to safely retry. It is slightly redundant with idempotentHint but the payload specifics are new information.

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 no filler, and the core action is front-loaded before the idempotency note. Wording is slightly clunky ("with the same preparationId idempotently returns") but nothing is wasted.

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 explained further, and annotations carry the safety profile. The remaining gap is the missing pointer to law_prepare_answer as the source of preparationId and to law_revoke_answer as the consumer of the revocation secret.

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 single preparationId parameter has no schema description. The description names preparationId and implies it is a handle produced by a prior preparation step, but does not say where to obtain it or what its format is, so it only partially compensates for the coverage gap.

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 ("Publish a prepared document") that an agent can distinguish from law_prepare_answer (which prepares) and law_revoke_answer (which revokes). It does not name those siblings explicitly, but the preparation/publish/revoke triad is inferable from the verb choice.

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 the precondition that a document must already be prepared and identified by preparationId, which implies law_prepare_answer runs first. However, it never states when to use this versus alternatives, nor what happens if the preparationId is unknown or expired.

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 annotations, the description discloses pagination behavior (rowLimit default 20, max 5000, next/snapshot), full-result mode, provenance per row, empty-result explain funnels with emptyAt, error codes, and pre-execution rejection of overly broad queries (QUERY_TOO_BROAD) or stale continuations (SNAPSHOT_CHANGED). It also sets the scope boundary that an out-of-profile corpus yields CORPUS_EMPTY.

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 content is highly relevant for an 11-parameter query language, but it is presented as a dense, semicolon-heavy block rather than a structured reference. The purpose is front-loaded and most clauses earn their place, yet readability and scanability suffer.

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

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

There is no output schema, and the description compensates by explaining the queryPage shape, row provenance, empty-result diagnostics, error codes, and snapshot-based continuation. Combined with the schema's full parameter descriptions and the listed relations/functions, an agent has enough information to form and continue queries correctly.

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

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

Schema description coverage is 100%, so the baseline is 3; the description still adds useful semantics: corpus is a package.name or glob rather than a filename, without corpus means the whole profile slice, full only works for a single package, and limit caps materialisations rather than rows. It also clarifies that predicate/node/type are URNs and that snapshot continues a previous page.

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: a deterministic LawQL query over CLIR, explicitly framed as a question to the act's model rather than to a case. It lists the queryable relations and functions and gives concrete examples, so the agent can distinguish this structured-query tool from case-oriented or natural-language 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?

It explains how the tool is used (inline LawQL, catalog question names, arguments, corpus scope, continuations) and clarifies that this is orchestration over CLIR and the core rather than new legal semantics. It does not explicitly say when to choose this over siblings such as law_ask or law_search, so it lacks full when-not/alternatives guidance.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false, idempotentHint=false), and the description adds real context by explaining the effect: it does not mutate the law, does not feed other tools' answers, and lands in the server log. However, 'the entry goes into the server log' sits in mild tension with readOnlyHint=true and the description never reconciles that the call does create a persisted record — an agent could read this as a purely side-effect-free operation. Useful added context, but the write-to-log vs. readOnly framing is left slightly ambiguous.

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-loaded with the core definition, then constraints, then the operational requirement (address + callId) and the log destination. It is dense but almost every clause carries information; the only soft spots are the somewhat rhetorical framing ('a report is a hypothesis for triage by a formaliser') and run-on enumeration.

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

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

With no output schema, the description must say what comes back, and it doesn't — the agent learns only that an entry goes into the server log, not whether it receives a report id, echo, or rejection on a bad address. It does cover the required address, the categories, and the dispute workflow, so for a 7-parameter diagnostic tool the coverage is adequate but leaves the response contract and error behaviour unexplained.

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

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

Schema coverage is 100%, so the schema baseline is already met, and the description adds meaning on top: package/fragment/predicate form an address checked against the catalogue, fragment is a StableId drawn from law_sources, and callId is the X-Law-Call-Id of the disputed answer. That cross-references sibling tools and supplies validation semantics absent from the schema. It does not explain how category affects triage or whether expected/observed need article citation, so not a 5.

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: 'A REPORT of a divergence between the formalisation and the source', then enumerates the divergence kinds (contradiction, missing norm, label mismatch, broken address). It also clarifies the artifact's standing relative to siblings ('never reaches the answers of the other tools'), so an agent can tell this apart from law_explain/law_argue, though it never routes to a named 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?

Gives clear trigger conditions (you disagree with an answer; you found a norm in the source not expressed as a rule; an address cannot be found) and a strong usage constraint ('it does NOT change the law', 'not derived does not become derived'). It also states the filing prerequisite: an address validated against the catalogue, plus callId from the disputed answer. No explicit 'do not use this for X, use sibling Y instead', so it stops short of a 5.

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

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

Annotations already declare destructive=true, idempotent=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine value beyond them by enumerating the blast radius — 'revocation closes the HTML page, the API and the download' — which tells the agent exactly what stops working.

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, zero filler, and the action-with-required-credential is front-loaded ahead of the consequence. Every clause earns its place.

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

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

An output schema exists, so return values need not be described. The scope of destruction and the credential requirement are covered; only errant cases (invalid/rotated secret, already-revoked state) are unaddressed, a minor gap.

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 explains the security model (the public id grants no control; the separate secret is what authorizes the action), which meaningfully clarifies revokeSecret, but it gives no format, length, or acquisition guidance for either parameter.

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 ('Revoke a published document') with the key mechanism named (separate secret). It is clearly distinguishable in intent, though it never names its natural sibling (law_publish_answer) or any other tool, so the agent must infer routing.

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 implies when it applies (a document was published and you hold the revoke secret) via 'The public id alone grants no control,' but there is no explicit when-to-use, when-not-to-use, or alternative clause. Adequate but inferential.

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, so the safety profile is covered. The description adds genuinely new behavioral context: paging behavior for package listings, the default/max limit and 'the budget may lower it', the human-readable remainder text, and the structuredContent fields (total, truncated, next) that form a ready-made continuation call. It does not address the non-idempotent hint, but otherwise this is rich disclosure.

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-loaded with the core purpose and the call-ordering rule before paging details. Dense parenthetical clauses ('20 by default, 500 at most', the 'showing a–b of N' sample) make it slightly heavy, but each sentence carries distinct 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?

For an 8-parameter tool with an output schema and full annotation coverage, the description supplies modes, ordering relative to law_ask, paging, and continuation guidance. Return values need not be re-explained because the output schema exists; the remaining omission is minor (no explicit note on the contract mode's interplay with the other flags).

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

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

Schema coverage is 100%, so the schema documents each parameter description. The description goes beyond it by explaining the mode interaction — package returns a table of contents for large instruments while predicate returns the full text — and by spelling out paging defaults and the continuation payload. This is more than the baseline repetition the schema already provides.

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

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

States a specific verb and resource — it returns 'the rules of formalised law ... exactly how a predicate is derived (premises, source articles)'. It distinguishes its two modes (package= gives a table of contents for large instruments; predicate= gives the full derivation) and separates itself from the sibling law_ask.

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 says 'Call this BEFORE supplying facts to law_ask', with the reason (the rules say which facts are needed rather than guessing). It names the alternative and the ordering condition, leaving nothing to inference.

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

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

Annotations cover the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial context beyond them: the output is a typed tree plus an extensions manifest, screening must be followed by full engine computation with a proof graph on the same snapshot, the binding is a pinnable object, and sourceSchemaContentHash is compared against the pin. These are non-obvious contract details an agent could not derive from 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?

Purpose is front-loaded in the first sentence, followed by scope exclusions and contract details. Every sentence carries information, but the middle is thick with domain jargon and could be split for readability.

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, annotations, and full schema coverage already present, the description still covers the result shape (typed tree + manifest), the two-stage execution contract with snapshot consistency, pin comparison semantics, where provenance facts belong, and what consumes the confidence value. 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 coverage is 100%, so the baseline is 3, and the description adds real semantics on top: the binding is 'passed as a pinnable object' and sourceSchemaContentHash is the actual hash 'compared loudly with the pin.' The legalTime fallback behavior is already in the schema, so it earns only modest additional credit.

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: 'Build a necessary condition — a superset — for the preliminary selection of rows from an external source.' It also fences itself off from siblings by declaring it is 'NOT a legal answer and NOT SQL' and routes provenance facts to law_ask. The jargon ('manifest of the extensions up to TRUE') is dense, so it is clear but not effortless.

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 (not a legal answer, not SQL) and names the alternative for adjacent work ('Case facts that carry provenance ... are supplied to law_ask, not here'). It also states the downstream obligation that passing rows must be recomputed by the engine. It never states the positive trigger condition ('use this when you need to pre-filter candidates'), leaving that to inference.

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

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

Annotations already declare readOnly/non-destructive, but the description goes well beyond them: it discloses the ranking mechanism (deterministic lexical embedder), warns that textual similarity is not normative applicability, clarifies the tool establishes neither fact nor norm, and pre-empts the empty-result false negative. This is exactly the extra behavioral context annotations cannot carry.

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 definition and follows with routing constraints, so almost every sentence earns its place. The ALL-CAPS emphasis, arrows, and em-dash fragments add stylistic noise that slightly obscures an otherwise tight structure.

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 format need not be re-explained, and the description still characterizes results as addressed candidates. Combined with the discovery-layer framing and sibling routing, nothing an agent needs to call this tool 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 100%, so all four parameters (kinds, limit, query, package) are already documented in the schema, establishing a baseline of 3. The description reinforces query semantics ('a question or a notion in your own words') and implies the candidate kinds, but adds no syntax, default, or constraint detail beyond 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?

States a specific verb and resource ('semantic SEARCH over formalised law') and concretely describes the output shape ('candidates with addresses — predicates with signatures, rules, article fragments'). It explicitly differentiates from siblings law_ask, law_rules, and law_sources, so an agent can route without opening another 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-to-use/when-not guidance: 'This is the layer of DISCOVERY, not of the answer', 'If you know the exact name, go straight to law_packages/law_ask', plus the critical caveat that an empty result does not mean the norm is absent. Alternatives are named with the condition that selects them.

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

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

Annotations already establish the safe read profile (readOnlyHint=true, destructiveHint=false), so the bar is lower; the description adds real value on top: pagination via offset/limit, that the answer budget may shrink a page, and the non-obvious rule that the contentHash refers to the WHOLE source rather than the excerpt. That is substantial behavioral context beyond the annotations.

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

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

Four dense sentences, front-loaded with the default behavior and each clause carrying a distinct rule (view modes, required inputs, continuation/hash semantics, paging). Telegraphic style is efficient, though the run-on packing of rules slightly reduces 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?

For a 10-parameter, no-required-param tool with no output schema, the description does the heavy lifting on paging, view modes, continuation, and partial return shape (fragments[].full, fragments[].next). It leaves status/language behavior to the source card and never describes error or empty-result handling, but coverage is otherwise strong.

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 80% schema coverage the baseline is 3, but the description adds cross-parameter semantics the schema cannot express: textOffset/textLimit require fragment, a continuation requires contentHash, and the hash scope warning. It also explains the textRange/fragments[].next continuation model, though it references a textRange that is not present 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 makes clear this retrieves official text sources, defaulting to short excerpts (view=summary) and offering full text (view=full), and it names law_search/law_rules as the origin of the StableId inputs. It does not, however, explicitly distinguish itself from sibling retrieval tools such as law_packages or law_editions, leaving the agent to infer the boundary.

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 specifies a key prerequisite ('Either package or fragment is required') and traces the StableId back to law_search/law_rules, which is genuine usage context. But it never states when to prefer this tool over the many sibling lookup tools, so usage is implied rather than spelled out.

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