Taiwan Legal RAG

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is handled. The description adds substantial behavioral context beyond that: token expiry with bounded automatic recovery, case_history semantics and overturn detection, and a post-answer verification step. It falls short of 5 because the return payload (citation_text, case_history, text_excerpt/truncation flags) is described only by reference, with no output schema to anchor those field names.

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 densely operational and front-loaded with the core purpose in the first sentence; the paging ritual, failure protocol, and citation-matching rule each prevent a distinct class of error. The offset guidance duplicates the schema's own description, but that redundancy is defensive rather than wasteful.

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 a nontrivial pagination protocol, the description carries almost the full burden and covers truncation, contiguity proof, and the 'no advancing offset' failure case. The remaining gap is the enumerated response fields themselves, which are referenced but not itemized.

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 only 33% (doc_id and result_token are bare strings), so the description must compensate and does: it says both come from the search result, that tokens must be copied verbatim and never reconstructed, and it fully specifies excerpt_offset semantics (source Unicode code points, not UTF-8 bytes, use next_excerpt_offset rather than len(text_excerpt)). That is far more than the schema conveys.

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 ('Retrieve the full reasoning text of a judgment') and scopes it to a judgment selected from search results, which cleanly separates it from search_judgments. An agent knows immediately that this is the follow-up fetch, not another 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?

