CT Injury Cases

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds useful behavioral context by disclosing the dataset domain and that the response includes caveats and per-tool examples; the output schema handles return shape, so omission of return format is minor.

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

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

It is front-loaded with 'Start here' and then a compact enumeration of returned content. There is no filler, although the long list makes the sentence dense.

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

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

For a read-only documentation tool with an output schema and a fully documented single parameter, the description is complete enough: it tells the agent this is the starting point and what topics the response covers. No call-critical detail 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 sole parameter is fully documented in the schema, including that purpose is logged and never returned. The description adds no parameter guidance, so baseline 3 is appropriate when schema coverage is 100%.

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 identifies a documentation/overview tool and enumerates exactly what it returns: dataset scope, currency, fields, stats metrics and dimensions, caveats, and example calls. 'Start here' differentiates it from sibling get/search/stats tools as the orientation resource.

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?

'Start here' gives explicit sequencing guidance: call this before other tools. It does not state when not to use it or name alternatives, but its orientation role is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine context beyond them: the aggregation semantics warning that totals are attorney-wide rather than current-firm-only, which prevents a misreading of the returned numbers. No mention of rate limits or result size, but that is a modest gap.

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

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

Two tight sentences, front-loaded with the resource and its contents, followed by the one interpretive caveat that matters. 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?

Output schema exists, so return-shape explanation is unnecessary, and the one non-obvious semantic risk (cross-firm aggregation) is called out explicitly. Combined with annotations covering the safety profile, an agent has what it needs to call this correctly.

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

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

Schema description coverage is 100% and both parameters are documented there, including the note that 'purpose' is logged and never returned. The description adds nothing about either parameter, so the baseline 3 applies.

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

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

Names the resource precisely ('One attorney') and enumerates the facets returned: firms, opposing firms, medical experts, motion practice, case outcomes. The scope caveat ('figures span every firm the attorney has filed with, not only their current firm') separates it from a firm-scoped lookup, though the description never names search_attorneys as the entry point the way a top-tier definition would.

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 aggregate caveat tells the agent how to interpret figures but not when to pick this tool over search_attorneys or get_firm. The fact that juris_number must come from search_attorneys appears only in the schema, not the description, so the workflow has to be inferred.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds a useful inventory of what the record contains (rulings, parties by side), but says nothing about missing data, not-found handling, or completeness of the returned record.

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 dense sentence that front-loads the core contents with no filler. It is a noun phrase rather than a full sentence, which slightly reduces clarity but not efficiency.

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

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

An output schema exists, so the description need not explain return shapes; listing the major data categories is enough for an agent to decide whether to call. Only edge-case behavior (unknown docket number) is unaddressed, and that is minor given the annotations and 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?

Schema coverage is 100%, so both docket_number and the 'purpose' field are documented in the schema, including a format example. The description adds no parameter-level detail beyond that, which is the baseline when the schema does the work.

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 fragment 'One case: dates, disposition, trial, verdict and offer amounts...' makes clear this retrieves a single case record and enumerates its contents. The singular scope implicitly distinguishes it from search_cases, though no verb is used and the sibling is never named.

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 by the singular 'One case' against the search_cases sibling; there is no explicit statement of when to use this versus searching. The agent must infer that a known docket number routes here.

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

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

Annotations already declare readOnly, idempotent and closed-world, so the safety profile is covered; the description goes beyond them by explaining that cases/plaintiffCases/defenseCases count every appearance while casesByYear, opposing firms, experts, motion practice, outcomes and the firm_juris_number filter are restricted to cases where the firm is the lead side. That is precisely the kind of nuance an agent would otherwise misread. It does not cover failure modes for an invalid juris_number, so not a 5.

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

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

Two sentences, no filler, with the content inventory front-loaded so the agent sees what comes back immediately. The second sentence is dense and clause-heavy ('the stats plaintiff_firm and defense_firm dimensions and the firm_juris_number filter'), which costs a little readability but every clause carries information.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile; the description adds the one thing structured fields cannot express, why a firm's totals differ across surfaces. Missing only edge-case behavior (unknown juris_number), which keeps it from a 5.

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

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

Schema coverage is 100% and both parameters carry their own descriptions, including the unusual 'purpose' parameter being log-only and never returned. The description adds no syntax or format detail for juris_number itself and only indirectly explains why scoping matters. Baseline 3 applies when the schema does the heavy lifting.

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

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

