GLO Law

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

Annotations already establish readOnly/idempotent/non-destructive, but the description adds far more than they do: results are never clearances, negative history is unverified with known false positives, quote matches use a nearest-neighbour join with attribution_distance, protected-info hits are not rulings, and the document is not stored or logged. It also discloses hard bounds (200 citations, 25 detailed flags, flagged_without_detail, citations_truncated) and the 2026-09-30 collection cutoff, which prevents misreading an empty result as 'no such case'.

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 body is organized by labeled blocks (reported_negative_history, quotes[], protected_info, Bounds), so an agent can scan to the section it needs. It is dense and clause-heavy and could be tightened, but with no output schema much of the detail is load-bearing rather than 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 must carry the full return-value contract, and it does: per-citation statuses, quote statuses and their caveats, protected-info fields, truncation limits, and the guaranteed headline/note/coverage_note envelope. Nothing an agent needs to interpret a response correctly appears to be 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?

Only one parameter exists and schema coverage is 100%, with the schema already documenting the 380,000-character cap and the refuse-rather-than-truncate behavior. The description adds nothing about the 'text' parameter specifically, so the baseline of 3 applies; the richer semantics it does provide are about outputs, not inputs.

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 sentence names a specific verb and resource ('checks the case citations in a document the user supplies') plus the concrete input artifact (draft filing, brief or motion) and the decision it supports (which cases to read before filing). That is clearly distinguishable from siblings like citation, citations and treatment, which operate on individual citations rather than a whole document.

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 usage context (pre-filing review of a user-supplied draft) and rules out expectations by listing what is not checked (short forms, statutes, rules, secondary sources, block quotations). It also points to adjacent tools ('Negative-history limits are those of the treatment tool' and 'The sources tool returns this tool's full coverage statement') but never states an explicit 'use X instead when Y' routing rule.

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

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

Annotations already declare read-only, idempotent, closed-world, non-destructive, so the safety bar is low — yet the description adds substantial non-obvious behavior: 404 means absence from this mirror rather than nonexistence of the case, one citation can match multiple records, results are capped at 25 with a capped=true flag, and every response (including misses) carries a provenance/coverage note.

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 resolution behavior, then layered caveats in short declarative sentences with no filler. The closing pair "Every response carries a note... A miss carries one too." is slightly redundant and could be one sentence.

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 describing returns, and it does so well: cluster list, 25-record cap, capped flag, note field, optional attachments. What remains unspecified is the shape of each cluster record and error behavior other than 404, which is a minor gap for a two-parameter read tool.

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 both the cite format and the include enum are already documented. The description only glosses the include options as "member opinions and parallel citations," adding no syntax or behavioral detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb ("Resolves") and resource (a reporter citation in the local mirror), gives the exact input format and an example (347 U.S. 483), and names the return type (matching case cluster(s)). This is clearly distinguishable from siblings like citations, cluster, and treatment.

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 sets the expected use (look up a known cite in this mirror) and explicitly fences off a competing use case by stating that a resolved citation is "not a good-law, treatment or validity signal," which routes validity questions to the treatment sibling. It does not explicitly name an alternative for cite-level listing (citations) or for fetching a cluster, so it falls short of full when/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?

Beyond the annotations, the description discloses the 1000-reference examination cap, out_of_corpus_count, examined_capped as a floor marker, the 22.7% missing-edge rate, per-opinion count behavior, and the 10-opinion limit on passages. These are substantial behavioral details that materially affect interpretation of results.

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

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

The purpose and direction semantics are front-loaded, and the density is justified by the tool's interpretive caveats. However, the description is a single dense block and includes some highly specific examples and statistics that make it harder to scan than it could 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?

There is no output schema, so the description must explain return semantics; it does so thoroughly with counts, coverage notes, passage fields, per-opinion behavior, and corpus-ending caveats. An agent has enough context to call and interpret this tool correctly.

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

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

Schema coverage is already 100%, so the schema carries the basic parameter meanings. The description adds useful semantics for with_passages, including the cited_by-only restriction, verbatim sentence behavior, and the at-most-10-opinions limit, but it does not deepen every parameter beyond 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 states a specific verb and resource: given one opinion id, it lists cases cited by that opinion or cases citing it, selected via direction. It also sharply distinguishes the tool from treatment/validity tools by saying the edge is textual reference only, not treatment or 'good law'.

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 explicitly explains the two direction modes and when each applies, warns that a thin cited_by list is not evidence of low citation, and clarifies the date cutoff for recent authority. It also points to sources for the full coverage statement and distinguishes this graph from Shepard's/KeyCite-style treatment.

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 and closed-world, so the safety profile is covered. The description adds genuinely new behavior: the payload is metadata-only (no opinion body) and every response carries a 'note' about its source and coverage limits — a disclosure an agent would not otherwise 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?

Three short sentences, front-loaded with the highest-value fact (what detail you get), then the scope limit, then the response note. Nothing is redundant or padding.

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 one-parameter read tool with no output schema, the description supplies what's missing: the shape of the return (metadata, member opinions, parallel citations) and the recurring coverage note. An agent has everything needed to call it correctly and interpret the result.

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% and the single 'id' parameter is already documented in the schema with its provenance (search/fts/citation result: id or cluster_id). The description's 'by cluster id' restates rather than extends that, so 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?

States a specific resource (cluster / full case) and enumerates what comes back: cluster metadata, member opinions, parallel citations. It also names the sibling 'opinion' as the full-text alternative, so an agent can distinguish the two without opening either schema.

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

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

The sentence 'Metadata only; the opinion tool returns full text' explicitly routes the agent to the sibling when full text is needed, which is the main usage decision for this tool. It stops short of covering the other direction, such as how it relates to search/citation lookups that produce the id, but the key alternative is named.

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/closed-world annotations, it discloses that policies change without notice, that unposted policies are absent, that revoked policies are listed with a successor, that held numbers return only status/reason and never text, and that Hawaii serves machine-read text for only 40 of 204 files. These are exactly the behavioral caveats an agent cannot infer from annotations or schema.

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 front-loaded correctly — purpose and the not-law boundary come first, caveats after — and nearly every sentence carries unique information. However it is a dense, run-on block with repeated constructions (multiple "answers X, never text" clauses) and partially duplicates the schema's "give number or query, not both" rule, which costs it 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 no output schema, the description fully carries the burden: it enumerates the returned fields (number, title, printed dates, replaced version, GLO read date, coverage_note) and explains the non-text outcomes for held, not-posted and revoked numbers. Coverage caveats for partial departments and Hawaii round out everything needed to call it correctly.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: keyword matching does no stemming, the special number value "contents" lists a department's files, and number forms vary per department (Kansas General Orders such as "TCF 15-101", BOP "OP 038.1"). Only the limit parameter's behavior is left entirely to the schema.

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

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

The first sentence names a specific resource (internal policies of a state DOC or the Federal BOP) and the two lookup modes (by number or by keyword query), and it explicitly carves out what it is not: statutes, regulations and court rules. That negative framing distinguishes it cleanly from siblings like statute, statute_search and citation without needing their 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?

It states a hard operational rule ("Give number or query, not both"), explains that a state absent from the enum simply isn't loaded, and routes the agent to sources(tool="corrections_policy", source=<code>) for per-department coverage and number forms. It stops short of explicitly naming which sibling to use when the target is actual law, though the "NOT law" framing implies it.

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 description's added value is the interpretive behavior: ambiguous text is counted under every reading with 'earliest' as the safe date, Kansas holiday orders are held only for 2025–2027 as one reading, and it is pure computation with no database query. Strong disclosure of limitations, though the warning semantics ('each applies to the date given') stay slightly opaque.

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

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

Front-loads the core purpose, but the body is a long run-on sentence packing five rule summaries and a return-field inventory into dense clause chains. The information earns its place, but the delivery is hard to scan and structure 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 return contract (status, readings with id/label/date/steps, earliest, latest, warnings, rule row with citation/text/corpus/as_of/source_url, detail, query, note) and states the coverage limits. Nearly complete for a complex tool; only the precise meaning of a few return fields and warning attachment remains 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?

Schema description coverage is 100% and the enum descriptions already explain per-rule parameter applicability, so the baseline is 3. The description reinforces rule-specific behavior (user-supplied days, three-day service additions, one-year outer limit for grievances) but adds little that the schema fields do not already state.

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: counts a deadline from a start date under an enumerated set of named rules, and returns counting steps alongside the verbatim rule text. The enumerated coverage (K.S.A. 60-206, K.A.R. 44-15-101b, FRCP 6, FRAP 26, 28 U.S.C. 2107(a)) makes it unmistakable against siblings like statute or citation.

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 in-scope (days-based periods, forward or backward, service add-ons) and explicit out-of-scope ('Not counted: periods in hours'), plus a routing pointer to the sources tool for the full coverage statement. Lacks an explicit contrast with a sibling tool that might otherwise be chosen for a similar date question.

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

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

Annotations only cover the read-only/idempotent profile, yet the description adds real behavioral context: exact-match/no-stemming semantics, coverage counts including 1,798 unsearchable records, the 2026-09-30 corpus cutoff and how to interpret empty results, freshness metadata fields (body_as_of, body_pending), and a transient 503 with one retry. That is substantially more than structured fields 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?

Front-loaded: the first sentence pins down mechanism, scope, and the keyword-vs-concept distinction before any caveats. It is dense but not padded, though the long coverage-statistics and freshness-metadata passage makes it heavier than a selector strictly needs.

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 burden of explaining returns and does so (opinion_id, cluster_id, BM25 rank, case metadata, highlighted snippet, plus the per-response 'note' and body freshness fields). For a 7-parameter search tool on a finite mirror, an agent has everything needed 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 description coverage is 100%, so baseline is 3. The description restates the 'q' semantics already present in the schema (all words must appear, no stemming, quotes for phrase) and says nothing about court, limit, date bounds, min_citation_count, or precedential_status, so it adds little beyond structured data.

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 ("Keyword full-text search (BM25) over opinion body text") and immediately contrasts itself with the conceptual sibling semantic_search. An agent can distinguish it from semantic_search without opening either 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?

Explicitly says when to use the alternative ("A case that states the concept in other words does not appear; semantic_search covers that gap") and warns about misreading thin results near the collection cutoff. It does not, however, differentiate from the plainer sibling 'search', which an agent must still infer about.

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

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

Goes well past the annotations (which only cover read-only/idempotent safety) by disclosing extraction provenance (body_source, fallback_used), a 200k-character truncation bound with truncated/text_available flags, and staleness semantics via body_as_of, body_pending, and body_note. It also explains the failure mode where an unreadable count makes an empty result inconclusive, and notes every response carries a source/coverage note.

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 correctly front-loaded, but the paragraph becomes dense and parenthetical-heavy, and the staleness explanation is spread across body_pending, body_note, and body_pending_note in a way that is hard to parse in one pass. Every claim is relevant, but the phrasing repeats rather than consolidates.

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 return-value burden and does so thoroughly: truncation flags, provenance, staleness states, and the universal note field. Only minor gaps remain, such as error behavior for invalid ids and whether any supplementary metadata fields exist.

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% and the single id parameter is fully documented in the schema (including where to obtain it). The description adds only the phrase "by opinion id," so it neither compensates for nor enriches the schema meaningfully beyond the baseline.

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

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

The opening sentence names a specific verb and resource: "Full text of one opinion by opinion id, plus metadata." It is immediately distinguishable from siblings like search, fts, semantic_search (which locate opinions) and treatment/citation (which the description explicitly disclaims).

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

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

Usage is only implied: an agent infers this is the retrieval step after a search returns an opinion_id (that hint lives in the schema, not the description). The negative statements "not live CourtListener... no treatment, 'good law' or citation-validity status" gesture toward the treatment and citation siblings but never name them or state when to prefer 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 only declare a safe, idempotent read; the description goes well beyond that with the things an agent actually needs: partial and citation-skewed coverage, a 2000-line examination cap with `examined_capped=true` marking a floor, the meaning of `unattributable_in_window`, and the fact that `score` has no documented meaning. It also discloses that near-duplicate grouping and the representative pick are this service's own choices, and that the case-law mirror ends 2026-09-30 — so an empty result is explained rather than misread as absence of authority.

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 front-loaded with the core definition, which is good, but the body is one long paragraph of stacked parenthetical asides and an inline Miranda example (107252 vs 9423233) that is illustrative but expensive. Exact corpus counts like 10,174,547 and 6,561,861 add bulk without changing agent behavior, and the dense punctuation makes it harder to scan than it needs to be.

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

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

For a two-parameter read tool with no output schema, the description covers everything that would otherwise be guesswork: what a returned row contains (case name, date, citation_count, group_id, group_size), why rows are grouped, how empty or capped results should be interpreted, and that every response carries `note` and `coverage_note`. Nothing material is left for the agent to infer.

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 earns extra credit by hammering the critical ambiguity that `id` is the DESCRIBED opinion, not the citing one, and by explaining that `limit` counts groups (one representative row per group) rather than raw parentheticals. That grouping/limit interaction is the main semantic trap and it is spelled out.

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

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

The opening sentence names a specific verb and resource ('returns the one-line parentheticals later courts wrote about that case, verbatim') and pins the input to a single opinion id. It then explicitly separates the tool from neighboring concepts ('not a holding of the described case... not treatment, validity or "good law"'), which lets an agent distinguish it from the sibling treatment and citations tools without opening a schema.

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

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

Usage is clear: call it to see how later courts characterized a case, and go to `treatment` if you want validity/good-law status. It also names `sources` for the full coverage statement and points at `same_case_opinions` / `most_parentheticals_on` for sibling opinions. What's missing is an explicit statement of when this tool should be skipped entirely (e.g., for pre-coverage or uncited cases), though the coverage caveat implies it.

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 (readOnly/idempotent/openWorld=false), the description discloses that results are metadata only with no opinion text, enumerates the returned cluster fields, and states the collection's coverage cutoff of 2026-09-30. It also explains that every response carries a "note" about source and coverage limits, which is non-obvious 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?

Content is front-loaded: purpose, match semantics, return shape, exclusions, then the coverage caveat. It is dense but nearly every sentence carries unique information; the parenthetical record count ("10,174,547 case records") is slightly heavy but serves to justify the coverage claim.

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 correctly enumerates the returned cluster fields, and it closes an important interpretive gap by explaining that empty results reflect the mirror's coverage end rather than absence of the case. Nothing an agent needs to invoke or interpret 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 coverage is 100%, so the baseline is 3, but the description adds real meaning by explaining that the q parameter is matched via punctuation-insensitive trigram (with a concrete example), which the schema's "case name or fragment" does not convey. Sort, court, and date parameters are left to the schema, which is adequate.

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 ("Case-name metadata search over the local CourtListener mirror") and immediately qualifies the matching mechanism (punctuation-insensitive trigram on case name). It distinguishes itself from concept/semantic siblings by stating "not concept search... it finds a case by its name, not by what it is about."

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 (concept search) and explains how to interpret thin results for recent authority. It stops short of naming which sibling to use instead (e.g., semantic_search or fts), so the agent must infer the routing, but the context is otherwise 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?

Beyond the read-only/idempotent annotations, it discloses that ranking covers only a partial embedded subset, that similarity is not treatment or validity, that matched_text is null about 10% of the time with a status reason, and that an embedding outage yields a 503 rather than an empty match. That is exactly the kind of failure-mode 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?

It front-loads purpose, then results, then limits, which is a sensible order, and nearly every sentence carries a distinct constraint. It is dense and runs long, with the coverage/degraded-state material packed into a single block that would read better as separate clauses, costing a point.

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 describing the returned fields (opinion_id, distance, similarity, matched_text_status, same_case_other_opinions, duplicate_records) is necessary and is done. Combined with coverage, cutoff date, and degraded-state behavior, an agent has everything needed to call it and interpret the response correctly.

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

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

Schema coverage is 100% and both parameters (q with 3-200 length, limit 1-20) are already documented in the schema, so the description adds little parameter guidance. Its value instead goes to return-field semantics, which is a different dimension. Baseline 3 applies.

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

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

The description states a specific verb and resource ('semantic (vector) search over embedded opinion chunks') plus its scope and matching mode, and explicitly distinguishes itself from the sibling 'fts' route. An agent can tell it apart from search, fts, or similar without opening a schema.

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

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

It states the selecting condition ('when there is no fixed term of art') and names the alternative route ('fts is a separate route'), so the choice between keyword and concept search is explicit rather than inferred. It also warns against misreading a thin result for recent authority, which governs how to interpret use near the collection edge.

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 it discloses real behavioral traits: a hard coverage boundary (case law ends 2026-09-30, exact count), staleness signaling via body_as_of/body_pending/body_note, the inconclusive-empty-result case when a count is unreadable, and a 503 cold-index behavior with a single server-side retry.

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 purpose and mechanism before the caveats, and each sentence carries operational information an agent would otherwise get wrong. It is dense and long for a two-parameter tool, with coverage/staleness detail that could partly live in the response note, costing it a point.

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?

The tool is simple, but the corpus has real traps (date cutoff, stale text, cold index). With no output schema, the description still explains the notable response fields and how to interpret empty results, leaving nothing an agent needs in order to call and read it correctly.

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

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

Schema coverage is 100% and both parameters are documented in-schema (id sourced from search/fts/semantic result opinion_id; limit 1-20, default 20). The description confirms that the id is an opinion id, not a case id, but adds no syntax or default detail beyond the schema, so 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?

Opens with a specific verb+resource: 'Given one opinion id, returns other opinions whose wording overlaps it, ranked by keyword match (BM25 more-like-this).' It explicitly delimits the mechanism ('Keyword overlap only') which separates it from search/semantic_search siblings, and states the exclusion of the seed opinion and its own case.

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?

Strong contextual guidance: it says what the result does NOT mean (not same issue, same result, or good law) and how to read a thin/empty result against the collection cutoff. It never names an alternative tool (e.g. semantic_search for conceptual similarity, treatment for validity), so the agent must infer the fallback, which keeps it below 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 readOnly, idempotent, non-destructive, and closed-world, so the baseline is low; the description still adds real value by disclosing that the data is 'served from the tool layer itself, with no database query' and by listing the exact return fields (tool, source, text, argument_descriptions, sources_available, note). The precedence note about per-response coverage_note is useful governance context. It does not specify size/verbosity of returned text, which would have made it a 5.

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

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

Front-loaded with the core action, then organized by mode (tool-only, source-code), then returns, then provenance. The long compound sentences pack several clauses each and repeat the schema's example codes, but every sentence carries information.

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

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

With only two parameters and no output schema, the description covers everything an agent needs: both input modes, what each returns, the field list, and where authoritative per-response coverage lives. Nothing required 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 3 is the floor; the description goes slightly beyond by tying the source code to concrete output consequences — 'citation forms, served and held counts and read dates' — and by pairing each tool family with its valid code domain. Much of the example-code content duplicates the schema's own parameter descriptions, limiting the added value.

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 ('Returns GLO's coverage statements as text') and immediately distinguishes itself from the data siblings by being a metadata/coverage lookup rather than a search or fetch. The two operating modes — tool name vs. source code — are named explicitly, so an agent can tell what it will get before opening the schema.

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

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

Gives clear conditional usage: use a tool name alone for that tool's statement, or pass a source/state code to get regulation-source coverage and citation forms. It stops short of explicit exclusions or a 'do not use when' clause, and the note that data tools' own response notes 'remain the record' implies precedence without stating it as a rule.

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 (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context beyond them: the four never-blended snapshots and their dates, per-source coverage/defect/held-unit notes, the rule that every response including 400 and 404 carries note and coverage_note, and the row flags (ends_at_colon, page_overlap_repeats_removed, last_amended_year_older_than_text). It also explicitly warns that as_of is a snapshot date and nothing in a result implies currency.

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 clause, which is good, but the body is a single dense block of semicolon-chained parentheticals, including a row count and a full enumeration of snapshot provenance. Much of that provenance is duplicated by the sources tool the description itself points to, so several clauses do not earn their place in a tool description.

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 citation-lookup tool with six optional parameters and no output schema, the description covers everything an agent needs: return fields, snapshot semantics, miss-versus-absence handling (structured_lookup_supported, cite_normalized, cite_forms_tried), held units answering kind "held" with no text, and row flags. It also correctly redirects to the sources tool for per-source coverage detail.

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 schema already documents cite, section, jurisdiction, title, source and raw with examples, so the description need not compensate. The description adds only marginal meaning, notably that source reaches exactly one regulation source and is never mixed, and that a hit form depends on jurisdiction. Baseline 3 is appropriate.

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

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

The first clause states a specific verb and resource with scope: "Exact lookup of one statute section or one regulation section by citation." It immediately distinguishes this from the sibling search tools (statute_search, fts, semantic_search) by emphasizing single-section exact citation lookup, and it explicitly excludes case law and annotations.

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 concrete routing guidance: omit source for statutes and Kansas regulations, set source=<code> to reach one regulation source alone, and use sources(tool="statute", source=<code>) for per-source citation forms. It also explains how to interpret a miss versus an absence. It stops short of naming a specific alternative tool (e.g. statute_search) for the browse/free-text case, so it is clear but not fully exclusionary.

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

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

Goes well beyond the readOnly/idempotent/non-destructive annotations: discloses ordering (most recently filed first, nothing else), the snapshot cutoff date, that subsection input is stripped and reported in subsection_dropped, that section_in_snapshot=false marks an absent section shown as written, and that every response including 400/503 carries note and coverage_note. It also quantifies reliability (precision 0.9845 on a blind sample, recall unmeasured) and names extraction gaps, which is exactly the context an agent needs to phrase confidence.

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 and purposeful in its first two sentences, but the body is a dense statistics block (25,093 of 60,444 sections, 10,745,929 records, occurrence-level 0.8870, distinct-pair 0.1697, Wilson intervals) that partly duplicates what the description itself says the sources tool provides. Several figures earn their place (base rate for empty results), but the precision/recall statistics could be trimmed without loss for a typical calling agent.

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 describing returns and does so for the non-obvious parts (parentheticals[] verbatim with 95.8%-empty base rate, section_in_snapshot/snapshot_detail, always-present note and coverage_note). It does not describe the shape of the citing-opinion records themselves (fields, whether cluster/opinion identifiers are included), which is the remaining gap for a caller building on 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 100% and each parameter is documented in-schema, so the baseline is 3. The description adds little parameter-specific meaning beyond what the schema already says — subsection stripping, the title+section alternative, and the limit/offset caps all appear in the schema text — though it does explain what happens at the semantic edges (dropped subsection reporting, refused state citations).

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 and resource ("Lists the opinions whose text cites one U.S. Code section") and immediately scopes it ("Federal only"), which separates it from sibling statute/statute_search tools that operate on statutes rather than citing opinions. It also states the semantic limit of an entry (text names the section, says nothing about treatment), so an agent knows what a hit does and does not mean.

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 (state citations are refused with a visible error) and warns that zero results is the majority outcome, so an empty list is not evidence of no citations — a rare and decision-relevant usage caveat. It also routes to the sources tool for the full coverage statement. It stops short of naming when to prefer statute_search or statute for resolving the citation string first, so it is clear context rather than a complete routing rule.

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 and idempotent annotations, it discloses ranking limitations, token handling, body-only matching, score instability, non-exhaustiveness, highlighting, and error behavior. The mixed-jurisdiction warning and distinction between a visible 503 and zero matches are especially valuable for correct interpretation.

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 and jurisdiction risk are front-loaded, and nearly every subsequent sentence supplies actionable behavioral or output-interpretation information. However, it is a dense single paragraph, repeats some schema guidance, and uses more space than necessary on precise benchmark figures.

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 still covers row metadata, snippets and highlight markers, rank, search-term diagnostics, ends_at_colon, response notes, and 400/503 behavior, while delegating full coverage details to sources. Together with the complete parameter schema and safety annotations, this gives an agent enough information to invoke the tool and interpret its results 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?

Although schema coverage is 100%, the description adds operational detail such as no stemming, duplicate collapse, the 40-word execution cap, body-only matching, and the practical risk of omitting jurisdiction. Some q and source guidance repeats the schema, and the description adds little beyond it for limit or title.

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 identifies the method (BM25 keyword search), resource (statute-section body text and, by default, Kansas administrative regulations), and scope. It also distinguishes the tool from statute, which returns full sections, while "Keyword, not concept" separates it from conceptual retrieval.

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 actionable selection guidance: use source to isolate one regulation source, constrain jurisdiction to avoid mixed-state results, use statute for full text, and use sources for coverage details. "Keyword, not concept" and "A section not returned is a miss, not an absence" also clarify when the tool and its results should not be relied upon.

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/idempotent safety, and the description adds substantial behavior beyond them: known false positives, a read guard (version 2) that withholds ten false shapes and reports them in declined_by_read_guard/read_guard_note, hand-read precision with confidence intervals, unknown recall, and the fact that only five labels are loaded. It also discloses that the overruling opinion itself is usually absent (Roe has no Dobbs row), which is exactly the kind of non-obvious behavior an agent needs.

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

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

Front-loaded with the essential definition and the id caveat, but the block is extremely dense and carries precision/recall confidence intervals and stratum-specific figures that matter more for trust calibration than for invoking the tool. Several clauses (sample sizes, intervals) could be moved to the referenced coverage statement without losing invocation-critical 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?

There is no output schema, yet the description documents the return shape in detail: every row carries the citing court's sentence, by_label reports all five labels regardless of filter, also_carried_by, unrelayable_in_window, capped, plus the mandatory 'note' and coverage_note, and ordering by citing-opinion date. Given the tool's complexity and high false-positive risk, nothing an agent needs to interpret results 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 schema already documents all four parameters, including the label enum note 'A filter over sentences, never a verdict'. The description reinforces the label-as-filter framing and the cluster-id-not-opinion-id distinction, but largely restates schema content rather than adding new parameter syntax or semantics; 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?

Opens with a specific verb+resource (later courts reporting a case was overruled/abrogated/etc.) and immediately disambiguates the identifier: 'Takes a cluster id (the case-record id), not an opinion id.' It also distinguishes itself from the sibling concept citation/Shepardizing, so an agent can place it against citation, citations and brief_check without opening a schema.

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

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

Explicit exclusions are given ('Not a validity verdict and not Shepardizing', 'zero rows is not evidence that a case remains good law', and the caveat that ~68.7% of findings are expressly partial), plus a temporal boundary explaining thin recent results. It stops short of naming a specific sibling to use instead when you want a positive/validity signal — it only delegates that to 'sources' for coverage.

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