Syfert Legal Research

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

Annotations already declare a safe, idempotent read operation, yet the description adds substantial behavioral context beyond them: truncation caps (128KB anonymous / 512KB with token) with stats.truncated_bytes and an INCOMPLETE AUDIT flag, the full verdict taxonomy, and how unresolved cites should be interpreted. This is far more than the annotations supply.

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 a single paragraph of roughly 600 words with no bullets or breaks, so it is neither front-loaded nor easily scannable. While much of the content is non-redundant, the volume and run-on structure impose real parsing cost on the 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?

There is no output schema, so the description carries the full burden of describing returns, and it does so exhaustively: corrections, verdict taxonomy, statutes section, citability, cited_for, treatment flags, and currency fields. Nothing essential for correct invocation appears missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches parameter meaning well beyond the schema: it explains mode=attack as treating text as the opponent's brief, and gives concrete forum examples ('ca9', 'fl') plus the behavioral effect of omitting it. max_cites semantics are left 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 opening sentence states a specific verb and resource ('Audit ALL citations in a draft brief, motion, or memo at once') and immediately distinguishes itself from siblings by naming the wrapper and the batch scope versus check_citation/verify_quote. An agent can tell this audits an entire document rather than one 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?

It gives explicit when-to-use ('ALWAYS run this on a finished draft before delivering it'), an alternative mode for the opposite use case ('Use mode=attack on an OPPONENT's brief'), and routes specific sub-cases to siblings ('check it with verify_quote', 'check_citation or get_statute with as_of'). This is unusually complete guidance.

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

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

The description adds extensive behavioral context beyond the annotations: verdict semantics, live re-checks against CourtListener, fabricated_citers handling, status warnings for repealed or omitted statutes, and treatment flags. This is far more than the readOnlyHint and idempotentHint annotations provide.

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

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

The description is front-loaded with the core purpose and uses all-caps section labels for structure. However, it is extremely long and dense, with numerous parenthetical edge cases, which 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?

Given the tool's complexity, the 10-parameter schema, and the absence of an output schema, the description is highly complete. It explains not only what the tool does but also how to interpret the nuanced verdicts and status blocks an agent will receive.

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 meaningfully adds interpretation for parameters such as expected_case_name, proposition, as_of, quote, sentence, and quotation. It explains how those inputs change the returned analysis rather than merely restating schema text.

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

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

The description opens with a specific verb and resource: 'Verify a legal citation actually exists before using it.' It clearly scopes the tool across cases, statutes, regulations, court rules, short forms, and public-domain cites, which distinguishes it from a generic case lookup.

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 strong usage direction, including 'ALWAYS use this to verify any citation that will appear in a legal document' and detailed guidance on interpreting verdicts. However, it does not explicitly route the agent to sibling tools such as verify_quote or get_case when those would be more appropriate.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses how windows are produced ('placed by word overlap'), that the judgement is deliberately left to the caller ('The windows are placed by word overlap; the judgement is yours'), the rough window size (~2,500 chars, configurable), and the 12-cite batch limit. This is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with the core question, then when to call, then inputs, then return shape, then scope and batch limits — a logical order with no filler sentences. It is a single dense paragraph, so the length is justified by information density but not maximally skimmable.

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 return contract (case identity fields, two windows, overlap scores, the judgement enum) and adds the constraints an agent needs — verdict is the caller's responsibility, case opinions only, 12-cite cap. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: the citation must be a reporter cite with its first page or a cluster_id, cluster_id is 'the cluster_id check_brief resolved the cite to', and a pin embedded inside the citation is also read. It restates max_chars defaults already in the schema, so it does not fully escape redundancy.

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 question, 'Does the cited case actually say what the brief says it says?', states the specific job in one line, and the return description (pinned_window, best_window, overlap scores, a supported/overstated/unsupported/cannot_tell instruction) makes the pin-cite-against-sentence check unmistakable. It is clearly separable from verify_quote (exact quote matching) and check_citation (citation validity), and explicitly carves out scope with 'Case opinions only (statutes and rules are out of scope).'

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 triggering rule: 'Call it after check_brief for every cite you rely on whose support_check says available, or for any sentence you want to test against the case it cites' — names the prerequisite tool, the field to consult, and the fallback condition. Scope exclusions are stated (statutes and rules out of scope) and the batch ceiling ('Up to 12 cites in one call with items') tells the agent when to batch.

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

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

Adds real behavioral context beyond the annotations: the MCP cannot write to disk so persistence is the caller's job, and long documents are paginated via truncated/next_offset requiring ordered appending. The readOnly/idempotent/non-destructive profile is already fully covered by annotations, so no contradiction and no redundancy penalty, but permissions or rate-limit behavior is left unstated.

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 key routing decision ('Optional. If your client can save files locally...') and nearly every clause carries information. It is a dense single block with several ideas packed together, which slightly hurts scannability, but there is little 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 carries the return contract itself (filename, format, bytes, document, note) plus the pagination protocol and the no-disk-write caveat. For a 7-parameter tool with 0 required params, an agent has 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 description coverage is 100%, so baseline is 3; the description goes further by explaining parameter interaction (citation used when cluster_id is absent, case_name to resolve citations newer than the reporter index, jurisdiction required for statutes/rules) and the append-in-order rule for offset.

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 (export/save a readable copy of a case or statute) and explicitly positions itself against siblings: 'otherwise use get_case / get_statute as before'. The description also enumerates exactly what the exported artifact contains (caption, headings, footnotes, star-page markers, links).

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?

Opens with the selection condition ('If your client can save files locally and you want a readable copy') and the negative case ('otherwise use get_case / get_statute as before'). It also gives per-resource invocation routes (cluster_id or citation for cases; jurisdiction + citation for statutes) so the agent knows which sibling semantics to mirror.

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 safety profile (readOnly, idempotent, closed-world); the description adds substantial behavior the annotations cannot express: match_kind semantics (exact_phrase/relaxed/proposition/quotation/cited_for_label), the no_close_authority flag, closeness tiers, semantic_case lead rows, and that exact-phrase matches survive state filtering.

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 the verbatim rule, and most sentences carry real output semantics, but it is a single ~350-word wall of text covering many match kinds without structural separation (no bullets/headers), making it hard to scan. The volume is defensible given no output schema, but the presentation is dense.

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 full burden of explaining returns and does so thoroughly: source_case, quoted_by_cases, match_kind variants, string_cite, semantic_case rows, match_sentence, closeness, and the no_close_authority signal, plus fallback actions on a miss.

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 baseline is 3, but the description adds a genuinely operative instruction the schema lacks: paste the proposition VERBATIM and do not convert it to keywords. The state parameter's scoping is documented in the schema itself, so the description's contribution is the verbatim-input rule.

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 ('Find the case to cite for a proposition') and immediately distinguishes itself from siblings find_issues and search_cases via explicit routing rules. An agent can tell exactly what class of input this tool consumes (verbatim propositions/quotes) versus its alternatives.

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

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

Gives explicit when-to-use and when-not-to-use guidance with named alternatives: proposition/quoted language -> find_authority, doctrine/fact pattern -> find_issues, party name/statute/keywords -> search_cases. It also covers the miss case and the pasted-vs-typed-quote distinction (verify_quote for quotes from memory).

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 read-only, idempotent, non-destructive behavior, but the description adds substantial rules: name_mismatch and ambiguous_docket problems, candidate ordering, fuzzy caption suggestions, treatment flags, database_caution, and exact-caption precedence. It also discloses failure modes and return fields beyond what annotations provide.

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

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

The opening is front-loaded with the core purpose and alternative tool, and nearly every sentence is substantive. However, the description is an extremely long, dense single paragraph mixing citation, caption, docket, fuzzy-match, and short-form rules, making it harder to scan than necessary for an agent choosing and invoking 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?

Given a complex seven-parameter lookup with no output schema, the description covers query types, decisive versus non-decisive outcomes, return fields such as case, kind, candidates, and treatment_flag, and edge cases like short forms and fuzzy captions. It provides enough detail for correct invocation and interpretation of 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?

Although schema coverage is 100%, the description adds meaning well beyond the schema: expected_case_name triggers a non-decisive name_mismatch, year and quotation break ties but never override resolving citations, court takes precedence over state, and sentence binds id./ibid./supra to the prior citation in the sentence. These are invocation rules the schema does not fully capture.

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: direct lookup of one case by citation, caption, or docket number, returning the case or candidates. It explicitly distinguishes this from search_cases, which is for topics and words, so an agent can tell the two apart immediately.

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 says to use search_cases for topics and words, and lays out when find_case is appropriate: citations, captions, and docket numbers. It also explains when an answer is decisive versus not decisive for each query type, giving clear routing and outcome 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds value beyond that by disclosing the shape of the response — court_groups aggregate tokens, per-row bluebook abbreviations, and citation_string — which matters because there is no output schema. It stops short of describing no-match behavior or whether results are a list.

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 resolve-to-id purpose, then the group behavior, then per-row field meanings. The long Bluebook parenthetical is informative but slightly over-extended for a single field.

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

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

For a one-parameter read-only lookup with no output schema, the description covers purpose, call-site routing, group semantics, and the meaning of every returned field. An agent has enough to call it correctly and to interpret the result without further docs.

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 name parameter's examples (Florida, Eleventh Circuit, Navajo Nation, tribal courts, veterans, bankruptcy) already appear in the schema. The description adds the semantic consequence — that group names collapse to a single aggregate token in court_groups — but no syntax or matching-rule details (fuzzy vs exact, partial names).

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 (court name → court_id), and explicitly ties the output to the search_cases court filter, which separates it from siblings like find_case or search_cases. It also pre-empts a likely misconception by covering whole-group resolution in the same sentence.

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 opening sentence gives clear context for when to reach for it: before filtering cases by court, resolve the name first. It names the downstream consumer (search_cases court filter) but offers no explicit exclusion or 'use X instead when…' guidance versus the other find_* 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?

Annotations already cover read-only/idempotent/openWorld=false, and the description adds a great deal beyond them: the default result size (3 issues, 5 statutes, ~12,000 characters), that issues_omitted counts the remainder, that detail=true/ max_issues expands output, that q over 8 substantive words is reinterpreted as a proposition, and the caveat that 'doctrine name is not case health' with a warning to read questioned_by before relying on followed_by.

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 entry cue and the return contents, and every sentence carries operational information, but the middle is a dense run-on that mixes return-value detail, caveats, size defaults and routing in one block. Slightly sprawling, though nothing is truly wasted.

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

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

For a 5-parameter, no-output-schema research tool, the description is unusually complete: it explains what comes back, how big the default answer is, how to expand it, how q length shifts interpretation, how to browse the tree, and how to route away from it. An agent has 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 100%, so the baseline is 3, but the description earns extra: it tells the agent that q is the doctrine as 'a lawyer would name it' in 2-6 words, that the >8-word threshold changes interpretation, that node browses the tree instead of searching, and that state accepts 'fed'/'us'/'federal' as one jurisdiction and triggers federal-bucket results for federal questions.

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 'ENTRY BY ISSUE' and a concrete statement of what is returned: the doctrine as courts in a state actually name it, cases on each side (followed_by / questioned_by), example sentences, statutes, per-state span, and matching mined propositions. It explicitly distinguishes itself from siblings via a routing block (find_authority, search_cases), so an agent can select it without opening other 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?

Gives explicit when-to-use ('Use this FIRST when the question arrives as facts or an issue rather than a case name') and names the alternative tools with the conditions that select them: proposition or quoted language -> find_authority, doctrine name or fact pattern -> find_issues, party name/statute number/keywords -> search_cases. It also prescribes node-based browsing as an alternative to q.

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). The description adds substantive context beyond that: the curated corpus size, that only landmark cases qualify, and the degraded fallback mode that returns co-cited cases with related_source "co_citation". It does not describe pagination or result volume directly, keeping it from 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?

