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

With no annotations, the description fully carries the behavioral transparency burden. It discloses that total is a candidate pool count (not full database), seven structured fields are empty, doc_id is not reusable, and includes performance characteristics for province vs. cause filtering. It even cites empirical test results (Guangdong 20/20) to back claims.

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 somewhat lengthy but every part adds value. It front-loads the core purpose and unique selling point. The notes about empty fields and doc_id reusability could be more succinct, but given the tool's complexity and need for caveats, the length is justified.

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 no output schema and no annotations, the description is extremely complete. It explains return fields (including the ones that are empty), cross-tool relationships (doc_id with get_case), performance characteristics, and the meaning of total. It addresses all likely questions an agent might have.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by explaining the left-prefix search behavior and the performance trade-offs (province fast, cause slow). It also suggests province as 'suggested required' though not technically required, providing semantic context 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?

The description clearly states the tool's purpose: browsing the full corpus of Chinese judgment documents, returning both full text and original links. It explicitly distinguishes itself from siblings by being the only tool providing both body_text and source_url, and contrasts with get_case by noting doc_id incompatibility.

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: prioritize this tool when samples require verifiable links, recommends including province for speed, warns that cause filtering is slow and may timeout, and notes that doc_id from this tool will 404 in get_case. It gives practical tips for effective use.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool operates on the entire database in real-time, mentions the massive dataset size (1.51亿 records as of 2026-07-22), and notes the previous documentation is obsolete. It also warns about dirty data in the year dimension. This is transparent and helps avoid misuse.

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 relatively long but every sentence provides critical information: real-time aggregation, dataset size, obsolete documentation, dimension details, filtering, and data caveats. It is front-loaded with the purpose and then dives into specifics. 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 complexity (no output schema, 5 parameters, real-time aggregation with large data), the description covers the tool's operation, input parameters, usage caveats, and distinguishes from siblings. It does not explain the exact output format beyond [{key,count}], but that is sufficient for an AI agent to use 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 input schema describes 3 of 5 parameters (dim, cause, province) with descriptions. The description adds context beyond the schema: it explains the meaning of each dim value, how to combine filters, and the importance of ignoring certain year values. This adds significant semantic value for an agent.

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's purpose: '案件大數據統計' (case big data statistics) performing real-time aggregation across the entire database. It specifies the available dimensions (cause, province, year, court) and that it returns aggregated counts. It distinguishes itself from sibling tools like case_stats, making the purpose 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 description explicitly tells when to use this tool: it is the only tool that gives true full-database counts, and it contrasts with case_stats which provides sample counts from an 80,000 snapshot. It also warns about dirty buckets in the year dimension, guiding the agent to ignore them. This is excellent 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 no annotations provided, the description fully carries the burden. It discloses that the tool reads a pre-computed snapshot (not real-time), that n_cases is capped per province and not actual case count, that win_rate is always null, and that province dimension has excluded malformed entries. The n_cases_capped flag is also mentioned.

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 relatively long but efficiently structured. It front-loads the main purpose, then lists caveats with numbered bullet points for clarity. Every sentence adds necessary context; no waste given the complexity. Could be slightly more concise but appropriate.

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 one parameter, no output schema, and no annotations, the description is remarkably complete. It covers what the tool does, the output fields (n_cases, p25/median/p75, average salary), data freshness, and critical caveats about sampling and capping. It also relates to sibling tools for context.

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 the single parameter dimension, but the description adds significant meaning beyond the enum values. It explains what each dimension represents (e.g., province→省份, term_reason→解雇原因) and provides context for the output statistics. This extra value justifies a score above the baseline of 3.

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 returns aggregated statistics on labor dispute cases sliced by dimension. It specifies the tool reads a pre-computed snapshot, not the full database, which distinguishes it from siblings like case_analytics. The verb '回傳聚合統計' and resource '勞動爭議判例' are specific.

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 states when to use this tool vs alternatives. It warns that the snapshot is not consistent with other tools, so numbers should not be compared. It directly points to case_analytics for real case counts. It also advises against using n_cases for cross-province comparison due to capping.

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?

Without annotations, description discloses valid doc_id formats, sources, and that wrong format causes 400/404 errors. Adds context about backend (ES side) and date of test. Does not discuss rate limits or auth, but acceptable for a read-only retrieval tool.

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

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

