nu:legal Deutsches Recht

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

Annotations already mark the tool as read-only and idempotent, so the description's job is to add behavioral nuance. It does: `observed` means first-seen date, not in-force date; the result is JSON; ordering is newest first; and the window is capped at 120 days. This goes well beyond the annotations and helps the agent use the feed correctly.

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, each carrying distinct information: the core function, the polling pattern, and the essential semantic caveat about `observed`. The most decision-relevant content is front-loaded in the first sentence, and there is no filler.

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

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

For a simple read-only feed, the description covers the polling model, ordering, date semantics, and window. It does not specify the response object shape, and there is no output schema, so an agent must infer the exact JSON fields beyond `observed`. Still, the description provides enough to call and interpret the tool in most 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 coverage is only 50%: `since` is described but `limit` is not. The description compensates for `since` by defining the critical `observed` semantics, which is more precise than the schema's 'on or after this date'. `limit` remains undeveloped, but its name plus schema constraints make it self-explanatory.

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

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

The description opens with a precise statement of what the tool does: it returns provisions whose text changed recently, ordered newest first, and identifies itself as a 'freshness feed'. This is a specific verb and resource, and the 'freshness feed' framing separates it from siblings like listNormVersions or search without ambiguity.

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 concrete polling strategy: set `since` to the newest `observed` value already processed. It also clarifies the 120-day window and notes that the law's own Änderungsverlauf reaches further back, implying an alternative for older changes. It does not explicitly name a sibling tool or state a 'when not to use' condition, but the context is clear.

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, idempotentHint, and destructiveHint. The description adds meaningful context: it explains that the tool reveals holes in the corpus, provides limits that clarify the meaning of version dates and source windows, and explicitly states that it never collapses two different answers. This is valuable behavioral context beyond the annotations and does not contradict them.

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

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

The description is concise, using three sentences to convey purpose, returns, and usage. It front-loads the core purpose ('Corpus scope with its holes stated') and then elaborates. No wasted words.

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 takes on the responsibility of explaining what the tool returns. It lists categories (totals, per-source windows, count of Aktenzeichen, limits) and explains what limits include. This is sufficient for an agent to understand the tool's output, though it could be more specific about the exact structure. For a zero-parameter tool, this is adequate.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameters, and it doesn't. It doesn't add parameter-specific semantics because there are none.

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 purpose: reporting corpus scope with its holes. It names the resource (corpus), the verb (get coverage), and distinguishes the tool by explaining it returns totals, windows, and limits, and that it differentiates 'outside_coverage' from 'not_in_corpus'. This clearly differentiates it from siblings like getNorm or search.

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 an explicit trigger: 'Call this once when your answer depends on whether an absence is real.' It also explains the key usage of distinguishing two distinct concepts, which is a clear instruction for when to use this tool over others. It doesn't need to list alternatives since it's a specialized coverage tool.

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

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

Beyond the readOnly/idempotent annotations, the description discloses response fields (first_observed, valid_to, date_precision, amendment_note), warns that first_observed is not the legal Inkrafttreten, and explains outside_coverage behavior for pre-archive dates. It also clarifies the trust semantics of fundstelle and authoritative_source.

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 structured into core purpose, parameter rules, point-in-time caveats, and trust metadata; every sentence carries actionable information. The front-loaded purpose statement is followed by logical sections, and no sentence is filler.

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

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

With no output schema, the description covers the key return fields, the outside_coverage error case, and how to quote or deep-link. It gives an agent enough to call the tool and interpret results correctly, including caveats about date precision and authoritative sources.

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

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

Despite 100% schema coverage, the description adds material meaning: ref must be the bare number with no §/Art and may carry letter suffixes, sub-units are dropped, aliases/case variants resolve, and as_of triggers version lookup with archive limits. This goes well beyond the schema examples.

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 line names the exact deliverable: 'the text of one provision, by default as clean Markdown.' This is a specific verb+resource, and the 'one provision' scope distinguishes it from siblings like listNormVersions, getChanges, and search, which serve different retrieval tasks.

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 clear operational context: how to format law and ref, when to use as_of, and the coverage caveat for dates before 2019-06-10. It does not explicitly name sibling tools as alternatives or say when not to use this tool, so it stops short of full 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description builds on this with crucial behavioral details: rn is null when the court printed no numbers, anchor_basis must equal 'native_numbering' for a reliable pin-cite, and amtliche_seite is always null because page breaks are absent. This goes well beyond what annotations provide.

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

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