The purpose and the primary usage rule are front-loaded in the first two sentences, and the fallback behavior is appended where it belongs. The trailing version tag (MCP22_20260927) is noise that costs a little efficiency.

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

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

With no output schema, the description carries the burden of explaining returns and it does name the key returned concept (the doctrinal family) plus a notable result field (related_source "co_citation"). Combined with full schema coverage of inputs, this is nearly complete; only result volume/paging behavior is left unstated.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema (including the case_name name+date resolution note and the max_cases default/max). The description adds no parameter-level syntax or format detail over 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?

The description names a specific verb (expand/return) and resource (the doctrinal family of co-cited cases around an anchor authority) and bounds the scope precisely (curated ~1,500 major doctrinal lines, landmark cases only). That is enough to separate it from siblings like get_citing_cases or get_treatment without opening 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 gives explicit when-to-use guidance: "Use when you have one on-point case and need the rest of the line." It also describes the fallback path for a case with no family. It does not explicitly exclude or name alternative siblings (e.g. get_citing_cases), so it falls just 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 establish readOnly, idempotent, non-destructive behavior, and the description adds substantial extra disclosure: pagination defaults (40000/150000), cited_by aggregation across twin clusters with a survivor response for duplicate/stub ids, embedded citation warnings, focus_miss semantics, and pin making the pinned page the first passage. These are behavioral traits the 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?

