search_precedents

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

With no annotations, the description carries the full burden and does so well: it discloses the per-category page size (20), the site's 500-record cap per category, pagination behavior, and the meaning of result fields such as reference_value, status, status_note, and 編註. It omits auth/access prerequisites but otherwise provides unusually rich operational 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 definition is long but well-structured: purpose is front-loaded, then a bulleted taxonomy, then caveats, then limits. Given the category list effectively substitutes for a missing enum in the schema, the length is largely earned, though a few lines could be tightened.

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

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

For a complex, domain-specific taxonomy tool with no annotations and no output schema, the description supplies the category definitions, default behavior, result caps, pagination guidance, and field semantics an agent needs. The absence of an output schema is well compensated by the explanation of reference_value/status/編註 fields.

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, and it does: keyword is defined as full-text search, category accepts comma-separated values with a documented default set, and year_from/year_to are clarified as 民國年. Only page is left to inference, a minor 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 (司法院判解資料), then explicitly carves out its scope by noting these are the categories search_judgments cannot return. The enumerated category list lets an agent distinguish it from siblings without opening any schema.

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

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

Explicitly routes the agent away from search_judgments and lists which categories belong here, plus the default category set when none is supplied. It also gives mitigation advice (add keyword or year when results are too numerous) and points to get_precedent for 編註, though it does not state general when-not-to-use conditions.

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