CaseNode Case Law API

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered without description help. The description adds only that results are suggestions intended to feed a subsequent filter, which is mild context; it says nothing about how matching works (prefix vs substring), ordering of results, or what happens with an empty/ambiguous q. Given the annotated baseline, a 3 is appropriate.

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 usage directive is front-loaded in the first sentence, the routing instruction second, and per-parameter detail is quarantined in a structured Args block. Every line contributes; there is no filler or restatement of the tool name.

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, and the description fully specifies the three inputs for a simple three-parameter lookup tool. The remaining gap is competitive positioning against the sibling autocomplete_citations, which an agent may need to disambiguate.

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%, so the description carries the full burden and does so: field's three permitted values are enumerated with glosses ("claimant" = applicant/claimant/appellant side, "respondent" = defendant side, "judge"), q is illustrated with a concrete expansion example ("Lamb" → "London Borough of Lambeth"), and limit states both default (10) and ceiling (25). This is meaningfully more than the bare schema titles provide.

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?

"Get name suggestions for party or judge filters" gives a concrete verb (get suggestions) and a bounded resource scope (party/judge name filters), so the tool's function is unambiguous. It stops short of a 5 because it never distinguishes itself from the sibling autocomplete_citations, which an agent could easily confuse with a similarly named suggestion 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?

"Use this before filtering search_cases to find the correct spelling / full name" explicitly names the downstream tool and the sequencing condition, which is exactly the kind of routing guidance an agent needs. There is no explicit when-not guidance or mention of the alternative autocomplete tool, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety and scope profile is carried by structured data. The description adds that matching covers aliases as well as citations and case names, which is useful behavioral context, but says nothing about result ordering, ranking, or truncation behavior beyond the limit cap.

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, followed by a routing sentence and a compact Args block. The examples earn their space by showing the accepted input shapes; nothing is redundant with the title.

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 present, return values need not be explained, and both parameters are documented despite zero schema coverage. The remaining gap is minor: no note on how results are ranked or how to treat an empty result set.

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

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

Schema coverage is 0%, so the description must carry the load — and it does, defining 'q' with three concrete example formats ('Donoghue', '[2019] UKSC', 'Landlord and Tenant Act') and giving 'limit' a default and hard maximum of 25 that the schema omits (schema only declares default 10).

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

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

The description gives a specific verb and resource ('Search for authorities by partial citation, case name, or alias'), which is more precise than the title. It distinguishes itself implicitly from resolve_citation (exact resolution) and get_authority_detail, though it never states the inverse case — that an exact citation should skip this 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?

Explicitly states the triggering condition ('vague or partial reference') and names the downstream siblings (resolve_citation, get_authority_detail) in the correct order of operations. It stops short of stating when *not* to use it, e.g. for a complete, unambiguous citation.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful mode-dependent behavior (what changes based on the argument), but says nothing about result shape, taxonomy depth, or whether the authority list is truncated.

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 statement, then the two-mode behavior, then a short Args block with examples. No filler, no restatement of the tool name.

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?

Output schema exists so return values needn't be described, and annotations cover the safety profile. With one optional parameter fully explained, the only real gap is how the agent should disambiguate this tool from list_topics and top_authorities_in_domain.

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 parameter has no schema description at all, so the description carries the full burden — and it does: 'optional domain to drill into' plus two concrete slug examples and the null-argument behavior. Only the slug format convention itself is left implicit.

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 (browse the legal domain taxonomy) and enumerates its two modes: no argument returns top-level domains, a slug returns authorities in that domain. It doesn't differentiate itself from siblings like list_topics or top_authorities_in_domain, so an agent could hesitate between them.

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?

