FIDE Laws of Chess

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?

Annotations already declare the safety profile (readOnly, non-destructive, non-idempotent, closed-world), and the description adds substantial behavior beyond them: MISSING_POLICY when no deadline policy is set, refusal on version mismatch, the fact that compact mode returns the same full answer with no stored snapshot, and the 'the server does not guess' failure model. It also discloses what the answer carries (rules applied, warnings, provenance hashes, signature block).

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 one dense unbroken block with no structure, and several themes (the server does not guess; errors are the answer) are restated. Most sentences do carry real information and the purpose is front-loaded, but the absence of formatting and the length 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?

With 22 parameters, nested objects, and no output schema, the description covers the essentials an agent needs: prerequisites, question kinds, error and MISSING_POLICY semantics, policy binding, and what the answer contains. A few parameters (evidence, supportEdges, selectedInterpretations) are left to the schema, which is acceptable given its 95% coverage, but the return shape is only sketched.

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 95%, so the baseline is 3, but the description genuinely adds meaning for the enum parameter 'kind' by spelling out what each of the six question kinds computes, including why_not on the same goal. It also explains the operational consequence of responseMode and deadlinePolicy beyond the schema wording, though the bulk of parameter detail still lives 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?

Opens with a specific verb+resource ('Put a question to formalised law') and immediately enumerates the question kinds (truth/collect/deadline/calc/positions/why_not), so an agent knows exactly what class of operation this is. It also names the sibling tools it cooperates with (law_search, law_packages, law_explain, law_prepare_answer), making it separable from the surrounding catalogue.

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 preconditions and routing: predicate names must come from law_search or law_packages before the first call, invented names are rejected, and the negative result 'no suitable instrument' is only valid after law_search has been tried. It also states what to do with an error or 'not established' result (pass it to the user, do not substitute outside knowledge), which is exactly when-to-use/when-not 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 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 declare readOnlyHint=true and destructiveHint=false, and the description correctly aligns with that as a read operation. It adds non-obvious behavior beyond the annotations: the default response is a projection without the proof graph, full mode returns the canonical document, and a refusal is always an error with an LDC-* code rather than an empty answer.

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, which is good, but the remainder is a dense run-on chain of semicolon- and em-dash-separated clauses that mixes return-value semantics, input forms, and error behavior without structure. It is adequately sized but not easy to scan.

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

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

For a nine-parameter tool with nested objects and no output schema, the description does the necessary work of describing the two return shapes (compact projection vs full canonical document, including what the projection preserves and drops) and the failure mode. The pieces an agent needs to call it correctly are largely present, though the query/card/evaluate interaction could be sharper.

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 all nine parameters, establishing a baseline of 3. The description restates the mutually exclusive input combinations (query, evaluate + queryId, saved queryId, card + args) and clarifies proof:true equals responseMode full, but adds little that the schema descriptions do not already carry.

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

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

The first clause states a specific verb and resource: run a registered case of a case package over its pinned dependencies and return the answer. It differentiates itself from the sibling law_ask by scoping to a case package, though the jargon (pinned dependencies, LDC-* codes) assumes a reader already fluent in the domain.

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 through the enumeration of input forms (query JSON, evaluate string, saved queryId, card + args), but there is no explicit statement of when to pick this tool over law_ask, law_prepare_answer, or law_query. The agent must infer routing from the 'case package' scoping rather than being told.

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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered; the description goes beyond them by disclosing the paging contract ('entries are paged by JSON Pointer; next continues the answer') and noting that the reports section includes failures, which tells the agent to expect error data in results. It stops short of describing auth requirements or error 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 short sentences with the resource named first and no filler; the paging note is a single useful clause. Terms like 'boundaries' and 'performance' are loose but do not pad the text.

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 read tool with no output schema and no schema descriptions, the description covers pagination but omits the return structure beyond the paging token and never explains the required contentHash or how sections filtering interacts with paging. It is usable but leaves meaningful gaps.

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

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

Schema description coverage is 0% across 6 parameters, so the description carries the burden; it partially compensates by naming content areas that map to the 'sections' enum (purpose/description, interface, checks, reports) and by implying paging via offset/limit. It says nothing about why contentHash is required alongside name and version, leaving a required parameter 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 identifies the resource (a 'passport' for an exact release) and enumerates its content areas, but uses a noun phrase with no verb and relies on domain jargon ('passport') that an agent cannot resolve from the text alone. It never distinguishes this from siblings such as law_editions, law_report, or law_rules, which plausibly return overlapping release metadata.

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 versus alternatives, no prerequisite for obtaining name/version/contentHash, and no exclusion criteria. The only operational guidance is about paging, not selection.

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

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

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?

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 readOnlyHint/destructiveHint=false annotations, the description discloses refusal-before-execution behavior (QUERY_TOO_BROAD), CORPUS_EMPTY for out-of-profile scope, SNAPSHOT_CHANGED on stale continuations, LDC-Qxxxx error codes with hints, row-limit budgeting (default 20, cap 5000), and the explain funnel on empty results. This is exactly the kind of operational 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?

The purpose is front-loaded, but the body is a dense run-on that enumerates 14 relations and 9 function signatures plus scope, examples, catalog questions, and pagination in one block — much of which the description itself defers to `law query --schema`. It is information-rich but substantially over-sized for a description field.

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 11 parameters, nested objects, and no output schema, the description carries the full return-shape burden and does so: queryPage with resultHash, snapshot, rowCount, rows/rowLimit/rowOffset, next-with-snapshot, and full:true semantics. Provenance, empty-answer, and error behaviors are all covered, so an agent has what it needs to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies that `query` is inline LawQL vs `question` naming a catalog entry vs `case`/`arguments` replacing clauses, and it explains rowLimit's budget vs an eval cap. It largely restates the schema's own parameter docs for corpus/snapshot/full, so it does not reach 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?

The opening states a specific verb and resource — a deterministic LawQL query over the CLIR of a formalization — and immediately scopes it as "a question about the model of the act itself, not about a case," which distinguishes it from case-oriented siblings like law_case_ask. It stops short of naming those siblings or summarizing the tool in plain terms, so the dense jargon keeps it from 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 clear context for when the tool applies (model-level questions, structural query over relations/functions, or a catalog question from `--list`), and it contrasts the model scope against case queries. It does not explicitly route the agent between this and siblings such as law_ask or law_search, so it lacks a true when/not/alternative statement.

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

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

Annotations 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.