Court Delta

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

The description goes beyond the readOnlyHint annotation by explaining that results are mined from the section's own history note, grouped by year, and include first-enacted year and total amendment count. It also clarifies that these are statutory dates from the legislature's record, not database update dates, which is important behavioral context.

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

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

The description is well-organized: purpose, usage examples, return summary, and sibling differentiation. The first sentence largely repeats the title, which is slightly redundant, but overall every paragraph earns its place and the most decision-relevant information 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?

For a one-parameter read-only tool with an output schema, the description covers why to use it, what it returns, how results are derived, and which alternatives to use in related scenarios. Nothing critical is missing for an agent to select and invoke it correctly.

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

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

The schema only has a 'citation' string with no description coverage, so the description must compensate. It gives an explicit example format, 'G.S. 14-33', and explains the resource is an NC statute section, which is helpful. It could be more explicit about accepted citation variants, but the example supplies enough guidance for a single-parameter tool.

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

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

The description clearly states the tool reports when an NC statute section was enacted and every time it was amended, with concrete example questions. It also differentiates itself from related tools such as recent_law_changes, get_statute, and diff_statute.

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 this tool for questions like 'how often has G.S. 14-33 changed' or 'when was this last amended', and tells the agent to use recent_law_changes for database-observed changes and get_statute/diff_statute for wording. This is 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 supply readOnlyHint=true, and the description complements this by clarifying that counts are 'STATUTORY, from history notes — not observations' and by enumerating the return categories. This adds behavioral context beyond the structured hints, though it does not discuss pagination or exact limit behavior.

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

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

The description is compact and front-loaded, with the core purpose in the first sentence. Every subsequent sentence earns its place: use case, return contents, chapter behavior, data provenance, and sibling alternatives. No filler or 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 read-only aggregation tool with an output schema and no required parameters, the description is largely complete: it states scope, output summary, data semantics, and alternatives. The only gap is that top and since_year are not explicitly described, but their meaning is reasonably inferable and defaults make the tool callable without them.

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 prose must explain parameters. It clearly explains chapter ('Omit chapter for a corpus-wide view') and links it to tool selection, but top and since_year are left to their names and defaults. The description partially compensates for the missing schema descriptions but not completely.

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 by defining the tool's purpose: measuring 'legislative churn' at the North Carolina statute chapter level, and specifies what is returned (amendment counts by year, most-amended sections, pending/repealed counts). It also separates itself from siblings by naming amendment_history and pending_changes as the tools for single-section and upcoming-text needs.

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

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

It gives a concrete use case ('which parts of Chapter 14 keep changing'), tells the caller to omit chapter for a corpus-wide view, and explicitly names alternatives: 'For one section use amendment_history; for upcoming text use pending_changes.' This is direct routing guidance with no reliance on 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?

The description goes well beyond the readOnlyHint/openWorldHint annotations: it states the assessment is deterministic, explains that severity 0 does NOT mean legitimate, discloses that a de-identified record is stored, clarifies that no name or phone number is collected, and explains how severity 1/2 should trigger ask_them_to_report. No contradiction with annotations: the storage is internal trend tracking and the tool remains non-destructive to user data.

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

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

The description is long but tightly packed with operational rules; it opens with the purpose and usage trigger, uses bold severity markers, and gives imperative handling instructions. A little redundancy exists (e.g., 'every field is optional' plus 'partial description still gets an assessment', and repeated 'never' cautions), but the length is justified by the safety-sensitive nature of scam triage.

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

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

The description covers all needed context for safe invocation: optionality, severity interpretation, the severity-0 false-all-clear hazard, case-number interplay with lookup_court_case, reporting channels, ask_them_to_report behavior, link formatting, data storage/privacy, and NC-only scope. Even though an output schema exists, the description adds essential decision logic around those outputs, making it complete for an agent to invoke and relay results responsibly.

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

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

With schema description coverage at 0%, the description compensates by explicitly listing accepted behavioral_flags, defining raw_description as free-form text used for assessment/category tags but not stored, and explaining that case_or_citation_number yields a pending status requiring lookup_court_case. Other parameters such as county and contact_channel are not individually described, though their enum/string values are self-explanatory and all fields are optional, so the remaining gap is modest.

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 line directly asks 'Is this court-payment demand a scam?' and the description begins with 'Assesses a contact someone received against known North Carolina (NC) court-scam patterns.' This names a specific verb, resource, and jurisdiction, and it clearly distinguishes this tool from siblings like lookup_court_case or search_cases_by_party by focusing on scam-pattern assessment rather than court record 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?