Clear context for the two call shapes — omit the argument to see the domain list, pass a slug to drill in. No exclusions or named alternatives are given, so the agent must infer which sibling to pick when it already knows a domain.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: it names the three citation categories detected and describes the return payload ('each citation with its type and canonical ID'), which is what an agent needs to chain into a resolution call.

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 purpose, then scope, then return shape — a sensible order with no filler. The trailing Args block is somewhat redundant for a single self-evident parameter, which keeps it off a 5.

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 fully specified, yet the description still summarizes them usefully. Combined with the input examples and the stated citation categories, an agent has enough to invoke this correctly; only explicit sibling routing 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?

Only one parameter and schema coverage is 0%, so the description carries the burden. The Args block ('text: Text containing legal citations') largely restates the schema, but the earlier sentence about acceptable inputs (paragraph, judgment extract, skeleton argument) does add real semantic guidance about expected content and size.

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 ('Extract legal citations from a block of text') and enumerates exactly what counts as a citation: case citations, statute references, and CPR rules. The phrase 'canonical ID for further lookup' implicitly points downstream to resolve_citation, though no sibling is named outright.

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 concrete input contexts ('a paragraph, judgment extract, or skeleton argument'), which tells the agent what to feed it, and 'for further lookup' hints that resolution is a separate step. However, it never explicitly says when to use extract_citations versus resolve_citation, resolve_citations_bulk, or autocomplete_citations.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is carried structurally; the description adds that the output is a text summary and that paragraph_ref injects a quoted paragraph into it. It does not discuss failure modes (invalid ID, unknown paragraph ref), which keeps it below 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 purpose sentence, then return contents, then routing guidance, then per-argument notes — four short blocks with no filler. Every sentence adds information an agent needs to choose or call the 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?

With an output schema present, listing return fields is a bonus rather than a requirement, and the sibling routing plus argument docs make the definition largely self-sufficient. The only shortfall is unstated behavior for unresolvable IDs or out-of-range paragraph_ref values.

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%, so the description must carry the load and it does: authority_id is documented with a concrete format example ('uk.case.uksc.2019.38') and paragraph_ref is described as an optional numbered paragraph to quote. It stops short of clarifying accepted paragraph_ref syntax (bare number vs. prefixed form) or whether a bad ref errors or is ignored.

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 ('Get full detail on a specific authority') scoped by canonical ID, then enumerates the returned fields. It explicitly contrasts itself with get_case_viewer, so the agent can distinguish it from siblings 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?