The core purpose is front-loaded in the first sentence, and every subsequent paragraph earns its place with necessary caveats about citation integrity, page numbers, and pagination. There is no redundant or filler language.

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?

Since there is no output schema, the description responsibly explains the key return fields and their reliability implications, which is essential for correct citation usage. It doesn't enumerate every possible paragraph field or error behavior, but it is sufficient for an agent to invoke the tool correctly and 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?

The case parameter is well described in the schema, and the description adds pagination purpose for offset/limit. However, with only 33% schema coverage, the description mostly explains output fields (rn, anchor_basis, amtliche_seite) rather than adding deeper meaning to the input parameters, leaving limit/offset semantics mostly inferred from names and defaults.

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: it returns the full text of one decision split into citeable paragraphs. This clearly differentiates it from sibling tools like listCitedAuthorities and listCitingDecisions, which handle citation relationships rather than paragraph-level full text.

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

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

The description makes the use case clear: retrieve paragraph-level text for a single decision, with pagination advice for long decisions. It doesn't explicitly name alternatives or state when not to use the tool, but the return content is specific enough that an agent can identify when this tool is appropriate.

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 signal read-only and idempotent behavior. The description adds valuable, non-obvious details: treatment is always null, classification is intentionally unbuilt work, and known-missing cases return known_missing with attestations rather than a 404. This is exactly the kind of behavioral context annotations cannot provide.

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

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

The description is front-loaded with the primary purpose in the first clause)Skip and every subsequent sentence addresses a meaningful caveat or edge case an agent needs to know. There is no padding or repetition.

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 provides enough about the return shape: statute provisions with how often each is cited, relied-upon decisions, always-null treatment, and the known_missing representation. For a tool with one parameter and clear semantics, this is complete.

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

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

The input schema has 100% description coverage for the single parameter, documenting that case accepts a juris doknr, ECLI, or decision URL as returned by search. The description does not add additional parameter-level nuance, so the schema carries the load and the baseline 3 applies.

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

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

The description names the exact resource ('one decision'), the direction of the edges ('outgoing'), and the two kinds of results (statute provisions with citation counts, and relied-upon decisions). It also points to listCasePassages as the sibling to use for reading actual passage text, which helps an agent distinguish this tool from that one.

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 clear context for when to use this tool: to inspect what one decision cites)Skip or relies on with weighting. It also explicitly tells the agent to use listCasePassages when it needs to read the citing passage itself, which is an alternative. It does not spell out exclusions such as 'do not use this for incoming citations,' though the word 'outgoing' implies the boundary.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses the ranking order, the risk of over-reading early CJEU-heavy results, pagination via offset and pagination.next_offset, the citing_rn semantics, and the coverage limitation where total: 0 can mean 'not indexed' rather than 'no citations'. This is substantial behavioral context.

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

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

The description is long, but every paragraph earns its place: core instruction, ranking caveat, result semantics, and coverage warning. It is front-loaded with the essential either/or usage first. A slight trim of the 'Read the ranking honestly' phrasing would make it tighter.

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

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

For a tool with no output schema, the description provides the needed return-value hints (total, pagination.next_offset, coverage.complete_for_this_norm, citing_rn) and the coverage limitations that are critical for interpreting results. Nothing an agent needs to call this correctly and interpret its output is missing.

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

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

With only 40% schema coverage, the description compensates by clarifying the mutual-exclusivity of law+ref versus case, how offset interacts with pagination.next_offset, and what results represent. It does not add much on the limit parameter, but the schema already supplies default and bounds, and limit is self-explanatory.

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 phrase 'Incoming citation edges' plus the explicit 'EITHER law + ref OR case' formulation states exactly what the tool lists and what inputs select each mode. It clearly distinguishes the tool from the likely outgoing-citation sibling (listCitedAuthorities) by framing this as the incoming direction.

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 explains when to use law+ref versus case, and gives an explicit fallback to 'search' for Land provisions when coverage is incomplete. It does not explicitly name or exclude sibling tools like listCitedAuthorities, but the directional language and coverage guidance are strong enough for correct routing.

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 readOnly, idempotent, non-destructive, and openWorld=false. The description goes well beyond that by explaining the meaning of each field (first_observed, valid_to, date_precision, amendment_note), the at_archive_floor flag, and the caveat that earlier amendments exist but are not held. It also discloses the lack of a diff tool, which is a behavioral limitation an agent must know.

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

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