It is front-loaded with the core fetch and has almost no filler, but it is a single dense paragraph of roughly 300 words with many parenthetical asides, making it hard to scan. The content earns its place; the structure does not.

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

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

There is no output schema, so the description must carry return-shape disclosure, and it does: metadata, parallel citations, treatment flag, embedded_citations, citation_warnings, focus_passages with page/offset/score/part, focus_miss, and quotable_passages. An agent can predict the response and choose the right parameter combination without further documentation.

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 per-parameter baseline is 3, but the description adds cross-parameter meaning the schema does not: citation is used only when cluster_id is absent, focus suppresses opinion text unless include_text=true, pin alters the first focus passage's source, and find_text can run with include_text=false. That interaction logic is genuine value beyond the field-level descriptions.

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

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

The opening sentence gives a specific verb and enumerates the record's contents ('metadata, parallel citations, treatment flag, and full opinion text'), so the agent knows exactly what a call returns. It implicitly contrasts with search_cases by scoping to 'one case' and sourcing cluster_id there, but never explicitly distinguishes get_case from the sibling find_case, which also resolves by name/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?

Offers concrete routing for several branches: use find_text instead of paging a long opinion, pass include_text=false when only passages are wanted, run verify_quote for memory-typed quotes, and run check_brief on the finished draft. It still gives no explicit statement of when to use get_case over find_case, and the alternatives it names are for adjacent tasks rather than for the fetch itself.

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, so the safety profile is covered. The description goes further by revealing the shape of the result (parentheticals written by judges, verbatim quotes, pin cites, signals) and the important limitation that only top-ranked ~50 citers are included. Pagination/ordering beyond that is not spelled out, keeping it short of 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 dense sentences with the payload description front-loaded and the sibling routing plus coverage caveat trailing. Every clause carries information; none is filler.

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

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