Explicitly names when the tool is REQUIRED ('whenever you intend to quote or paraphrase a court's holding — the search listing alone does not contain reasoning text'). It also covers recovery branches: rerun search ONCE on result_token_invalid_or_expired, never retry the same failed token, stop if recovery fails, and 'This is not a login error.'

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/open-world, and the description goes further: it returns only the current consolidated version with no historical versions, may include an abolition note, and exposes law_url for amendment history. It also explains the two failure modes (article-not-found implies wrong/renumbered number; law-name miss returns law_candidates and does not prove nonexistence due to corpus gaps). Lacks only detail on response shape beyond the key fields.

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?

Dense but well-structured: the core action is front-loaded, followed by the verification rationale, the scope limitation, and the failure-mode guidance. Nearly every sentence carries operational value, though it runs long enough that the historical-version caveat 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 2-parameter lookup with no output schema, the description covers what is returned (verbatim article_content, abolition note, law_url), the corpus's scope limits (no municipal ordinances, incomplete administrative rules), and both error paths — nothing an agent needs to invoke and interpret 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?

Schema coverage is 100%, so the baseline is 3; the description still adds value by clarifying that article_no accepts the '47-1' form meaning 第47條之1 and that law_name accepts common abbreviations. It also introduces the meaning of law_candidates returned on a name miss, tying parameters to failure behavior.

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 ('EXACT lookup of a CURRENT Taiwan statute article') plus the identifiers used, with a worked example (民法, 184 / 47-1). It is immediately distinguishable from siblings like get_legal_reference and search_judgments, which it names.

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 says when to use it (verify every statute citation before legal writing) and when not to (never for pre-amendment 行為時法 text — check law_url amendment history; not for 函釋 or judgments, with the correct sibling named for each). Alternatives and exclusions are both spelled out.

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 the safety profile (readOnly, idempotent, non-destructive), and the description still adds several things annotations cannot express: the returned `status` lifecycle vocabulary and how to interpret repealed/ceased vs `unknown`, and the warning that a not-found result does not mean the serial is fabricated. It also discloses the document class limit (agency materials, never court reasoning), which prevents a misattribution error the annotations would not catch.

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 a dense block rather than a short one, but the identifying fact (EXACT serial lookup) is front-loaded and each subsequent sentence encodes a distinct failure mode: status misreading, miss-as-fabrication, document-class confusion, wrong-tool-for-keywords. The final 勞裁字 sentence is narrow but prevents a specific misfire, so it earns its place; a line-broken layout would improve scanability.

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 2-parameter, no-output-schema lookup tool, everything an agent needs to call it correctly and to correctly interpret the result is present: input shape, the status field's meaning, the meaning of a miss, and the doc-type boundary. There is no output schema, yet the description still characterizes the returned payload enough to act on it.

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 the per-field descriptions already carry the parameter semantics and the baseline is 3. The description adds a genuine constraint beyond that — that this tool takes the serial only and that keyword exploration belongs elsewhere — which reinforces why `serial` must be an exact number rather than a search phrase.

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 ('EXACT lookup of a Taiwan administrative interpretation by its issuing serial number') and immediately supplies concrete serial-format examples. It also explicitly marks the boundary against search_legal_references (keyword exploration), so an agent can pick between the two 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?

Gives an explicit use case ('verify that a cited interpretation exists and to check its current validity BEFORE citing it') plus named alternatives and the condition that selects each: search_judgments for judgments, search_legal_references for topic/keyword work, search_bundle/search_judgments for 勞裁字 decisions. Exclusions are stated as directly as the inclusions.

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 annotations, the description discloses important behavior: the returned bundle contains allowed_citations and strict citation rules, unread candidates must not be cited as authority, arbitration decisions are administrative rather than court judgments, and duplicate bundles can degrade answer quality. This is rich context for a read-only, idempotent search 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?

The description is front-loaded with the recommended use case and remains information-dense throughout. It is somewhat long, but nearly every sentence adds relevant legal or behavioral context.

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 there is no output schema, the description does a good job explaining the returned bundle, citation rules, result_token, and arbitration caveat. The main completeness gap is the lack of input parameter semantics for read_top, max_results, and search_type.

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 explain the four input parameters. It only implies the query parameter and does not explain read_top, max_results, or search_type, leaving key controls 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?

The description uses specific verbs and resources: it runs a search, retrieves reasoning excerpts, and returns a citation bundle. It explicitly distinguishes itself from search_judgments and explains its role in answering Taiwan legal questions.

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 usage guidance: use this instead of search_judgments when answering a legal question, reuse an existing bundle for the same question, and use get_judgment_fulltext for unread candidates or truncated excerpts. It also explains special handling for labour questions involving arbitration 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 cover read-only/idempotent/open-world, yet the description adds real substance: the anchor-bundle return shape, the allowed_citations vs unread_candidates distinction, and the 'arb:' prefix meaning administrative 裁決委員會 decisions rather than court holdings. It omits any note on result caps or latency, keeping it below 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?

Purpose is front-loaded in the first clause and every subsequent sentence carries citation-policy or reuse information. The labour/arbitration caveat is dense but earns its place; the whole thing is slightly crammed into one block.

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 two-parameter, no-output-schema search tool, it explains the return shape (anchor bundle, citation ids, unread candidates) and citation constraints well. The missing piece is any description of max_results behavior or what happens beyond the default result count.

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% for two parameters, so the description carries the full burden. It implies query semantics loosely, but says nothing about max_results (default 5, max 10) or how query strings are interpreted, leaving half the schema undocumented in both places.

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 ('Search Taiwan court judgments') and adds what comes back ('an anchor bundle with server-read reasoning excerpts'). It doesn't explicitly differentiate itself from the similarly named sibling search_bundle, so the agent must infer the distinction.

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 clear reuse rule ('if the same question was already searched earlier in this conversation, reuse those results') and a labour-query caveat, but never says when to prefer this tool over search_bundle or get_judgment_fulltext. Usage is implied rather than routed.

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 cover the safety profile (readOnly/idempotent/openWorld), and the description adds substantial non-annotation context: results are unranked-for-relevance candidates, corpus is non-exhaustive, materials are agency documents not court reasoning. It stops short of describing ranking mechanics or pagination, but the verification workflow it specifies is unusually strong behavioral disclosure.

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 and filters, then the caveats. The warning block is long but each item (verify, quote verbatim, mis-citation risks, corpus gaps) carries distinct operational weight. Slightly dense in the legal-disclaimer run-on, but no dead sentences.

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 names the returned fields (citation, serial_no, lifecycle status, similarity score, excerpt) and the required follow-up path for full text, so an agent knows both what comes back and what to do next. Nothing needed 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 coverage is 75%, so filters are already partly documented; the description reinforces authority as an exact agency name with concrete examples (財政部/勞動部) and enumerates source_kind values in prose. It adds meaning beyond the schema for the two filters but says nothing about max_results or query phrasing beyond what the schema shows.

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 ('SEMANTIC search over Taiwan administrative interpretations'), enumerates the corpus types covered, and explicitly distinguishes itself from court judgments and the 裁決 corpus. An agent can tell it apart from search_judgments and search_bundle 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?

Gives explicit routing: use search_judgments for judgments, use search_bundle/search_judgments for 勞裁字 labour decisions, and mandates a follow-up get_legal_reference call before citing. It also states when-not-to-infer (empty result does not mean the interpretation doesn't exist).

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