The description is dense but every sentence earns its place: purpose, ordering, field explanations, floor caveat, and the no-diff guidance. It is front-loaded with the primary use case and stays focused without redundancy.

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

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

For a read-only list tool with two parameters and no output schema, the description fully covers what the agent needs: what is returned, how to interpret ambiguous dates, the floor concept, and how to perform diffs. No critical behavioral or usage details are missing.

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

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

Schema description coverage is 0%, so the description must explain what 'law' and 'ref' mean. It only implies that they identify a provision ('Every stored version of one provision') without explicit details. The schema examples (BGB, 288) help, but the description adds no semantic meaning beyond that. Given the zero coverage, this is a notable 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 clearly states the verb (list) and resource (stored versions of one provision), and immediately ties it to a specific purpose: discovering which dates getNorm(as_of=…) can answer. This distinguishes it from sibling tools like getNorm and getChanges without needing to inspect 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?

The description explicitly tells the agent when to use this tool (before calling getNorm with an as_of date) and provides a concrete workflow: fetch two versions with getNorm and diff them because no diff tool exists. It also explains the floor-date concept, which is essential for interpreting results correctly.

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

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

The description discloses far more than the annotations: it never returns a near match, distinguishes statuses like `attested` from `not_in_corpus`, reports `date_mismatch`, returns stubs unless `include: ['text']` is passed, and distinguishes gazette citations from the tool's own URLs. This gives the agent a detailed behavioral model beyond readOnly/idempotent hints.

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

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

The description is long, but nearly every sentence carries distinct operational guidance: accepted formats, result statuses, stub behavior, and date mismatch. It is front-loaded with the key instruction ('Call this BEFORE...'). A small amount of repetition around the text stub could be tightened, but the density is justified for a complex tool.

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 carries the full burden of explaining return semantics. It covers all major result statuses, evidence fields like `normalised_from`/`normalised_to`, `fundstelle`, `text_truncated`, `date_mismatch`, and even warns against verifying quotations against stubs. Nothing essential for correct invocation appears 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, but the description adds real value: it clarifies citations are taken 'verbatim' and 'in the form you already hold it,' and it explains the `include` behavior in depth, including that `'text'` returns full text rather than a 300-character stub. That goes beyond the schema's own parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Ground a batch of German legal citations against the corpus.' It further narrows scope by listing accepted citation kinds and explicitly declaring 'Call this BEFORE stating any citation you did not read here,' which sets it apart from sibling search/retrieval 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?

It gives an explicit trigger ('Call this BEFORE stating any citation you did not read here') and explains how to handle each outcome, e.g., 'attested is not a failure... you may state that the decision exists.' It does not name sibling tools or explicitly say when not to use it, but the usage context is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: results anchored at best-matching Randnummer (#...rd_51), the cross-land by_jurisdiction roll-up, and which Länder hold full text. No rate-limit or auth notes, but for a read-only search tool this is a strong value-add.

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

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

The description is long and multi-paragraph with inline examples, but the density is justified by the tool's complexity (hybrid search, dual corpora, cross-jurisdiction behavior). The most important constraint — query both corpora — is front-loaded, and the 'CROSS-LAND COMPARISON' heading aids scannability. It earns its length, though it could be tightened.

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

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

With no output schema, the description carries the burden of explaining return structure, and it does: jurisdiction-labelled rows, the by_jurisdiction roll-up, and Randnummer anchoring for quoting paragraphs. The only gap is pagination behavior for the limit parameter — no indication of whether results are paged or how to page through. Minor given the overall completeness.

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

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

With schema coverage at 75%, the description substantially enriches the q parameter by explaining the German-language requirement ('write raw umlauts, they are handled'), the lexical-vs-semantic split, and the scope semantics in depth. It clarifies the misleading nature of scope='norms' far beyond the schema's 'Narrow only when you know which corpus answers.' This materially compensates for any schema 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 states a specific verb ('Search') over two distinct resources (federal/Land statutes and court decisions) and precisely characterizes the dual search semantics (lexical with concept pinning for norms, semantic for cases). It clearly distinguishes itself from siblings like getNorm (single-norm retrieval) and listCasePassages (case passages), so an agent knows exactly which tool does broad cross-corpus discovery.

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 instructs 'Search both unless you have a reason not to' and gives the concrete failure mode for narrowing too early (the 'Verzugspauschale' example showing why scope='norms' returns nothing when a term of art never appears in the governing statute). It also tells the agent when to flip include_repealed (researching an older state of the law) and recommends natural-language shape for case law.

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