Gives an explicit trigger: 'Use this when someone describes being contacted about jury duty they missed, unpaid court costs, a warrant, or a bond — and being asked to pay.' It also states NC-only scope and instructs when to route to a sibling: 'Call lookup_court_case with that number to check whether it is real.' Combining two related tools is spelled out, and the warning that a real case number does NOT make the payment demand legitimate prevents misuse.

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 readOnlyHint and openWorldHint, so the description carries the behavioral burden and does so in depth: it discloses that the (a4) determination is the tool's single decision, that everything else merely routes, that determinable:false is not a 'no', that eligibility is person-level and unverifiable here, and that an (a4) expunction is not destruction. This is far beyond what the annotations 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?

The first sentence front-loads purpose and the regime/family sections are clearly delimited, so structure is deliberate rather than rambling. But the description runs to roughly a thousand words of all-caps imperatives with repeated ALWAYS/NEVER/DO NOT directives, which is well past the size an agent needs and dilutes the highest-priority instruction.

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, yet the description still supplies the interpretive meaning of the fields (regime, windowDeterminable, waiting dates, family, probationMatter, automaticExpunction) that the schema alone cannot convey. Given the legal nuance and the tool's narrow decision surface, nothing essential for correct invocation or correct phrasing of the answer is missing.

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

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

Schema description coverage is 0% across three parameters, so the description must compensate — and it only partly does. `caseNumber` is explained (omit it to get the whole statute table), but `felony` and `convictionCount` are never addressed: nothing tells the agent when to set felony or whether convictionCount feeds the 145.5(c) waiting-period arithmetic shown in the output. An agent must guess how two of the three inputs affect behaviour.

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

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

The opening line states a precise verb+resource: routing each charge's disposition to the NC expunction statute and AOC petition form, with links, venue and fee. It is immediately distinguishable from siblings like lookup_court_case or search_judgments, which retrieve records rather than map dispositions to statute/form. The 'call with no caseNumber to get the whole statute table' sentence further pins down what the tool returns.

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

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

Usage is exhaustively specified: check automaticExpunction first, do not lead with petition forms when it applies, treat probationMatter as an answer rather than a gap, abstain on unroutable reduces, and never present the tool as deciding eligibility. It also states the safe/unsafe answer boundary ('not yet eligible' is safe; 'eligible' never is), which is exactly the when-to-say-what guidance 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 readOnlyHint/openWorldHint, but the description adds rich behavioral context: that output is 'options with consequences, not a recommendation,' the mandatory-appearance cross-charge rule (viaCompanionCharge), FTA/order-for-arrest consequences, timing semantics ('lastDay', 'noCourtDate'), the pre-screen vs. verdict distinction for reductions, and speed-dependent classification. This is exceptional disclosure 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?

Long, but the length is justified by the tool's complexity and the high-stakes nature of the answer. Front-loaded with the core question, then organized into clear blocks (timing, statute, charges, speed, county, court_date, pre-screen caveats). Slightly overlong with some repetition (e.g., timing warnings appear multiple times).

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 complexity (cross-charge eligibility, state-specific timing rules, pre-screen semantics) and the fact that an output schema exists but the description still explains the meaning of key fields ('lastDay', 'noCourtDate', 'viaCompanionCharge', 'userMustConfirm'), the description is complete enough for an agent to invoke and interpret correctly. It even covers failure modes (unclassified charges, null citationOptions).

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%; the description fully compensates. It specifies that `statute` must be the G.S. number printed on the citation (with examples), that `offense` must be passed verbatim (with the school-bus/fictitious-plate rationale), that `court_date` must be the real date in YYYY-MM-DD and that omitting it silently loses `reductionSubmitBy`, that `county` decides the reduction path, and that `actual_speed`/`speed_limit` drive classification. Every parameter gets concrete semantics beyond the bare 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?

States a specific verb+resource ('check whether a NC traffic charge requires a court appearance') and names the sibling tool to use instead when a case number exists (lookup_court_case). The scope ('from the citation itself, BEFORE the case is searchable') sharply distinguishes it from the other tools.

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

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

Explicit routing: 'IF THE USER HAS A CASE NUMBER, USE lookup_court_case INSTEAD.' Plus explicit conditions for when this tool is appropriate (no case number yet) and when not (has a case number). Also distinguishes from court-portal tools via 'no court-portal request, unlike the other 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 declare readOnlyHint=true and openWorldHint=false, and the description adds context beyond those: 'Returns static text; makes no court-portal request' discloses that no network/portal interaction occurs, and 'Calling this first just delays their answer' reveals the latency tradeoff of misusing the tool. No contradiction with the annotations.

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

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

The description is front-loaded with the capability statement, then gives the call condition, then the exclusion with alternatives, then the behavioral note. Every one of the four sentences earns its place; the length is justified by the routing nuance needed across 15 sibling tools.

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 0 parameters, a readOnlyHint annotation, and an output schema already present, the description covers everything an agent needs: what it returns, when to call it, when to avoid it, what it does not do, and that no arguments are required. Nothing necessary 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?