The first sentence enumerates exactly what the tool returns for a single law firm: attorneys, opposing firms, experts, motion practice, and case outcomes. Combined with the required juris_number it is clearly a single-firm profile getter, distinguishable from the sibling search_firms (which supplies the identifier). It stops short of an explicit verb like 'retrieve a law firm profile by juris number', which is why it is not 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?

The description implies usage through the data-semantics caveat (case counts vs. lead-firm-only figures), but never states when to call this instead of search_firms or the stats family. The only explicit workflow hint, 'Firm juris number from search_firms', lives in the schema rather than the description. An agent can infer the search-then-fetch flow but must do the inferring.

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

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, lowering the bar. The description still adds genuine context beyond them by disclosing the ~11-month window for closures and the aggregation granularity (motion family), though it says nothing about coverage limits or freshness of verdict 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?

A single front-loaded sentence with no filler; the parenthetical time window earns its place. Slightly dense in its list of three metrics but not padded.

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-value detail need not be spelled out, and the description adequately characterises what the profile covers. Minor gap: no statement of jurisdictional/dataset scope, which matters for an open-ended analytics 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 coverage is 100% for both parameters, so judge_key and purpose are already documented in structured data. The description adds no meaning beyond the schema, so the baseline of 3 applies.

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

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

The description names a specific resource (one judge) and enumerates the three content areas returned: case outcomes/closures, motion grant rates by family, and trial/verdict figures. It is clear what the tool does, though it never names a sibling (e.g. search_judges) to contrast 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?

Usage is only implied: the schema notes judge_key comes 'from search_judges', suggesting this is the detail lookup after a search, but the description itself states no when-to-use condition or alternative. An agent must infer the search-then-fetch pattern.

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

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

The annotations already cover the safety profile (readOnlyHint, destructiveHint). The description primarily confirms the read-only nature of the operation by detailing the data retrieved. It adds context regarding the *type* of data (e.g., counts only, disputed findings) but no novel behavioral constraints.

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 tool definition is maximally dense and efficient. Every phrase in the single sentence serves to precisely define the scope and contents of the returned profile, avoiding any 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 that an output schema exists, the description focuses entirely on providing comprehensive semantic value regarding the returned data. It successfully tells the agent exactly what the 'profile' entails, fulfilling its contextual role perfectly.

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

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

With 100% schema coverage, the baseline score is 3. The description adds semantic value by defining the context of the required provider_id—it is the specific identifier needed to retrieve this complex profile.

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 is extremely specific, using definitive language to outline exactly what the tool retrieves: law firms, case lists, case endings, and specific findings for defense examiners. This makes its purpose crystal clear and highly distinct from searching or retrieving single cases.

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

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

While it does not explicitly list 'when' versus 'when not,' the detailed description of the profile content inherently guides the user. An agent knows this tool is for comprehensive profile retrieval, differentiating it from simple search tools like search_providers.

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=false and destructiveHint=false already signaling a safe write, the description adds useful behavioral context: the request is logged and read by the people who build the dataset, meaning it is a human-reviewed feedback channel rather than an immediate data fetcher. It does not explain whether the agent receives any confirmation beyond the output schema, but that is largely covered by the existing output schema. No contradiction with 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?

Two short sentences with no wasted words. The core request is front-loaded, followed by the examples and the logging behavior, making it easy to scan and act on.

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

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

The tool is low-complexity with two fully documented parameters, an output schema, and annotations covering safety. The description supplies the missing conceptual context: this is a human-reviewed request log for missing data, not a retrieval operation. It could be slightly more complete by explicitly directing the agent to first try existing search tools, but overall it is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so both the purpose and description parameters are already fully documented in the schema, establishing a baseline of 3. The description adds examples of the kinds of data to mention (other courts, states, case types, fields, documents), but it does not clarify how to distinguish the purpose parameter from the description parameter. This is baseline-level value over the schema.

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

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

The description states a specific action: tell the dataset maintainers about missing data you need, with concrete examples (other courts, states, case types, fields, documents). This distinguishes it from retrieval siblings like search_cases and get_case, though it does not explicitly name an alternative. The verb-and-resource combination is clear enough for an agent to select it.

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 implied by 'data this dataset does not have but you need,' which tells the agent to use this when existing search/get tools cannot satisfy the need. There are no explicit when-not conditions or named alternatives (e.g., 'use search_cases first'), leaving the agent to infer the boundary. This is adequate but not strong guidance.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so safety needs no restating. The description adds the ranking behavior (most cases first), which is genuinely useful, but says nothing about paging, result-set size, or empty-result behavior beyond what the schema carries.

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

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