Two sentences and one warning, all front-loaded with purpose. No wasted words; each sentence serves a clear role: purpose, acceptable sources, and crucial caveat.

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

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

For a simple single-param get tool, the description covers purpose, valid inputs, and a key limitation. Could mention return value briefly, but given no output schema, it's not strictly necessary. Sibling context helps complete the picture.

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%, but description adds significant meaning beyond schema: explains two origins of doc_id, specific formats, and warning about browse_full_corpus. Schema alone only states valid formats; description provides necessary usage context.

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 states it fetches single case details by doc_id, with specific verb '取單條' and resource '判決詳情'. It distinguishes from siblings by specifying valid doc_id sources and warning against use with browse_full_corpus results.

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 when to use: with doc_id from search_cases, search_judgments, or search_judgments_full. Explicitly when not to use: with doc_id from browse_full_corpus (will 404). Also notes browse_full_corpus already provides full text, so no need 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?

With no annotations, the description fully bears the burden of behavioral disclosure. It transparently states that win_rate is always null and n_cases is capped at 2000 with a flag. It also clarifies that results include body_excerpt but not full text. These are important limitations that are clearly communicated.

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 verbose but efficiently packs essential information. It starts with the core function, then lists features, caveats, and sibling tool references. Some redundancy exists (e.g., the stats caveats are repeated), but every sentence contributes to understanding. Could be slightly more concise, but structure is good.

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 (8 parameters, mixed search, important caveats, sibling tools), the description is complete. It explains return values (similarity, percentiles, factors), output limitations (no full text), and edge cases (capped n_cases, null win_rate). Without an output schema, it adequately covers the return structure.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema; it provides an example query for the 'q' parameter but otherwise the schema already documents each parameter thoroughly. The description's mention of 'mixed search' is helpful but not additional semantic detail.

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 retrieves Chinese labor dispute judgments (110万+ structured cases) and returns high similarity cases, amount percentiles, and key adjudicative factors. It explicitly distinguishes itself from siblings by indicating what it does not return (full text) and directing users to other tools for that purpose.

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 detailed guidance on when to use this tool (for case summaries, stats, and links) and when not to (for full judgments, use search_judgments_full or browse_full_corpus). It also includes critical caveats about win_rate being null and n_cases capping at 2000, preventing 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?

Discloses that body_text is never returned (0/20 tested), that q only matches title not full text, and that broad queries may be slow with cold cache. No annotations exist, so description fully carries the burden.

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

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

Single dense paragraph conveys all essential info. Could be slightly more structured (e.g., bullet points) but not verbose. Front-loaded with purpose.

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?

Without output schema, describes return fields (title, court, reason, date, case number, link). Covers purpose, limitations, performance, alternatives, and parameter tips. Complete for a complex search 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?

All 7 parameters have schema descriptions (100% coverage). Description adds context: q's title-only matching, performance tip, and example values (e.g., '工商银行 信用卡'). Adds moderate value beyond 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?

Clearly states it is a general-purpose search over 1.2M+ Chinese judgments across 1200+ case types. Distinguishes from sibling search_cases (labor-only with quantification) and refers to search_judgments_full for full text.

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

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

Explicit when-to-use (general case retrieval) and when-not (need full text). Recommends narrowing with reason/province for performance. Directs to alternatives (search_judgments_full, browse_full_corpus).

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 no annotations, the description carries full burden. It discloses that source_url is always null (with specific test evidence), body_text is empty ~15% of the time, q only matches titles, and performance is slow without filters. These are critical behavioral traits beyond basic functionality.

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 informative and well-structured with warnings and alternatives, but slightly verbose. Important caveats are bolded, and information is front-loaded. Could be tightened without losing 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 8 parameters and no output schema, the description covers return fields, null behavior, empty text detection, performance, and sibling tool differences. Comprehensive for the tool's complexity.

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 88%; description adds meaning: q only matches titles, cause is left-prefix matching, pageSize defaults to 20 and max 50. This goes beyond what the schema properties provide.

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

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

The description clearly states it performs full-text judgment search with multiple filters (keyword, province, cause, court, year range). It directly contrasts with sibling tools browse_full_corpus and search_judgments, making the specific purpose 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 description explicitly tells when to use this tool versus alternatives: mentions browse_full_corpus for links+full text, search_judgments for links without full text, and provides instructions for when source_url is null. Also advises narrowing search with province/cause for performance.

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