The tool has 0 parameters, which warrants a baseline of 4. The description explicitly states 'Takes no arguments,' confirming to the agent that invocation requires no input and that the schema's empty object is intentional, not a schema omission.

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 the purpose with specific verbs and resource: 'what this Court Delta server covers, with example questions.' It clearly distinguishes the tool from its siblings by positioning it as the capabilities/help endpoint, explicitly naming lookup_court_case and search_cases_by_party as the tools to use instead for actual court queries. An agent can tell this apart from every sibling 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?

The description provides explicit when-to-use ('ONLY when the user asks what this server / connector can do, what data it has, or how to use it'), explicit when-not-to-use ('It is NOT a step toward answering a court question'), and names the alternatives with routing conditions ('skip this and call lookup_court_case / search_cases_by_party directly'). This is the model of usage 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 is exceptionally transparent about behavioral quirks beyond the annotations: it warns that multiple locations may be returned, hours include lunch closures, absent parkingAttributes do not mean 'no parking', and source fallback leaves hours empty. It also confirms the readOnlyHint ('Read-only') and openWorldHint ('ABSENT MEANS NOT CLAIMED'). No contradiction with annotations is present.

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

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

The description is long but deliberately structured with clear sections: purpose, disambiguation, hours, parking, accessibility, source fallback, and disclaimer. It is front-loaded with the core question it answers. Minor redundancy in the repeated warnings about not guessing between courthouses makes it slightly less concise than ideal.

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

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

For a tool with subtle real-world pitfalls, the description covers nearly everything an agent needs: return shape, multi-location handling, matching against hearing locations, lunch closures, parking semantics, accessibility semantics, source fallback behavior, and when to route to another tool. The output schema exists, so the description doesn't need to enumerate return fields; the behavioral caveats are what matter and they are thoroughly addressed.

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 parameter meaning. It does: it explains that `county` expects a value like 'Wake' and that `caseNumber` can be used to derive the county. The sole gap is that it doesn't discuss precedence or behavior when both parameters are supplied, and it doesn't give a caseNumber format example. Still, it compensates well for the schema's silence.

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 statement of what the tool provides: 'Which courthouse, where it is, when it's open, and where to park.' It also explicitly distinguishes itself from case-related tools: 'THIS IS LOCATION INFO, NOT CASE INFO.' This clearly separates it from siblings like lookup_court_case.

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

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

The description gives explicit when-to-use context: 'For "I have court on Tuesday — where do I go?"'. It names the alternative tool, lookup_court_case, for case info, and provides detailed disambiguation guidance involving upcomingHearings[].location. It even tells the agent when NOT to force a match and to show options instead.

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 the description adds meaningful context beyond that: it explains the OUTBOUND vs INBOUND distinction, the section-level granularity rule (20-141(j1) → edge to 20-141), and that chapter-wide references are excluded. This helps the agent understand what results to expect and what to avoid.

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 tightly written, front-loads the core purpose, and uses clear examples. Each sentence adds value: purpose, usage, direction semantics, granularity rule, and pointer to the sibling tool. No wasted words.

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

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

Given the tool's complexity and the presence of an output schema, the description covers the essential semantics well. It explains the direction model, the granularity rule, and when to use the sibling get_statute. However, it omits documentation for the 'limit' parameter and does not spell out direction value options, which are minor gaps given the clarity of the core function.

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 of documenting parameters. It conceptually explains direction (INBOUND/OUTBOUND) but does not enumerate the possible values for the 'direction' parameter or explain the 'limit' parameter. It also doesn't specify the citation format. Partial compensation, but gaps remain.

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 exactly what the tool does: lists statutes that a given NC statute cites (OUTBOUND) and those that cite it (INBOUND). It distinguishes itself from get_statute by explicitly directing text retrieval there, and the sibling list confirms this differentiation.

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 concrete example queries ('what does G.S. 14-72.1 depend on' or 'what else references it') and clarifies the two direction semantics. It also explicitly says 'For the text itself use get_statute', naming the alternative and the condition for choosing it.

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

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

Annotations only declare readOnlyHint=true and openWorldHint=false, but the description adds critical behavioral context: observed history begins at first ingest, most sections have only one version, and diff can be null. It also explains what mode='pending' actually compares. This goes well beyond the annotations.

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

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

The description is information-dense but well-organized: main purpose, mode explanations, then a clear limitation and alternatives. Every sentence adds distinct value, and the most important discriminator (mode behavior) 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?

The description covers the key behavioral modes, limitations, and sibling routing, and an output schema exists for return values. However, it omits practical invocation details such as how to write the citation and date parameters, which are not covered by the schema descriptions. Minor but real gap.

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

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