Two short sentences, front-loaded with what it does then the disambiguation pointer. Nothing redundant, nothing padded.

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

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

With an output schema, full parameter documentation, and complete annotations, the description covers what is needed to select and call the tool. Only paging expectations (cursor/limit cycling) are left entirely implicit.

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

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

Schema description coverage is 100% and the schema descriptions are richer than the summary (e.g., side explains re-ranking by cases on that side). The description merely enumerates a subset of facets, adding no semantics beyond the schema.

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

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

Specific verb and resource ("List attorneys") plus the filterable facets and the ranking order ("most cases first"). It also names the sibling get_attorney so the agent can tell list-of vs. single-record apart 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?

"get_attorney gives one attorney in full" establishes the split: use this to enumerate/filter, use the sibling for full detail. No explicit when-not-to-use or mention of search_cases/search_firms as alternative entry points, so it stops short of a 5.

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

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

The annotations already declare this is a read-only, idempotent, non-destructive, non-open-world operation. The description adds useful behavioral details beyond them: results are returned in docket-number order and capped at 50 per page, which matters for pagination expectations.

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

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

Two sentences, front-loaded with the core action, followed immediately by alternative-tool routing. There is no redundant or filler text.

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 rich schema, annotations, and output schema, the description covers the essential selection context and ordering. Minor omissions such as cursor pagination specifics are already handled by the schema, so completeness is strong but not exhaustive.

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

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

Schema description coverage is 100%, so every parameter is already documented in detail. The description mainly restates that filters exist and that page size is capped at 50; it adds little parameter-level meaning beyond the schema baseline.

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

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

The description states a specific verb and resource: 'List auto-injury cases matching filters.' It also adds ordering and page-size scope, and explicitly distinguishes the tool from get_case and stats, so an agent can identify its role without opening the schema.

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

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

It explicitly routes the agent to alternatives: use get_case for one case in full and stats for aggregate counts, rates, and amounts. Combined with 'matching filters,' this makes the selection condition between search, detail lookup, and aggregation clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds genuine context not present in structured fields: the default sort is 'most cases first', which affects how results should be interpreted. Pagination is left to the cursor/limit 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?

Two tight sentences, front-loaded with the filter/sort behavior and followed immediately by the disambiguation pointer. There is no filler and nothing an agent must read past.

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 full schema coverage, annotations, and an output schema, the description only needs to carry purpose and routing, which it does. Minor gaps like the default page size are already documented in the schema, so nothing critical 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 100%, so every parameter already has documented meaning, including the side-ranking nuance and min_cases behavior. The description's mention of 'size' maps loosely to min_cases but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb ('List') and resource ('law firms') plus the filter dimensions (name, side, district, size) and ordering ('most cases first'). It explicitly distinguishes itself from the sibling get_firm ('gives one firm in full'), so an agent can choose between them without opening either schema.

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

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

The sentence 'get_firm gives one firm in full' makes the list-vs-detail split clear, which is the main decision an agent faces here. It stops short of explicitly ruling out other search_* siblings or stating prerequisites, but the usage context is unambiguous.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description still adds real behavioral value: results are sorted with the highest case counts first and each entry includes a case count, which shapes how an agent should interpret the returned ordering. Return format itself is covered by the output schema, so no penalty there.

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

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

Two short sentences with zero filler. The primary capability and the sort behaviour are front-loaded, and the disambiguation sentence follows immediately.

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 a full input schema, a declared output schema, and complete annotations, the description supplies everything needed to select and call the tool. The only omission is that it never signals pagination exists, though cursor and limit are self-documenting in the 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?

Schema description coverage is 100%, so name, district, limit, cursor, and purpose are all documented in the schema with more precision than the description gives. The description only echoes "by name and district" and adds no matching semantics (substring, case handling) or pagination guidance beyond what the schema already states. Baseline 3 applies.

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

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

States a specific verb and resource (list judges), the filterable attributes (name, district), the sort order (most cases first), and what each row carries (case counts). It also explicitly names the sibling it is not: get_judge. An agent can distinguish it from every search_* sibling without opening a schema.

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

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