There is no output schema, so the description must describe returns, and it does so thoroughly (signals, quotes, pin cites, parentheticals plus flag colors). Combined with the stated citer-coverage limit, an agent has everything needed to call it and interpret results.

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

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

Schema description coverage is 100%, so the schema already documents citation, case_name, cluster_id, max_citers, and flag_filter. The description only reinforces the flag-color filtering, adding no syntax or resolution detail beyond the schema, which matches the baseline-3 rule when structured fields do the heavy lifting.

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

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

States a specific verb and resource ('Full citator list: every ranked case citing this one') and enumerates the exact payload (parentheticals, verbatim quotes, pin cites, Bluebook signals). It is clearly distinguishable from get_treatment, which is named as the sibling for a different job.

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 when to use it ('Best for FINDING SUPPORTING AUTHORITY and parentheticals') and when not to ('for comprehensive negative-treatment checking use get_treatment'). It also discloses the coverage boundary (only each case's ~50 top-ranked citers), which is exactly the kind of routing caveat an agent needs.

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 safety (readOnlyHint, idempotentHint, destructiveHint false). The description adds substantial behavioral detail beyond that: what the output contains (distinct propositions each with own treatment flag and counts), the meaning of a null passage, the proposition parameter's return fields (proposition_match, proposition_note), and the quotation-mark convention for pasted text.

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 question and purpose, but the final three sentences about quotation marks, verify_quote, and check_brief are tangential workflow instructions that inflate length. Most sentences carry useful detail, but the structure could be tighter and more scannable.

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

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

With no output schema, the description must explain return values; it does so for propositions, treatment flags, passage, and proposition_match/proposition_note. It covers the main use case and key outputs, but omits max_propositions behavior and the full response shape. Adequate for a read-only lookup tool whose annotations already cover safety.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema for the 'proposition' parameter by explaining it is 'your use of the case' and triggers proposition_match/proposition_note. It also clarifies 'passage' as an output field, though citation, case_name, cluster_id, and max_propositions receive no additional elaboration.

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 ('Returns') and resource ('distinct legal propositions courts cite the case for') plus key attributes (headnote-grade, own treatment flag and counts). The phrase 'A case can be good law on one proposition and overruled on another' clearly distinguishes this tool's proposition-level granularity from sibling get_treatment, which likely gives case-level 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?

Explicitly says when to use it: 'Use before citing a case for a specific point, and to find the strongest proposition to cite it for.' It also cross-references verify_quote and check_brief for adjacent workflow steps. However, it does not name a when-not scenario or an alternative tool that performs the same job.

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 the description adds substantial behavior beyond them: exactly which fields every answer carries, that temporal_warning or status_warning leads the response, and the full status taxonomy (current | sunset | future | expired | repealed | renumbered, plus omitted/removed/former_appendix cases) with what each returns. This is unusually rich disclosure of return-time behavior for a read tool.

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

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

Information-dense and front-loaded with purpose, currency fields, then operative-date handling, but it is one long undelimited block and the tail (omitted U.S. Code sections, CFR removals, former appendix handling) is verbose relative to what an agent needs to select and call the tool. Much earns its place, but structure and length could be tightened.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so thoroughly (currency field list, temporal_warning/status_warning precedence, successor/prior text availability). For a temporally complex corpus this is complete enough for an agent to interpret 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?

Schema description coverage is 100%, so the schema already documents all five parameters in depth, including as_of semantics, citation formats, and jurisdiction corpora. The description restates and emphasizes as_of usage but adds little syntax or format detail the schema does not already supply, 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: 'Fetch the full text of a statute, rule, or code section,' and names the scope ('the current codification in the edition this corpus holds'). This cleanly separates it from siblings like search_statutes (discovery) and get_case (case law) without needing to open 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 strong conditional usage guidance: for a crime, contract, limitations period or procedural step, establish the operative date first and pass it as as_of, and say so when the text postdates the facts. It explains the consequences of passing as_of vs not. It stops short of routing among siblings (e.g., no pointer to search_statutes for finding a citation first), so it is clear context rather than full when/when-not/alternatives.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond them: the meaning of each flag color, the presence and semantics of flag_reason, flag_basis (with enumerated bases), flag_evidence, proposition_note, and ambiguous_citation/candidates handling. It also quantifies the compact tradeoff (~90% smaller, ~2-4 KB vs 20-50 KB), which is exactly the kind of operational context annotations can't convey.

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 answer ('Is this case still good law?' and the flag set) and every sentence carries substantive information. It is dense with nested parentheticals and long compound sentences, so a reader must work harder than ideal, but there is little true waste.

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?

No output schema exists, so the description carries the full burden of explaining return values — and it does: flag colors, citing-case rows, proposition-level matches, flag_reason/flag_basis/flag_evidence, compact mode contents, and the ambiguous-citation response shape. For a six-parameter, branching tool, an agent has enough 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%, so the baseline is 3, but the description adds real meaning: compact=true is explained in terms of what survives (flag, scope, overruled_by, top negative citers), proposition is explained in terms of the proposition_match/proposition_note outputs it triggers, and the ambiguous-citation path clarifies how case_name and cluster_id interact. The citation-vs-cluster_id precedence is left mostly to the schema, keeping it from a 5.

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

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

States a specific verb and resource: returns the citator treatment flag (red/yellow/green/procedural) for a case plus the citing cases and quoted context behind each signal. The scope is unmistakable and distinguishable from sibling tools like get_citing_cases (raw citers) or get_case (full text), since the description centers on the treatment verdict and its evidentiary basis.

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 guidance: use proposition when the case-level flag is green but your specific use may be red, and pass case_name/cluster_id when ambiguous_citation=true. It doesn't explicitly name when to prefer a sibling tool (e.g., get_citing_cases) or state exclusions, so it stops short of a full when/when-not/alternatives 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, so the safety profile is covered, yet the description adds substantial behavioral detail beyond them: null totals under filters, total_pages/total_note, partial_note on timeout, tier/_source backend, relaxed=true with kept/dropped terms, and semantic_fallback on empty text searches. This is rich response-shape disclosure the annotations do not carry.

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

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

Front-loads the purpose and routing before diving into response nuances, and nearly every sentence conveys non-obvious behavior for a 12-param tool. However, it is a single dense run-on paragraph whose length and inline notation (e.g. 'relaxed_terms_kept / relaxed_terms_dropped') make it harder to scan than it needs to be.

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

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

With no output schema, 12 parameters, and complex query modes, the description fully compensates by explaining returned fields (bluebook, url, snippet, passage_origin, direct_hit, matched_by, similarity), pagination/total behavior, and fallback modes. Nothing an agent needs to call or 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 baseline is 3, but the description meaningfully enriches q with full query syntax (boolean, phrases, proximity, wildcards, name:/judge:/syllabus: filters) and explains semantic-mode ranking and its interaction with filters. It stops short of clarifying a few filters (e.g. how judge/status interact), so it edges above baseline rather than maxing 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?

Opens with a specific verb+resource+scale: 'Full-text search over 10.7M U.S. court opinions (all states + federal)'. It then explicitly distinguishes itself from siblings find_authority, find_issues, and find_case with a routing rule, so an agent can pick the right tool without opening other 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?

Provides explicit routing: 'a proposition or quoted language -> find_authority; a doctrine name or fact pattern -> find_issues; a party name, statute number or keywords -> search_cases.' It also notes find_case performs only the single-caption lookup, giving clear when-to-use and when-not-to-use 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 only say read-only/idempotent, but the description adds substantial behavior: the relaxed fallback when no exact phrase exists, the proposition match kind, the ranked-by-adoption ordering, and the returned fields (passage, source case, adoption counts). It also notes first-3-rows carry star_page and cite_as.

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

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

The core purpose and fallback behavior are front-loaded well, but the text is dense and blends in tangential cross-tool workflow (verify_quote, check_brief, 'copy cite_as', 'quotation marks mean pasted') that dilutes focus on this tool's own 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 search with no output schema, the description supplies the return shape, the two fallback modes, ranking semantics, and routing, leaving nothing an agent needs in order to call it correctly or interpret results.

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

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

Schema description coverage is 100%, so the schema already documents both the quote ('three or more words, matched as a phrase') and state parameters, including the verbatim-vs-relaxed state scoping. The description adds no syntax or format detail beyond that, so 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 verb and resource ('find every case that has quoted a phrase') with concrete scope (4.3M passages, ranked by adoption count). The routing rules explicitly distinguish it from find_authority, find_issues, and search_cases, so an agent can place it among its 16 siblings.

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

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

Gives explicit when-to-use cases ((a) sourcing half-remembered language, (b) locating canonical rule wording) plus a full routing block mapping proposition/quoted-language, doctrine/fact-pattern, and party/statute inputs to three different sibling tools. It also names follow-ups (verify_quote, check_brief).

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, closed-world, non-destructive, so the safety profile is covered. The description adds real value beyond that: result fields (text_last_changed, last_amended_year, effective_date, status, successor), corpus_currency, and the operative-date caveat that text is the held edition rather than the law on every date. However, it does not describe result ordering, pagination beyond limit, or how source coverage is surfaced in the response, so it stops short of full behavioral disclosure.

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

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

Core purpose and the state/kind routing are front-loaded, and every sentence carries actionable content. It is somewhat dense and leans on all-caps emphasis plus a long parenthetical, but the length is justified by the multi-jurisdiction behavior it must convey.

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 five-parameter search tool with no output schema, the description covers defaults, jurisdiction resolution, result currency fields, and the operative-date pitfall. Nothing essential for correct invocation or result interpretation 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 baseline is 3, but the description adds meaning on top of it: examples of state codes, the rule/statute semantics of kind, the conditional use of kinds, and citation-vs-topic query examples. It also clarifies that as_of belongs to get_statute/check_citation rather than this tool, which prevents a common misuse.

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 (Search) and resource (statutes, court rules, codes) with explicit scope (every U.S. state + federal). It is clearly distinguishable from siblings like search_cases, find_authority, and get_statute, which retrieve other document types or a single known provision.

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

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

Gives explicit when-to-use routing: pass state for one jurisdiction, kind to scope to rule vs statute, kinds only when state is absent, and the default is Florida-only. It also names alternatives for the as_of workflow (get_statute, check_citation), so the agent knows where operative-date lookups belong.

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: it clarifies that the suggestion does not change the live flag, that a proposal equal to the live flag is not recorded, what is returned (current flag and what was recorded), and exactly what is or is not logged (case id, flag, reason, authority, date; no session, user, query or document data). That data-retention and no-op disclosure is precisely the 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?

Purpose and trigger lead, and the dense constraint sentences each carry weight. Minor bloat remains in the closing promotional sentence about helping syfert.com improve its flags, which adds no invocation guidance.

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 write-ish, 6-parameter tool with no output schema, the description covers identity paths, allowed values, reason format and length limits, return contents, and the no-op/equality edge case. An agent has 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?

With 100% schema description coverage the baseline is 3, but the description adds real meaning: identity may be supplied either by cluster_id or by citation with an optional case_name cross-check, and it restates the red/green enum restriction in plain language. The authority field's role (the case or statute the reason relies on) is also framed functionally.

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 (propose/suggest) and resource (a red/green treatment flag correction) with the exact evidence trigger for it. It is clearly distinguishable from read-side siblings like get_treatment, check_citation and get_citing_cases.

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

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

Gives explicit when-to-use conditions (an overruling, abrogating or reinstating opinion, or a later holding that the case is still good law) plus hard exclusions (only red or green, never yellow; the reason must concern legal status only, never the user's facts, question, client or document). Nothing about selecting this tool 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 readOnly/idempotent/non-destructive, so the safety profile is covered; the description goes further by enumerating the return fields (verdict, percent, best_match, star_page, offset, case, advice) and interpreting the verdict enum. However, 'percent' is never explained, so a key piece of returned behavior is left ambiguous.

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

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

The core check is front-loaded in the first sentence, then return values, then case identification, so scanning order is sensible. It is dense and mixes in agent-workflow rules (quotation-mark conventions, running check_brief) that make it longer than strictly needed, though each rule is actionable.

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 mostly does so, including how to act on 'near' and 'absent'. Gaps remain: the meaning of 'percent' and the handling of quotes shorter than the schema's three-word minimum are unaddressed, which matters for a tool whose whole value is the verdict.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning by explaining how the case is identified — cluster_id or reporter citation, with case_name as the fallback for citations newer than the reporter index. That precedence rationale goes beyond the schema's terse per-field text.

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

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

The first sentence states a precise verb and resource — checking one quotation against the full text of the opinion it is attributed to — and scopes it with a trigger ('before it goes in quotation marks'). It is clearly distinguishable from siblings like search_quotes (finding quotes) and check_brief (draft-level review).

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 when-to-use rules ('before it goes in quotation marks', 'if you typed a quote from memory, run verify_quote and use best_match') and names the alternative workflow for text that was pasted from a tool result, plus a downstream routing instruction to check_brief. Alternatives and conditions are both stated.

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