Schema description coverage is 0%, so the description must compensate. It explains mode semantics well and implies from_date/to_date with 'optionally between two dates', but it does not describe citation format, date format, or the format parameter. With five parameters and no schema descriptions, this is a meaningful 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 ('diff') and resource ('North Carolina statute section between two versions'), and immediately distinguishes the two modes. It also names sibling tools at the end, making the tool's role clear relative to amendment_history and pending_changes.

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 guidance for each mode: mode='pending' for enacted-but-not-yet-effective changes, mode='observed' for recorded versions. It also explicitly routes users to amendment_history for earlier dates and pending_changes for pending text, leaving no ambiguity about 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 only declare readOnlyHint and openWorldHint; the description adds substantial behavior beyond them — refusal rather than guessing for CDL/out-of-state, determinable:false abstention without speed_limit, the two PJC exceptions to a zero, the unmatched[]/viaCatchAll distinction, and the mandatory 30-day suspension that is separate from and additional to points.

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 (what it is, then the comparator framing) and uses caps to flag must-report items, but the text is very long and includes material tangential to invoking the tool — the limited driving privilege paragraph and the DWI-statute caution are output-narrative rather than call guidance. Much earns its place, yet the volume is heavier than needed to select and call the tool correctly.

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 still covers the behavioral edges an agent needs: refusals, abstentions, unmatched handling, catch-all vs unclassified charges, and the suspension/points distinction. Nothing needed 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?

