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

Annotations declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value beyond that by disclosing the returned contents (deadline, vote counts per date, class period, announcing firms, linked docket, matched source announcements), which matters because there is no output 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?

A single front-loaded sentence that leads with the two retrieval modes before the field list. The trailing enumeration is long but every item is informative about the return payload, so little is 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?

With no output schema and no parameter descriptions, the description is the sole source of contract information. It documents return fields well, but omits ambiguous-case handling (both params supplied, neither supplied) and any pagination or volume limits for the ticker-wide mode.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it does clarify that case_id selects one case while ticker selects all cases for a ticker. It does not explain precedence when both are supplied or behavior when neither is given, leaving a 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?

States a specific verb and resource clearly: returns full detail for one case by id, or all cases for a ticker, and enumerates what detail means. An agent can tell it apart from a bulk lister without opening the schema, though it never names the sibling tools (list_cases, search_announcements) it is distinct from.

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 implies the usage modes (by id vs by ticker) but gives no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as list_cases for browsing. An agent must infer that this is the detail-retrieval endpoint.

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 this is a read-only, closed-world operation. The description adds genuinely useful behavioral context: the result ordering and the meaning of the default status=open. It says nothing about result size or how the limit interacts with ordering, which for a 6-param list tool would be worth one line.

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?

One lead sentence plus a tight bullet list, front-loaded with the resource and ordering. Each line earns its place; the only minor cost is abstracting the filters as a glossary rather than prose, which is still easy to scan.

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 6-param, no-output-schema listing tool, the description covers filtering and ordering adequately, but omits anything about the limit/pagination dimension even though limit is a top-level parameter with a default of 50. An agent can call it correctly, but cannot reason about result-set size.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it documents 5 of 6 parameters with real differentiation: ticker is an exact match while query is a substring match, status enumerates the accepted values with their meaning, and first_seen_since is scoped as an ISO date. Only limit is left undocumented (its default 50 is visible in 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?

States a specific verb and resource ('List tracked securities class actions') plus the ordering ('soonest lead plaintiff deadline first'), which distinguishes it from get_case (single case) and search_announcements. It does not explicitly contrast with the siblings, but the resource scope is unambiguous.

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 bullets explain how each filter narrows results, including the useful hint that first_seen_since answers 'what is new', so usage is implied through parameter semantics. There is no explicit when-to-use-this-vs-get_case/search_announcements guidance or statement of default behavior beyond the status enum.

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 readOnlyHint=true, so the description is free to spend its words on subtler behavior, and it does: it warns that a filing code is not a classification, that `securities_candidate` means 'not ruled out' and even `securities_class_action` is unconfirmed. That is real epistemic context an agent needs before trusting the output. It omits ordering, pagination, and rate-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?

Front-loaded with the core purpose, then layered caveats. Dense but each sentence adds information; the only slight drag is the stacked disclaimers in the middle paragraph.

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 and only two annotations, the description does the heavy lifting well, covering provenance, timing, classification caveats, and the unmatched case use. Still missing what a returned docket record looks like beyond the classification fields and how results are ordered or paged.

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

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

Schema coverage is 0%, so the description must carry the parameter burden. It richly explains the `classification` enum semantics and the meaning of `unmatched_only`, but leaves `limit` and `filed_within_days` (only obliquely implied by the 'weeks before' framing) undocumented. Partial compensation for a 4-param 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?

States a specific verb and resource: listing federal dockets under nature-of-suit code 850 (Securities/Commodities) from CourtListener. The scope is unusually precise, but it never names a sibling (list_cases, search_announcements), so an agent must infer the boundary itself.

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 context is implied rather than stated: the timing note ('appear the day a case is filed, weeks before any press release') and the 'unmatched_only' gloss ('possible cases no firm has announced') hint at when the tool is useful. But there is no explicit when-to-use/when-not or routing to 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?

With annotations only declaring readOnlyHint=false, openWorldHint=true and idempotentHint=true, the description adds real behavioral value: it discloses that cap-exceeding articles are deferred rather than dropped, that unreachable sources are reported by name and retried, and that it merges into existing lawsuits (a mutation). It stops short of describing result/output shape beyond the error-reporting note.

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

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

Front-loaded with the pipeline in the first sentence, then compact per-parameter clauses. It is longer than a typical description but every clause corresponds to an undocumented parameter or a behavior (deferral, retry) that an agent needs, so the length is earned.

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 4-parameter mutation tool with no output schema and 0% schema coverage, the description covers parameters, external I/O, failure handling, and partial result reporting. The main remaining gap is a fuller account of what a run returns or how progress is observed.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: it defines sources with the concrete allowed values (prnewswire, businesswire, globenewswire) plus the 'all three' default, days as a look-back window, max_fetch as a per-source body cap, and include_courts as a CourtListener sweep limited to nature of suit 850. This supplies semantics the schema's bare typed properties entirely lack.

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 concrete verb+resource pipeline: read newswires, discard non-filed cases, extract ticker/class period/deadline, and merge announcements into lawsuits. An agent can tell this is the ingest/refresh job rather than a read tool like list_cases or search_announcements, though the description never names a sibling to sharpen the boundary.

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 context is implied by 'Run one pass' and by the parameter semantics, but there is no explicit statement of when to call this versus get_case/list_cases/search_announcements, nor any prerequisite or exclusion. The operational notes (deferred over cap, retried on failure) hint at usage but do not route the agent among 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful scope detail (includes set-aside announcements, reports why each was set aside or which case/rule absorbed it), but says nothing about ordering, pagination, or how 'limit' behaves.

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?

Compact and front-loaded: the return scope is stated first, then the two filtered fields. The kind/source glosses are terse but justified given zero schema description coverage.

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 does decent work describing what comes back (announcement plus the decision about it). However, two of four parameters lack any semantics and there is no note on result volume or default limit behavior.

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

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

Schema description coverage is 0%, so the description must carry the parameters. It usefully enumerates kind values (filing, reminder, investigation, settlement, other) and gives a source example (prnewswire), but 'query' and 'limit' are left entirely unexplained.

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 and resource ('Search every announcement the tracker has read') and clarifies scope, including set-aside items and the decision attached to each. It does not explicitly distinguish itself from siblings like list_cases or get_case, so it stops short of a 5.

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

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

There is no statement of when to reach for this tool versus list_cases/get_case, nor any prerequisite or exclusion. Usage is only inferable from the fact that it searches announcements and their decisions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds substantial value on top: it discloses the exact fields returned, the presence of error history, and a staleness heuristic for interpreting the output. It doesn't cover refresh cadence or whether the classifier status is live vs cached, but the diagnostic context is genuinely useful.

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 classifier state, then the per-source field list, then a single diagnostic sentence that earns its place by telling the agent how to read the data. Slightly dense in the middle enumeration but no wasted 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 and no annotations describing returns, the description carries the burden of explaining the payload, and it does so reasonably: it lists the reported fields and gives a staleness interpretation. It stops short of describing the structure/shape of the response, but is adequate for a zero-arg status 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?

Zero parameters, so the baseline is 4 — there is no parameter surface for the description to compensate for.

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 concrete resource (sources) and enumerates exactly what is reported: classifier active state, on/off, last success, last error, newest announcement, and record counts. It's a monitoring/status tool, clearly distinct in intent from case/announcement siblings, though it never explicitly differentiates itself from them.

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

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

Usage is only implied — the diagnostic note that a source whose newest announcement hasn't moved 'has quietly stalled' hints at when to consult this (health checking), but there is no explicit when-to-use, prerequisite, or alternative tool guidance.

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