Gives explicit workflow placement ('Use after resolve_citation or search_cases when you need the complete record as text') and names the alternative plus the condition selecting it ('For an interactive case viewer ... use get_case_viewer instead'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description does not need to carry the full safety profile. It adds useful behavioral context: results are paginated by paragraph index, default limit is 50, maximum is 50, and it returns individual paragraph chunks rather than the full document.

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 purpose and usage before the Args section, and every sentence contributes concrete information. The parameter list is compact and directly useful for invocation.

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 paginated paragraph-reading tool with no output schema, the description supplies the key call semantics: pagination via offset/limit, defaults, max, and paragraph-chunk return behavior. It could optionally clarify the exact chunk shape or whether total counts are returned, but it is sufficient for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate, and it documents every parameter. It explains authority_id with a canonical ID example, offset as a 0-based paragraph index defaulting to 0, and limit as the number of paragraphs defaulting to 50 with a maximum of 50.

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: reading paragraphs from a judgment in pages, returning individual paragraph chunks from the authority's full text. It explicitly differentiates this from get_authority_detail by noting that it accesses sections beyond the truncated text there, so an agent can understand its role without opening schemas.

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

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

It gives clear usage contexts: reading through long judgments page by page or accessing specific sections beyond the truncated text in get_authority_detail. The named alternative helps routing, though it does not explicitly state when not to use this tool or distinguish it from sibling read_judgment_text.

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

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

Goes well past the readOnlyHint/openWorldHint annotations: it discloses the exact return payload and its equivalence to GET /authorities/{id}/viewer, the scroll-and-highlight side effect of paragraph_ref, and the non-obvious trap that an undeclared argument is silently dropped by FastMCP, causing every page turn to refetch page 1. That last detail is exactly the kind of behavior an agent cannot learn from structured fields.

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 return shape, then a conditional behavior sentence, then parameter docs. The Args block is slightly verbose and the FastMCP implementation note is long, but every sentence carries actionable information.

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

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

With no output schema, the description covers the return payload shape at a high level, and it fully accounts for all three parameters and the paging mechanism. It stops short of describing payload size or pagination limits, which matters for a viewer that pages through judgment paragraphs.

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 carries the whole burden and does so well: all three params get concrete examples ("uk.case.uksc.2019.38", "45" / "para 12") and paragraph_offset is explained as 0-based plus why it must be declared. Only the accepted range for paragraph_offset is left unspecified.

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 ("Open the interactive case viewer for an authority") and immediately names the payload it returns (judgment paragraphs, cites, cited-by, test elements), which distinguishes it from pure text readers. It does not, however, contrast itself with close siblings like read_judgment_text or get_authority_detail, so an agent must infer the difference.

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 mention that paragraph_ref comes "from search_extracts" implies a search-then-open workflow, and the paragraph_ref/offset behavior hints at page-turning usage. But there is no explicit statement of when to pick this over read_judgment_text or get_authority_paragraphs, and no exclusion conditions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds that it returns *every* paragraph referencing the authority, with pinpoint refs and highlighted citation spans — useful completeness context. It doesn't say what happens when the edge exists but no paragraph references were extracted (empty list vs error), which keeps it below 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?

Purpose sentence first, output content second, usage guidance third, then a compact Args block. No redundant restatement of the title, and every sentence adds information.

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

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

With an output schema present, return shape needn't be spelled out, and the direction of the edge — the main way to misuse this tool — is made explicit. Missing only an edge-case note (no matching paragraphs, invalid/unresolved IDs) for a 2-param lookup.

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 carries the burden — and it does, disambiguating the critical direction (citing = source of edge, cited = target) for both parameters. It does not explain where canonical IDs come from (resolve_citation) or their format, leaving a 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 (get paragraphs in a citing case that reference a cited case) plus the exact directed edge semantics. It is clearly distinguishable from get_authority_paragraphs (all paragraphs of one authority) and get_citation_network/subgraph (structure without 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?

"Use after exploring a subgraph or citation network to see exactly how one case treats another" gives an explicit workflow position and names the sibling tools it follows. It does not state when-not to use it (e.g., when you only need counts or the citation is unverified), so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds a genuinely non-obvious behavioral trait: results are ordered with the most senior court first, so page one reflects appellate treatment rather than recency. It does not address edge cases such as an authority with no citations.

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 unbounded by preamble, and the ordering caveat sits high enough to influence how an agent reads the first page. The 'Essential for understanding...' line is mildly promotional but still earns its place by naming the use case; the Args block is long but justified by the empty schema descriptions.

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 present, return values needn't be described, and everything an agent needs to call correctly is here: the three traversal directions, court filtering, pagination, and the non-obvious result ordering. Nothing material is missing for a read-only five-parameter traversal 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 0%, so the description must carry the whole burden, and it does: all five parameters are documented, including the three literal direction values with plain-language glosses, court-code examples (EWCA-Civ, UKSC), and the semantics of limit/offset. It also explains the practical trade-off between court filtering and paging.

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, and the follow-up enumerates the three modes precisely: 'what cases cite this authority, what it cites, or what's commonly cited alongside it.' That is far more specific than the title alone, though no sibling tool (e.g. get_citation_subgraph, get_related_authorities) is named to draw the boundary explicitly.

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

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

It states the analytical purpose ('understanding how an authority has been applied and what it relies on') and gives concrete operational guidance: on a heavily cited authority, filtering by court beats paging. That covers when to use it, but there is no explicit when-not, and no routing guidance against the overlapping citation siblings.

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 readOnlyHint/openWorldHint: it discloses exactly what comes back (node/edge counts, most-cited authorities, edge-type breakdown) and the cap guard — when the match set exceeds the cap you get a total count and a request to narrow, mirroring the Explorer UI. That is precisely the kind of truncation/limit behavior 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?

Front-loaded with the one-sentence purpose, then return shape, then the cap guard, then the Args list. The Args block is long but justified at 0% schema coverage; 'default 500, max 500' slightly duplicates the schema default but also adds the max, so it 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?

With 14 optional params, no output schema, and only two annotations, the description supplies the two things structured fields cannot: what the return payload contains and what happens at the cap boundary. An agent has enough to call it and interpret the result without trial and error; only filter-combination semantics remain 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 0%, so the Args block carries the full load and does it well: examples for query, domain, court codes, the six disposition values, jurisdiction strings, multi-select topics, substring-match semantics for claimant/respondent/appeal_from, and cap's default/max. Minor shortfall: it doesn't say how year_from/year_to interact or whether filters combine as AND, and the null defaults are never explained.

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: return a filtered citation subgraph, plus the intended activity (graph exploration). An agent can tell this is the graph-shaped counterpart to search_cases from the 'same filters as search_cases' line, though it never explicitly contrasts itself with the sibling get_citation_network, which an agent must disambiguate on its own.

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 says to use the same filters as search_cases and explains the narrow-your-filters fallback, which gives implied usage context. But it never states when to choose this over get_citation_network, get_related_authorities, or top_authorities_in_domain — a real gap given six graph-adjacent siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description explains the conceptual behavior of shared citation patterns, but adds no operational details such as pagination, result ordering, or practical limits beyond the parameter default.

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 core purpose and then provides a useful contrast. The Args block repeats schema fields, but that repetition is justified by the lack of schema descriptions and remains brief.

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. Given the read-only annotations and two-parameter schema, the description is complete enough for correct invocation, though it could better situate the tool among its actual siblings.

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 compensate. It does so by documenting both parameters: authority_id as the canonical ID and limit as the maximum number of results with a default of 20.

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: find authorities related through shared citation patterns. It explains the concept clearly and contrasts it with co_cited, though it does not distinguish itself from the actual sibling tools get_citation_network or get_citation_subgraph.

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 explicit usage guidance by contrasting with co_cited: use this when looking for cases that cite similar sets of authorities rather than cases cited alongside each other. However, it does not mention the related sibling tools available in this toolset.

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 and closed-world safety, but the description adds a genuinely non-obvious operational fact: calling it does not consume the daily limit. That is exactly the kind of context an agent needs before firing it during a quota scare. It stops short of stating auth requirements, so not a 5.

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

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

Two short blocks: the return payload first, then the invocation triggers. Every clause carries information and the most decision-relevant content (what you get, why you'd call it) is front-loaded.

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 shape is already documented, and the description nonetheless names the four key fields for fast scanning. For a no-argument read tool this leaves nothing an agent would need to know before calling.

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?

Zero parameters, so the baseline of 4 applies. There is no parameter semantics to explain, and the description correctly spends no words on a non-existent input surface.

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 (CaseNode usage) and enumerates exactly what is returned: today's request count, daily limit, remaining allowance, and reset time. This is unmistakably distinct from every sibling tool in the list, none of which deal with quota or billing state.

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 an explicit trigger set ('user asks about their usage, limits, quota or plan') plus a proactive condition ('after a usage warning'). No alternatives are needed because no sibling overlaps, so the routing guidance is complete.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description notes the corpus-wide scope and the fields exposed, but adds no pagination, ordering, or freshness context beyond that; with an output schema documenting the return shape, there is limited extra behavioral value.

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, front-loaded with the resource and payload, second sentence devoted entirely to routing guidance. 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?

Complete for a zero-parameter, read-only discovery tool whose return fields are documented by the output schema. Only minor gaps remain, such as result ordering or whether the court set is static.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter claims are made or contradicted.

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 plus the payload contents (case counts, precedence ranks, binding relationships), which is concrete and non-tautological. It does not explicitly distinguish itself from taxonomy-style siblings like browse_taxonomy or list_topics, 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?

Explicitly tells the agent when to use it: to discover valid court codes for filtering search_cases, research_pack, etc., and to understand the hierarchy. It names downstream consumers but offers no exclusions or guidance on when browse_taxonomy or list_topics would be the better choice.

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

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

The annotations already declare this is a read-only, closed-world operation. The description adds useful behavioral context by stating that the result is topic slugs intended for use as filters elsewhere. It does not discuss permissions, rate limits, or pagination, but those are less critical given the annotations and simple read-only nature.

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 core purpose and return value, then provides just enough argument detail. Every sentence adds useful information with no redundant restatement.

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 one-parameter read-only list tool with an existing output schema, the description covers purpose, output meaning, downstream use, and parameter behavior. Nothing needed to call it 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?

Schema description coverage is 0%, so the description must carry the parameter meaning. It does so fully: explains `domain_slug` as a filter to topics under a domain, gives concrete examples ('employment', 'landlord-tenant'), and states that omitting it returns the full taxonomy.

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 uses a specific verb and resource: listing legal topics from the domain taxonomy. It also clarifies the output is topic slugs usable as filters. However, it does not explicitly differentiate this tool from the sibling browse_taxonomy, which could leave an agent unsure which taxonomy tool to pick.

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 usage context: use this to obtain topic slugs for the `topic` filter in search_cases and other tools. It also states the when-not case for the optional parameter ('Omit for the full taxonomy'). It does not name alternative taxonomy-browsing tools.

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

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

The annotations already establish that this is a read-only, non-open-world operation. The description adds useful behavioral context by emphasizing that the text is exact and untruncated, that long judgments are paged via offset, and that the limit has a default and maximum.

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 core purpose and sibling differentiation, then follows with a compact Args section. Every sentence adds useful information about what the tool returns or how to page through results.

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

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

Given that an output schema exists and annotations cover the safety profile, the description supplies everything an agent needs to invoke the tool correctly: exact-text behavior, sibling distinction, paging guidance, and all parameter meanings.

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 carries the full burden and does so well. It explains authority_id as a canonical ID with an example, offset as a 0-based character offset with default 0, and limit as a character count with default 8000 and max 50000.

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: read the complete, untruncated judgment text by character offset. It also explicitly distinguishes this tool from get_authority_paragraphs, so an agent can select it 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?

It names the alternative sibling tool and explains the key selection condition: get_authority_paragraphs serves pre-processed chunks that may skip or truncate text, while this tool returns exact full text. It also explains how to page through long judgments by advancing the offset.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds useful behavioral context by explaining what the pack returns, how target_court adds binding/persuasive status, and how top_authorities controls result count. It does not discuss latency, limits, or result-size constraints, but the annotations reduce the burden.

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 purpose and return shape, then gives a compact argument list. For a 10-parameter tool, the length is appropriate and every section contributes useful 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?

Given the 10 parameters and 0% schema coverage, the description is largely complete: it covers every parameter and explains the tool's output and purpose. It leaves out explicit sibling routing and some parameter formatting details, but the presence of an output schema reduces the need to explain return values further.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it does list all 10 parameters with meanings. It provides examples for domain, disposition, jurisdiction, and topic, and explains target_court's effect, though some entries like 'court: Court code to focus on' remain thinner than ideal.

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 ('Get a structured research pack on a legal area') and describes the return contents, including authorities, legal test elements, and usage examples. It distinguishes itself as the 'richest tool' for substantive research, though it does not name a sibling alternative.

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

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

Gives clear usage context: use it for substantive legal research on a topic, and implies it is the comprehensive option by calling itself the richest tool. It does not explicitly state when not to use it or name alternatives such as search_cases or get_authority_detail.

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 and openWorldHint=false, and the description adds genuinely new behavior: it discloses the two possible outcomes (exact match vs disambiguation list) and the side effect that an exact case-law match automatically opens the interactive case viewer. That side effect is the kind of thing an agent could not 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?

Front-loaded with purpose in the first sentence, followed by supported inputs and return behavior. The Args block is slightly redundant with the schema but earns its place by showing concrete example strings.

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 return-value burden and does so at a coarse level (exact record vs disambiguation candidates), plus it flags the case-viewer side effect. It stops short of describing what a disambiguation candidate contains or ranking behavior, but nothing critical for correct invocation 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 0% and the single 'citation' parameter is undocumented in the schema, but the description's Args block supplies both the semantic ('citation string') and concrete examples across formats (neutral citation, statute name). This compensates well for the schema gap, though it omits format edge cases such as pinpoints.

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 (resolve) and resource (a legal citation) plus what comes back (full authority record). It clearly delimits scope by listing accepted formats, which separates it from extraction/search tools, though it never names a sibling like resolve_citations_bulk or autocomplete_citations.

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 context for use: any citation format, whole or partial names, and the outcome is either an exact match or disambiguation candidates. There are no explicit exclusions or pointers to the bulk/autocomplete alternatives, which keeps it from a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds the meaningful extras: batching is optimised server-side and capped at 100, and target_court enriches each result with binding/persuasive status. It is silent on partial-failure behavior — what happens if some citations don't resolve — which matters for a bulk call.

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 routing rule is front-loaded in the first two sentences and the Args block is compact. The 100-item limit is restated in the Args section, a small redundancy, but otherwise every line 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?

With annotations covering the safety profile and an output schema covering return values, the description only needs to explain scope and parameters, which it does. The one gap is error/partial-success semantics on a 100-item batch, which an agent would want before firing off a large request.

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 carries the full burden and does reasonably well: it specifies citations is a list capped at 100 and that target_court is optional and changes the output by adding binding/persuasive status. It does not state the expected court-code format (the sibling list_courts implies one exists), leaving that to inference.

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 ('Resolve multiple legal citations in one call') and immediately frames the batch scope. Combined with the explicit contrast to the sibling resolve_citation, an agent can distinguish it from every other tool in the list without opening a schema.

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

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

Gives a concrete when-to-use rule ('when you have a document with many citations') and names the alternative it replaces (repeated resolve_citation calls). The 100-item ceiling also tells the agent when this tool stops being sufficient.

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

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

Annotations already cover read-only safety and closed-world scope. The description adds valuable behavioral context beyond them: results are ranked by relevance with citation counts, mode may fall back from semantic/hybrid to keyword, and the response 'mode' reports what actually ran. It doesn't cover pagination or rate limits, so not a 5.

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

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

Front-loads purpose and the key corpus limitation before the args list. The args block is long but each entry earns its place given 15 parameters and zero schema descriptions; some entries could be compressed slightly but none are 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 15-parameter search tool with no output schema, the description is nearly complete: it explains result ranking, citation counts, mode behavior, and the corpus limitation. Minor gaps such as pagination or exact result shape are acceptable since no output schema exists and the core return semantics are stated.

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 compensate, and it does: every one of the 15 parameters is documented with type, meaning, and examples, including substring-match behavior, multi-select topics, enum-like values for disposition/judgment_status/jurisdiction, and mode fallback semantics.

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

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

States a specific verb and resource ('Search UK case law — judgments and tribunal decisions') and explicitly distinguishes the searchable corpus from legislation/procedural rules, naming the sibling resolve_citation for those. An agent can tell it apart from the other search/extract tools without opening schemas.

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

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

Says explicitly when to use it (topic, party name, legal concept) and when not to (legislation and procedural rules are not searchable). It names the alternative resolve_citation for statutes/rules, giving clear routing 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 and openWorldHint=false, so safety is covered; the description adds genuine behavioral detail, notably that semantic mode silently falls back to keyword when the embedding model is unavailable and that the response's 'mode' field reports which ran. That fallback disclosure is exactly the kind of surprise an agent needs warned about. It stops short of describing the shape of returned paragraphs or how limit interacts with total result counts.

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 sibling differentiation are front-loaded in the first two short paragraphs, followed by an Args block that is dense but earns its space given 0% schema coverage. The per-parameter list is longer than ideal but every line adds information not present in the schema.

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

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

For a 10-parameter read-only search with no output schema and only minimal annotations, the description covers every parameter, defaults, and the mode fallback behavior. It does not describe what a returned paragraph contains (fields, citation anchoring, ordering) or whether limit truncates silently, which leaves a modest gap for a tool whose whole purpose is extracting quotable text.

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 carries the full load and does so well: it explains term with examples, gives the exact allowed disposition values (allow, dismiss, grant, quash, refuse, remit) and jurisdiction strings that are not enums in the schema, and documents topic as a multi-select list with slug examples. Gaps remain for court (no code format, and list_courts exists as a sibling) and domain (no slug example), so it is not fully self-sufficient.

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 gives a specific verb (Find) and resource (specific paragraphs across cases) with the subject matter constraint (discuss a legal concept). It explicitly contrasts with the sibling search_cases by naming case-level vs paragraph-level results, so an agent can pick between them 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?

It states the positive condition plainly — 'Use when you need quotes or specific language from judgments' — and names the alternative (search_cases) together with the reason to prefer this tool over it. Nothing about tool selection is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds the ranking signal (citation counts) and the default limit of 20, which are behavioral facts not in the annotations. It omits anything about ordering ties or result shape, but an output schema exists to cover returns.

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 purpose sentence, then ranking semantics, then a compact Args block. The per-parameter type labels ('Domain slug', 'Optional court filter') partially restate the schema, but the parenthetical examples earn their space.

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?

A read-only, three-parameter ranked-query tool with an output schema; the description covers purpose, ranking basis, and all three arguments. Only edge-case behavior (empty domain, invalid court code, pagination beyond limit) is unaddressed.

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 carries the full burden and mostly does: domain_slug gets two concrete examples, court gets example codes ('UKSC', 'EWCA-Civil'), and limit states its default. What is missing is any hint of valid slug formats or what an invalid court code does.

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 ('Get the most-cited authorities in a legal domain') and adds the ranking basis ('Ranked by how many other cases cite them'), which distinguishes it from generic search siblings. It does not name a specific alternative like search_cases or get_related_authorities, so differentiation is inferred rather than stated.

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?

'Use this to find the leading cases, statutes, or rules in an area of law' gives a positive use case but no exclusion or comparison against search_cases, get_related_authorities, or browse_taxonomy. An agent knows roughly when it applies but not when to prefer a sibling.

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

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

Annotations only declare safety flags, so the description carries the real burden and does well: it discloses the internal extraction+resolution behavior and that target_court adds binding/persuasive status per citation. It does not address the mild tension with readOnlyHint=false — the tool reads as purely analytical yet is flagged non-read-only — nor any latency/cost characteristics.

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

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

Purpose and the anti-pattern routing come first, then a tight Args block. Every sentence adds information; there is no restatement of the name or title.

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 both parameters are covered with semantics. What remains unstated is the corpus scope and behavior on unparseable text, but 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 0%, so the description must compensate, and it does: it explains text as the document body containing citations and documents target_court with concrete example codes ('EWCC', 'EWHC-Ch') plus its downstream effect on the report. Minor gap: no format rules or fallback behavior when target_court is omitted.

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 ('validate all legal citations in a document') and spells out the full pipeline: extract every citation, resolve each against the corpus, return a structured validation report. It explicitly distinguishes itself from extract_citations and resolve_citation, so an agent can route correctly without opening any 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 concrete usage context ('skeleton argument, witness statement, or any legal document') and names the alternative pattern it replaces ('more efficient than calling extract_citations + resolve_citation in a loop'). It lacks an explicit when-not-to-use clause (e.g. single-citation lookups, large corpora), which keeps it short of a 5.

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