With top-level schema description coverage at 0%, the description carries the full burden and does: it explains what priorPoints and recentlyReinstated feed (the two G.S. 20-16(a)(5) thresholds), what commercialLicense/outOfStateLicense trigger (refusal), and why actual_speed and speed_limit are jointly required for the suspension branch. This is meaning well beyond the bare schema types.

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 precise verb and resource ('Estimate driver's-licence points under G.S. 20-16(c)') and frames it sharply as 'a COMPARATOR, not a lookup', which tells the agent what the output means. It also distinguishes its scope from the insurance/SDIP system and from accumulated-point suspension. The one gap is that it never names or differentiates itself from the sibling check_traffic_charge, whose relationship to this tool is left ambiguous.

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 and when-not guidance: pass actual_speed for speeding charges or they land in unmatched, pass speed_limit or branch (i) cannot be assessed and the tool abstains, pass priorPoints/recentlyReinstated only if the user knows them. It also states the refusal conditions (commercialLicense/outOfStateLicense) and the limits (cannot determine first-conviction status, cannot assess SDIP premiums).

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses critical runtime behavior: slow cache-miss latency of 30–120 seconds due to CAPTCHAs, a 6-hour cache with `cached` and `fetched_at`, merged results on ambiguous name searches, and the difference between a successful empty result and an error. The annotations are not contradicted; they are substantially enriched.

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

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

The description is long, but every section earns its place: required argument combos, sibling differentiation, attribution caveats, latency warnings, cache semantics, and error handling are all high-stakes for correct invocation. The core question and most critical constraint are front-loaded, and the formatting makes the guidance 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?

Given the tool's complexity, the description is essentially complete: it covers argument requirements, defaults, output contents, attribution risks, performance expectations, caching, error handling, geographic scope, and public-record status. The output schema exists for return structure, so the description need not repeat it; nothing an agent needs to call this tool correctly is missing.

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

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

With 0% schema description coverage, the description carries the full parameter burden and does most of it well: `bar` OR both `first` and `last` is required, lone names and no-argument calls are rejected, and absent dates default to today. The main remaining gap is that the date format for `start`/`end` is never specified, which an agent would need to construct valid date strings.

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 the exact question the tool answers — an attorney's hearing calendar — and states the resource and accepted identifiers clearly. It also explicitly names its sibling `search_cases_by_attorney` and distinguishes the two, so an agent can tell them apart without inspecting 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 provides explicit routing: "THIS IS THE TOOL FOR 'TODAY', 'TOMORROW', 'THIS WEEK' AND 'MY CALENDAR'" and warns against substituting `search_cases_by_attorney`, explaining why that tool's file-date filters answer a different question. It also gives concrete decision guidance — prefer the bar number, read `attributable`, and never present an `error` result as an empty calendar.

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

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

Beyond the readOnlyHint annotation, the description discloses what the tool returns: catchline, body, history note, and first-enacted/last-amended dates. It also explains the non-obvious behavior of `as_of` (past text) and `pending` (variants enacted but not yet effective), which is exactly the kind of context that helps an agent use the tool correctly.

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

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

The description is dense but every sentence earns its place: definition, usage pattern, accepted inputs, return contents, temporal options, section-level constraint, and sibling routing. It is front-loaded and well organized, with no filler or repetition of schema defaults.

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 statute lookup tool with an output schema, this description is complete: it covers the exact use case, citation formats, temporal modes, return components, and when to choose sibling tools. The only minor gap, `max_chars` semantics, is mitigated by the schema's default value and does not prevent an agent from calling the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain `citation` with accepted spelling examples, `as_of` as past-date text, and `pending` as not-yet-effective variants. However, `max_chars` is not explained at all, even though its default of 12000 could affect the returned text and its interaction with the promised 'full text' is unclear.

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 specific verb and resource: 'Full text of one North Carolina (NC) General Statutes section, by citation.' It also differentiates itself from siblings such as amendment_history and diff_statute by explicitly saying when to use those instead, so an agent can distinguish the tool 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?

The description gives an explicit query pattern ('what does G.S. 14-72.1 say'), states the section-level limitation ('ask for "20-141", not "20-141(j1)"'), and names precise alternatives for related needs: amendment_history for WHEN it changed and diff_statute for WHAT changed.

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 mark readOnly and openWorld hints; the description goes far beyond by revealing defaults (yesterday, not today), partial-data risks for today's filings, the 200-case portal cap with truncation semantics, the 'server' county filter guarantee, and the finer-grained case_status values. This is substantial behavioral context that annotations alone could not 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?

The description is long but every section earns its place by preventing real misuses: defaults, prefix semantics, truncation handling, and empty-result interpretation. It is front-loaded with the core purpose and sibling differentiation, then organized with clear bold labels, making the length navigable rather than bloated.

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, output schema availability, and the many edge-case traps, the description is remarkably complete. It addresses required date-range limits, truncation, incompleteness prefixes, error handling, county exactness, and status reporting rules, leaving no critical operational gap for an agent selecting or invoking the 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 carries full weight for parameter meaning. It thoroughly explains date_start/date_end formats and semantics, case_type as a prefix rather than exact code, case_status granularity and prefix-matching requirement, and county_filter's 'server' special value. Only limit/offset lack explicit exposition, but their defaults and the portal-cap context make their role inferable.

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 leads with a specific verb and resource: 'What was FILED — every case of a given type in a county over a date range.' It immediately distinguishes itself from the sibling name-axis searches and provides concrete example questions, making it unmistakable which tool to invoke for docket-oriented lookups.

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

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

The description explicitly names alternatives: use search_cases_by_party/_business/_attorney when you know WHO, use get_attorney_hearing_calendar for today's hearings, and avoid lookup_court_case just for case status. It also clarifies when an empty result is a real answer versus an upstream failure, leaving no ambiguity about when to use this tool.

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

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

Annotations only say readOnlyHint/openWorldHint, but the description adds read-only semantics (no email sent, nothing saved, NC only, informational not legal advice), error-contract handling (`retryable`/`upstream_status` is a transport failure, not 'case not found'), liveness warnings (`portalSessionRef` lifetime unspecified and rotating; document retrieval unreliable), and null-reading rules across many fields. This is far beyond what the annotations carry.

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

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

The core lookup and identifier guidance is correctly front-loaded, but the description then runs to roughly 1500 words with deep dives into dozens of output fields, repeating rules in multiple places. Most statements are individually useful, yet the sheer volume and the number of caveats make it hard to scan; it is over-specified relative to what an agent needs to select and invoke 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?

An output schema exists, so return values need not be explained, yet the description still supplies the interpretive rules that the schema cannot (null = not applicable vs not found, deprecated alias handling, empty-list meanings). Nothing an agent needs to call this 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 carries the full burden, and it does: it defines each of the four parameters, gives format examples for `caseNumber` and `citation`, explains that `portalSessionRef` is short-lived and must not be persisted, and marks `caseHash` as a deprecated alias. None of the parameters is left ambiguous.

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 (look up) and resource (NC court case or traffic citation), and the next lines spell out the three accepted identifiers with examples. It also distinguishes itself from siblings by naming `search_cases_by_party` as the source of `portalSessionRef` and framing this tool as the follow-up to that search.

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

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

It explicitly ranks the identifiers: `caseNumber` is the STABLE canonical choice, `portalSessionRef` is an immediate-follow-up fast path, and `caseHash` is a deprecated alias. It also gives when-to-use context for the returned alert flow (ask, wait for yes, never call `subscribe_to_case_updates` on your own initiative), which is unusual and genuinely directive.

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?

With readOnlyHint=true, the annotation already covers safety. The description adds meaningful behavior: only future-dated variants are counted, a diff is returned by default, and AMENDMENT is distinguished from NEW SECTION with no diff. This goes beyond the annotations and reveals important non-obvious behavior.

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

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

The description is compact, front-loaded with the core purpose, and every sentence adds distinct value: purpose, return contents, amendment vs new section behavior, and alternative tools. No redundant or filler language.

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

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

Given the output schema exists and readOnlyHint covers safety, the description is strong on scope, behavior, and alternatives. The only significant gap is the lack of explicit parameter descriptions, which is especially relevant because the input schema provides none.

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?

Input schema has zero description coverage, so the description must compensate. However, it only tangentially mentions include_diff by saying 'by default a diff' and references Chapter 14, but it never explains limit, chapter, citation, or include_diff parameter intent. The 4 parameters are left essentially undocumented.

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

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

Description clearly identifies the tool as handling NC statute text already enacted but not yet effective. It specifies the verb/resource relationship by explaining that it returns current and future variants with effective dates and diffs, and it differentiates the purpose from related tools like get_statute and amendment_history.

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: 'Use for what changes to Chapter 14 are coming.' It also provides clear exclusions and alternatives: 'For text in force now use get_statute; for already-enacted history use amendment_history or recent_law_changes.' This gives an agent unambiguous 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?

The description goes well beyond the readOnlyHint annotation by explaining the two data sources, their distinct meanings, and the fact that the initial corpus load is excluded unless include_baseline=true. This is valuable behavioral detail that an agent could not infer from the schema or annotations alone.

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

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

The description is concise and well-structured: the core purpose is front-loaded, followed by essential source semantics, a baseline caveat, and a pointer to an alternative tool. Every sentence contributes useful information without unnecessary fluff.

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

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

For a tool with five parameters and multiple behavioral subtleties, the description covers the most important aspects: source kinds, baseline behavior, and sibling routing. However, it leaves the required 'since' format and 'chapter' semantics underspecified, which slightly reduces completeness for an agent preparing a valid call.

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 0% schema description coverage, the description must compensate for parameter explanations. It explains include_baseline and partially explains source and since, but it does not clarify the expected format for the required 'since' parameter or the meaning of 'chapter' and 'limit'. This is a noticeable gap in parameter guidance.

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

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

The description clearly states that this tool returns recently changed North Carolina statutes filtered by date or year. It also distinguishes itself from the sibling tool amendment_history by directing single-section queries there, leaving no ambiguity about its 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?

The description gives explicit usage context: STATUTORY is for legislative history such as 'what passed in 2025', while OBSERVED covers database-detected changes. It also explicitly says to use amendment_history for a single section, providing a clear alternative 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?

Beyond the readOnlyHint and openWorldHint annotations, the description adds substantial behavioral context: live portal searches with a shared upstream token, slow responses (~60s for 3 names, ~2 min for 5), partial batch failures with per-name errors, portal_truncated as a lower bound, exact matching with no soundex, and no identity confirmation. No statement contradicts the annotations.

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

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

The description is long but every section earns its place, covering limits, latency, partial results, truncation semantics, date formats, matching behavior, and disclaimers. The structure uses clear categorical labels and front-loads the primary purpose before caveats, making it scannable despite its length.

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 and the existence of an output schema, the description is remarkably complete: it covers rate-limit rationale, slow-response expectations, partial-failure behavior, truncation, date interpretation, exact-match semantics, identity limitations, and jurisdiction. Nothing an agent needs to call this tool correctly is missing.

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

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

With schema description coverage at 0%, the description carries the burden of explaining parameters. It explains that county, case_status, and file_date_* are narrowing filters, defines file_date_* as filing-date bounds, and specifies accepted date formats. It does not detail county value formatting or the effect of leaving filters null, but it compensates well for most of the schema's silence.

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: 'Triage a SHORT list of people for North Carolina (NC) court cases.' It immediately identifies the exact use case ('which ones have cases?') and explicitly distinguishes itself from siblings like search_cases_by_party and lookup_court_case by stating it returns counts and facets, not case detail.

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 states when to use this tool, what not to do ('This server cannot accept file uploads'), and names the alternatives: call search_cases_by_party for full rows or lookup_court_case for one case. It also gives concrete usage constraints: max 5 names per call, 3 at a time, split longer lists, and don't retry on slow responses.

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 supply readOnlyHint and openWorldHint; the description adds extensive behavioral detail: server-side versus post-cap filtering, truncated:true meaning matches are missing, finer-grained case_status values, NULL attorney_name for merged matches, 'OF RECORD' not equaling current representation, and public-record status. This does not contradict the annotations.

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

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

Long, but the length is earned: every paragraph addresses a failure mode or routing decision an agent would otherwise get wrong. The most critical facts are front-loaded — purpose, status field, speed, and truncation — before the deeper caveats.

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

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

The description supplies return-field expectations (case_number, caption, filing date, case type, county, case_status, attorney_name, matched_attorneys, truncated), explains the 200-case cap and its consequences, and provides guidance on how to report results honestly. An agent can invoke and interpret this tool correctly without needing the output schema.

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

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

With schema description coverage at 0%, the description compensates by explaining the bar/last/first combination rule, accepted date formats and what file_date means, the case_status filter values versus the finer-grained returned values, and county's post-cap filtering weakness. Only limit is not explicitly discussed, but the 200-case cap and truncated behavior cover its practical impact.

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

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

Opens with a specific verb and resource: 'Cases where an attorney is counsel of record — by bar number OR by name.' It also distinguishes itself from siblings by naming lookup_court_case and get_attorney_hearing_calendar, and clearly scopes itself to North Carolina (NC) only.

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 labels the intended use ('"What's on my docket?" for a lawyer or firm') and gives direct routing rules: use get_attorney_hearing_calendar for calendar questions, do not call lookup_court_case merely for status, prefer bar number over name, and do not present merged multi-attorney matches as one lawyer's caseload.

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

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

The description discloses extensive behavioral traits beyond the annotations. It reveals that the tool is fast (5-45 seconds), has no CAPTCHA, that case_status rows are finer-grained than filter values (so equality checks fail), that there is no party role (every row labeled 'Defendant' incorrectly), that the 200-case cap affects results and county filters happen after truncation, and that matched_businesses lists distinct entities. It also explicitly states 'Public record. Read-only.' which aligns with the readOnlyHint annotation. No contradictions.

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

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

The description is long but every sentence carries essential information. It is structured with clear sections and emphasis (bold, caps) to highlight pitfalls and constraints. The primary purpose and alternative are front-loaded, followed by critical usage rules and edge cases. There is no filler; each clause adds value.

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 (6 parameters, output schema, many potential pitfalls), the description is remarkably complete. It covers usage guidelines, behavioral expectations, parameter nuances, and result semantics (e.g., case_status granularity, matched_businesses meaning). It also warns against common mistakes (e.g., not testing equality with filter vocabulary, not claiming the business is the defendant). With an output schema present, the description needn't explain return structure, but it still clarifies result semantics. Nothing an agent needs to call this tool correctly is missing.

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

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

Although schema description coverage is 0%, the description adds critical semantics for each parameter: name must be typed as it appears with the comma included; limit is not mentioned but default is in schema; county filter happens after the 200-case cap (so counts are lower bounds); case_status values are broad but actual results are more detailed; file_date_start/end bound filing dates and accept two formats. The description also explains wildcard behavior (at least 4 chars before *) and recommends yearly filtering to stay under the cap. This far exceeds what the schema provides.

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

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

The description states a specific verb and resource: find court cases by business name. It explicitly differentiates from sibling search_cases_by_party by specifying that this tool is for organizations (LLC, corporation, insurer, etc.) and that party search requires first and last names. The purpose is unambiguous and well-scoped.

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 provides explicit when-to-use and when-not-to-use guidance: 'Use this, not search_cases_by_party, whenever the subject is an organization.' It explains why the alternative fails for businesses. It also gives detailed usage tips: comma significance, wildcard rules, date formats, the 200-case cap, and how to handle truncation and county filters. These are actionable instructions that guide correct invocation.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses critical behaviors: the ephemeral lifetime of portal_session_ref, truncation flags (portal_truncated vs results_truncated), fine-grained case_status values that do not match the filter enum, party_role_source trust levels, and the 15-50s runtime variance. This goes far 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 description is long, but the tool is complex with 10 parameters, two truncation limits, server-side vs client-side filtering, and token-lifetime caveats. Nearly every sentence carries operational value; the main cost is that the length requires an agent to parse several dense paragraphs, so it is not maximally concise, but it is well-structured with clear topic breaks.

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

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

The description covers the full calling context: required and optional inputs, result semantics, truncation handling, follow-up tool routing, data-quality caveats, read-only nature, jurisdiction, and legal disclaimer. With an output schema present, it does not need to document return types, and nothing essential 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 description coverage is 0%, but the description fully compensates by explaining every parameter: last/first required, limit up to 200, county values, soundex broadening behavior, case_type sourced from narrowing.caseTypes, case_status enum plus the caution about finer-grained return values, confirm_broad for autonomous recovery, and file_date_start/end accepted formats. This is exemplary parameter-level documentation.

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, unambiguous statement: 'Search North Carolina (NC) court cases by a person's name.' It clearly identifies the resource (NC eCourts party-name search), the action (search), and the scope (party/person), and the title and first sentence align exactly with the tool name and its distinguishing role among sibling tools.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: it tells the agent to pass portalSessionRef to lookup_court_case for quick follow-up, to use case_number for persisted work, to NOT call lookup_court_case just to check open/closed status, and to call lookup_court_case for an authoritative role/roster. It also explains exactly which filters are server-side versus client-side and when to use them to recover truncated results.

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 readOnlyHint/openWorldHint annotations: the real-property-lien coverage, the absence of a 200-cap (contrasted with search_cases_by_party), the ~1-3s speed as 'the FAST exception', the alias-sweep status states (ran/failed/skipped), the detail fan-out timeout risk (60s on 'ANDERSON, DAVID'), and client-side substring filtering. Nothing contradicts the annotations — 'Read-only. NC only.' aligns with readOnlyHint=true.

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?

Well-structured with bold section headers, front-loaded purpose, and clear warnings — but the description runs roughly 1,800 words and repeats itself. The lien warning (DO NOT FILTER TO lien) is belabored across three paragraphs, and the alias concept is explained twice. For a genuinely complex tool most sentences earn their place, but the same points could be made in considerably less 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?

For a 12-parameter tool with deep behavioral quirks — alias sweeps, detail fan-out, lien classification, cause_of_action substring semantics, no-cap completeness — the description is remarkably complete. It even addresses return-value nuances (alias_matches as leads, detail_skipped_reason, detail_included) that an output schema would not fully cover, and it has a schema for structured output. Nothing an agent needs to call this 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?

With schema description coverage at 0%, the description carries the full burden and compensates heavily: party ('LAST, FIRST' form), case_number (dashed or undashed), from_date/to_date (binds the ORDERED date, ISO or MM/DD/YYYY), county (server-side exact), judgment_type/sentence_type (comma-separated civil/criminal), alias (direct index search that disables the sweep), cause_of_action (substring match), and detail (auto-fetch behavior). The only parameter left undocumented is 'sort', which is a minor gap given nine others are covered in depth.

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 title and opening line state a specific verb+resource: 'Search North Carolina (NC) money judgments and criminal sentences by party name.' It sharply distinguishes itself from siblings by declaring 'This is the JUDGMENT index, NOT the case index' and naming search_cases_by_party and lookup_court_case as the alternatives for case-level queries. An agent can unambiguously tell this tool apart from every sibling.

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 when-to-use ('does X have a judgment against them', 'how much do they owe', 'find liens/judgments before I lend or rent') and when-not-to-use ('For the case itself... use search_cases_by_party or lookup_court_case') are both given. It also states explicit exclusions (UCC filings, Register of Deeds, liensnc.com) and strong anti-pattern warnings like 'DO NOT FILTER TO lien' and 'DO NOT ask the user whether to pull [amounts]' — guidance an agent can act on without 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 mark it read-only; the description adds behavior: returns ranked snippets rather than full text, expands court abbreviations case-insensitively and reports it in expanded_query, searches current law at section level, and treats low top rank as evidence the subject may not be statutorily covered. No contradiction with readOnlyHint or openWorldHint.

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 longer than average but front-loads the core search-and-get_statute workflow first, then syntax, then interpretation. Every paragraph earns its place with examples and operational 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?

Given the output schema and annotations, the description gives an agent enough to select the tool, form a correct query, understand abbreviated input handling, and know what the result means. It lacks only a bit of detail on chapter/include_repealed filtering, which is unlikely to mislead.

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 contains no property descriptions, so the description must carry the burden. It thoroughly explains query syntax (exact phrases, -excluded terms, or) and shorthand expansion, which is the highest-value parameter. It does not explicitly walk through limit, chapter, or include_repealed, though their names/defaults make them fairly discoverable; this is a small but real gap.

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

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

The description names a specific verb, resource, and mode: search NC statutes by topic, keyword, or phrase. It gives concrete examples and immediately contrasts with get_statute, so an agent can distinguish search 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?

Explicitly states when to use: when you know the subject but not the citation. It names the alternative (get_statute) for citation lookups and even tells the agent to follow up with get_statute after selecting a section. It also explains how to interpret low relevance rather than forcing a match.

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 thoroughly explains side effects: it creates a pending signup, sends a confirmation email, stores name/email/phone/case number, includes an unsubscribe link, and does not share with attorneys. It clarifies that monitoring only starts after the user clicks the link, that count-based detection means moved hearings don't trigger alerts, and that a third active case returns a plain message. This exceeds the annotations' basic readOnly/destructive hints and fully informs the agent of the tool's behavior.

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

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

The description is long but every sentence delivers essential information. It is logically organized: purpose first, then safety constraints, then detailed behavior, storage, limits, and scope. Key warnings are emphasized with all caps, and the formatting makes it easy to scan. Nothing is redundant or tangential.

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 description covers all critical aspects: purpose, side effects, limitations (count-based alerts, free account cap), privacy (no sharing), required versus optional inputs, explicit instructions for interacting with the user, and regional scope. It also addresses edge cases (dormant signup, third active case) and provides a fallback to another tool (search_cases_by_party). This is a complete and self-contained description.

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 the input schema has no parameter descriptions, the text explains every parameter: name and email are stored, phone is optional, and case_number is required ('A case number is required — subscribe to a case, not to a person's name'). It also clarifies that email is used for sending alerts and that the user must confirm the email address aloud. This fully compensates for the schema's lack of descriptions.

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

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

The description clearly states the purpose: 'Sign the USER UP for email alerts when a North Carolina (NC) case changes.' It explicitly distinguishes itself from lookup tools ('It is not a lookup'), uses a specific verb ('sign up'/'subscribe'), and identifies the resource ('case updates'). The additional details about sending a confirmation email and storing information further clarify what the tool does.

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 provides explicit usage guidance: it tells agents to only subscribe the person they are talking to, to confirm details before calling, to use search_cases_by_party if only a name is available, and to subscribe to a case number rather than a person's name. It also specifies the geographic scope ('NC only') and warns against promising alerts for moved hearings or disposition changes. This covers both when to use and when not to use the tool.

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