"get_judge gives one judge in full" explicitly routes the agent to the alternative for the single-record case, which is the main ambiguity here. What's missing is any exclusion for the adjacent case (search_cases when a judge's rulings, not judges, are wanted), so selection is clear but not fully framed.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds one genuinely useful behavioral detail not in the schema or annotations: results are ordered with the most-litigated providers first, which affects how an agent should interpret the top of the list. It says nothing about pagination mechanics or result shape, leaving the remaining burden to the schema and 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?

Two sentences, no waste, with the capability and the sibling routing front-loaded. Every clause carries information an agent needs.

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

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

With a rich input schema, an output schema, and full annotations, the description covers the essentials: scope, filters, ordering, and the alternative tool. Only minor gaps remain, such as whether filters are conjunctive and how paging interacts with the ordering, but these are small against the structured coverage.

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

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

Schema description coverage is 100% and every parameter, including the side enum values and the purpose/cursor semantics, is documented inline. The description only echoes the filter names ('type, specialty, side, town and size') without adding syntax, matching rules, or defaults, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List medical providers named in expert disclosures'), names the filter dimensions, the ordering ('most cases first'), and explicitly distinguishes itself from the sibling get_provider, which returns a single provider in full. An agent can tell exactly which of the two tools to reach for.

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 closing sentence routes the agent to get_provider for a single full record, giving clear context for when this search tool is the wrong choice. It does not spell out how filters combine or what happens when no filters are supplied, so it stops short of full when/when-not guidance.

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

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

With annotations only declaring the mutation profile (readOnly=false, destructive=false, idempotent=false), the description adds meaningful undisclosed context: the recipient is the service operator, and the name/email must not be included without explicit user consent. Schema-side it also notes that 'purpose' is logged and never returned, a non-obvious data-handling trait. It stops short of saying what feedback or confirmation the caller receives, but an output schema exists to cover that.

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

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

Two sentences, front-loaded with the action and recipient, then the permitted content categories, then the one hard constraint. No filler and nothing important buried.

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 four-parameter, single-responsibility tool with full schema coverage, annotations, and an output schema, the description covers purpose, audience, and consent requirements adequately. Only minor gaps remain, such as whether the user should expect a reply and any rate-limiting on repeated sends.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including the permission condition on name/email and the logging behavior of 'purpose'. The description largely restates the consent rule and purpose categories rather than adding syntax, format, or selection guidance beyond the schema; baseline 3 applies.

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

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

Names a specific verb and resource ("Send a message to the person who runs this service") and enumerates the accepted content classes: feedback, questions, data problems, and interest in paid features/coverage/limits. This makes it unmistakable against the sibling set, which is entirely read-only dataset 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 enumeration of legitimate purposes (feedback, question, data problem, paid features) gives a clear when-to-use criterion, and the explicit-permission rule for including name/email is a real operating constraint. No when-not guidance or alternative routing is stated, but there is no sibling tool that competes for this use case, so the gap is minor.

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

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

Annotations already cover read-only, idempotent, closed-world safety, but the description adds genuinely non-obvious behavior: small-group suppression (three or fewer cases), a 100-group cap, and largest-first ordering. These are exactly the traits an agent cannot infer from the schema, though it doesn't say what an invalid metric/unit combination returns.

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

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

Four sentences, each earning its place: purpose first, then the discovery pointer, then the two limits. No filler and no repetition of schema content.

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 21 parameters, an output schema, and rich annotations, the description covers the things structured data can't: suppression, group cap, ordering, and where to learn valid metrics. Only a note on how filters interact with the case-vs-motion unit distinction 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 100%, so the schema already carries parameter meaning and a 3 is the baseline. The description only restates that grouping takes up to two dimensions and that filters narrow results, adding nothing beyond maxItems and the per-field 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?

States a specific verb and resource ("Compute one metric over cases (or motion rulings)") plus the two modifiers available (grouping dimensions and filters). This clearly separates it from retrieval siblings like search_cases and get_case, which return individual records rather than aggregates.

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 routes the agent to describe_dataset for metric/dimension enumeration and states which unit each metric applies to, which is real usage guidance. However, it never states when to choose this over search_cases plus manual counting, nor any prerequisite conditions or exclusions.

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