japanlaw.org — Japanese law

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

Annotations already declare the safe read-only/idempotent profile, and the description still adds substantive behavior: Markdown layout, per-paragraph translation provenance (MoJ translation, slip-corrected, or machine), per-line address and URLs, citation graph, and sources. It also discloses the negative behaviors that matter most — a law returns only an overview, and a date with no held text is refused rather than answered with the nearest text.

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 action and the provision-vs-law split before the finer detail, and nearly every clause carries information. The sentences are long and clause-stacked, which costs some readability, but there is little dead weight.

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 read tool with full schema coverage, annotations, and an output schema, the description supplies everything an agent needs: both id forms, what each returns, translation provenance, version selection, and the refusal case. No material gap remains.

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, but the description adds real meaning beyond the schema: why asOf/version exist (an earlier text, or one an amendment not yet in force will leave) and that a japanlaw.org URL is accepted as an id. It stops short of the mutual-exclusion and format details, which the schema already carries.

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 ('Read in full a law or provision ... by its id') and splits the two id shapes into distinct outcomes, so an agent knows exactly what comes back. It never names the overlapping siblings get_provision and get_law, so the boundary with those tools is only implied (via 'in full' and the lang note about get_provision's card).

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?

Clear context: use it on an id 'search found', with explicit routing between a provision id (full text) and a law id (overview, 'never its whole text'), and the asOf/version fork for reading a non-current text. No explicit when-not or sibling routing against get_law/get_provision, which is the main remaining gap.

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 (readOnly, idempotent, closed-world), it discloses pagination behavior (continued.cursor replayed with the same version), a significant data caveat (amendments with textPublished false have their changes merged with the next amendment's and cannot be told apart), and a coverage warning that some amendments' changes are not held. These are non-obvious traits the annotations cannot express.

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, but the prose is telegraphic and clause-stacked ("its version — the text it leaves, which get_provision and fetch read where textHeld is true"), which slows parsing of an otherwise informative definition. Almost every sentence carries real content, but the em-dash nesting hurts readability.

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?

Covers the full call lifecycle for a moderately complex tool: list mode vs. single-amendment mode, pagination continuation, and two distinct data-availability failure modes. An output schema exists, yet the description still supplies the interpretive caveats an agent needs to avoid misattributing changes.

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 spelling out what passing a version yields (per-provision before/after wording in Japanese and English, plus beforeEnglishWhose/afterEnglishWhose) and by linking cursor to continued.cursor from the same version. It does not explain the law identifier forms or the lang parameter, leaving those entirely to 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 resource and scope: what a single amendment to a Japanese law changes, when it takes effect, and its state. It explicitly contrasts itself with list_changes (cross-law, date-range) and with get_provision/fetch (text reading), so an agent can route 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?

Names the alternative and the condition that selects it: "for what changes across every law between two days, list_changes." It also gives an explicit usage rule for the version parameter ("Unset lists the amendments") and a prohibition against answering from memory, which is exactly the routing guidance an agent needs.

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 genuinely new behavioral context by disclosing the coverage boundary ('in the laws japanlaw.org holds') and the per-result payload (law, designation, citing words, id, url). The instruction to link each cited provision by its fromUrl is useful output-shaping guidance. It stops short of saying what an empty result means or how limit/total interact beyond the schema, keeping it at 4.

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 purpose and scope are front-loaded before the invocation instructions, and no sentence is pure filler. The middle clause is dense and slightly tangled ('an id for fetch and its url; link each one you name by its fromUrl'), mixing payload description with output formatting in one breath, which costs a point.

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 present and 100% parameter coverage, the definition only needs to add scope and routing, both of which it does, including the important caveat that coverage is limited to laws japanlaw.org holds. Its remaining gap is minor: no statement about what to do when nothing cites the provision, but that is largely covered by the output 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 law, address, lang and limit are all already documented in structured form, including the three address notations. The description's only addition is a worked example ({"law": "labor-standards-act", "address": "Article 36(1)"}), which mildly reinforces the required pair but repeats what the schema already says.

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 — 'Find the provisions that refer to a given one' — and then bounds the scope explicitly (same law, other laws, and the Cabinet/Ministerial Orders that set the details), plus the corpus limit 'every provision in the laws japanlaw.org holds'. That reverse-citation framing is clearly distinct from get_provision (fetch one provision) and search (find provisions), so an agent can select it 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 tells the agent how to invoke it ('Call it with law and address, as get_provision') and supplies a concrete call example, which anchors the two required parameters. It does not, however, state when NOT to use it — e.g. that forward citations (what a provision cites) or plain text reading belong to get_provision/search — so the alternative routing is implied rather than 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?

Goes well beyond the readOnly/idempotent annotations by disclosing pagination semantics (a law with many terms stops at one; continued.cursor must be passed back with the same arguments), the currency constraint ('The text in force only'), and the fact that the response mixes statute text, japanlaw.org explanations, and related legal concepts (施行, 政令, 附則). That is substantive behavioral context an agent could not infer from 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?

Purpose is front-loaded in the first sentence, followed by scope, mode selection, and pagination in a logical order. The long parenthetical enumerating return fields (statuteJa, englishWhose, definedAt, scopeLabel…) partly duplicates the existing output schema and makes the middle sentence a run-on, which is the main efficiency cost.

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 five-parameter tool with an output schema, the description covers everything an agent needs: what is returned conceptually, how address changes the result set, how term narrows it, how to continue paging, and that only in-force text is included. No material gap remains.

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 schema already documents all five parameters; the description adds value by explaining why address matters ('because its text uses the word'), that term matches Japanese, reading, or English, and that cursor must be reused with identical arguments. The marginal gain is real but modest given how complete the schema is.

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: it returns the words a Japanese law defines for itself (定義語), and explicitly bounds their meaning to that law's reach rather than everyday speech or another law. The 'Call it before explaining what a provision means' line and the address/term framing make it clearly distinct from get_provision and get_law.

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 concrete when-to-use direction ('Call it before explaining what a provision means') and explains the two operating modes: unset address lists every defined term, while address returns only the definitions that apply in that provision. It does not explicitly route away from siblings such as search or get_provision beyond the address-format cross-reference, so it stops short of full alternative naming.

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 safety hints in annotations, the description clarifies specific behavioral traits: which metadata is included (translation percentage), the structure of the description (who it applies to/doesn't to), and the logic for the 'aspect' filter and outline generation.

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 extremely dense and lengthy, which lowers its score for conciseness. However, this length is necessary to convey the complexity of the output and parameter logic.

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 definition is highly complete for a complex data retrieval tool. It clarifies the output data structure, the functionality of the 'outline' parameter, and the exact scope of the legal descriptions returned.

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?

Although schema coverage is 100%, the description provides essential semantic context for the inputs. It explains the various allowed formats for the `law` parameter (slug, ID, English/Japanese titles) and defines the conceptual meaning of every `aspect` enum.

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 tool description specifies retrieving a comprehensive description of a Japanese law, clearly differentiating it as a deep-dive content retrieval tool, unlike list or search operations among siblings.

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 doesn't explicitly state when *not* to use the tool, it provides extremely detailed context about the scope of the retrieved information (e.g., versions, enforcement claims), helping the user understand the right depth of usage.

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 layers on real behavioral detail: truncation at a provision with continued.cursor resumption, asOf refusal semantics ('never answered with the nearest text'), the englishWhose provenance taxonomy, and the citation rule to link the site url rather than e-Gov. That is context an agent could not infer from structured 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?

Purpose is front-loaded and the later sentences on pagination, versioning and citation each carry distinct operational value. The Japanese and English purpose sentences say the same thing, which is pure duplication for a bilingual-capable model and the main thing keeping this from a 5.

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 seven-parameter tool with versioning, pagination and provenance subtleties, the description covers everything an agent needs to call it correctly and to use the answer responsibly. The return-value detail is arguably redundant against the output schema, but the englishWhose and citation guidance is not something the schema conveys.

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 a 3 is the floor, but the description adds genuine meaning: worked examples of both the slug and Japanese-address forms, the cursor round-trip ('continued.cursor, passed back as cursor with the same address'), and what references='lists' actually returns. It stops short of full coverage since asOf/version interactions are mostly restated from 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 — 'Read the text of an article, paragraph or item of a Japanese law' — and immediately scopes it ('One article, paragraph or item of a law, with everything under it'), which distinguishes it from get_law (whole statute), get_definitions, and get_citing_provisions. An agent can route to it 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?

Gives a concrete trigger ('to quote or explain it: the wording may have changed since a model learned it') and routes related needs to siblings ('get_citing_provisions has them all', 'search and get_law hand out' addresses). It never states an explicit when-not-to-use-this case, so it falls 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?

Annotations already declare readOnly, idempotent, non-destructive, non-open-world. The description goes beyond that by explaining the meaning of the day values (on/by/open), ordering ('those with no day yet last'), and pagination behavior. It does not discuss auth, rate limits, or error conditions, so it is not exhaustive, but it adds meaningful behavioral 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?

Front-loaded with the purpose in the first sentence. Dense but mostly earns its place; the Japanese snippets add some visual bulk without much functional value to an agent, and the parenthetical about day values is a bit compact, but overall it is efficient.

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 an output schema exists, the description need not explain return values, and it still covers defaults, ordering, pagination, and routing to get_amendments. An agent has everything needed to call 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?

Schema coverage is 100%, so baseline is 3. The description adds interpretation beyond the schema: the semantic difference between 'since' and 'until' defaults, the meaning of the day statuses, and the requirement that cursor be reused with the same since/until/law/topic arguments.

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 — what changes in Japanese law between two days — with scope options (every law, one law, one topic). It also explicitly names the sibling get_amendments and what it is for, so an agent can distinguish 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?

Explicitly covers defaults ('since defaults to today'), the no-until behavior, pagination instructions ('continued.cursor, passed back as cursor with the same arguments'), and the alternative for per-provision detail ('call get_amendments'). The when-to-use vs when-not-to-use is fully specified.

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 the description's real contribution is the exhaustiveness contract: the unfiltered list is the complete set of holdings, which is what licenses a negative answer, and total/kinds describe the counts returned. It spends some of that budget restating the per-law fields (title, kind, number, url) that the output schema already covers, and the clause "held all the laws held" is garbled enough to be ambiguous.

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 purpose and the "find the name to pass as law" framing are front-loaded, and much of the length is load-bearing (the negative-case rule, the get_law handoff). It loses a point because the middle sentence is a single over-stuffed clause that mixes filters, returned fields, and counts, and one phrase is malformed.

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 present, the description does not need to explain return values, and it still notes the counts it exposes. It covers the filtered-list workflow and the crucial 'not held' inference; the only gap is that it never states what the tool does when filters match nothing versus when the law genuinely does not exist.

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 three parameters are enums with meanings spelled out, so the description is working against a high baseline. It paraphrases the same filters (kind, topic, query words) and glosses the Japanese labels (法律 Act, 政令 Cabinet Order, 省令 Ministerial Order) but adds no constraint the schema lacks, such as how filters combine or whether they intersect.

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?

Uses a concrete verb+resource ("Every law japanlaw.org holds") and explicitly scopes the response to a summary listing (title, kind, law number, url) while naming the sibling that carries the full text ("get_law has the rest"). An agent can distinguish list_laws from get_law and search without inspecting 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 a positive use case ("Check whether japanlaw.org holds a law, and find the name to pass as law") and an explicit fallthrough to get_law, plus a when-not rule: a law absent from the full list is not held, so report that rather than reciting text from memory. The exclusion even covers the edge case of 条例 ordinances, which the kind enum cannot express.

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?

Adds substantial behavior beyond the annotations: result ordering, lawsTotal, one result per matching article at its best-matching paragraph/item, snippet and designation fields, terms and concepts, and the fallback to list_laws. Annotations already cover read-only/idempotent safety, and the description does not contradict them.

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 key purpose and usage rules are front-loaded, and most sentences carry useful operational detail. It is long and includes bilingual example repetition, but the complexity of the search semantics justifies most of the length.

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 five parameters, an output schema, and rich annotations, the description is complete enough for an agent to invoke it correctly. It covers query language behavior, law scoping, result structure, and the list_laws fallback.

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 meaning: Japanese-containing queries search Japanese text, non-Japanese queries search stemmed English text, every word must be at least two characters, and the law parameter restricts searching to one named law.

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 action and resource: finding Japanese statutory provisions for natural-language questions, with concrete examples. It also distinguishes itself from sibling tools by explaining that result ids are passed to fetch or get_provision.

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?

Explains when to use this tool, how Japanese versus English queries behave, and what to do when a named law returns nothing: check list_laws and say the law is not held rather than answer from memory. It also names related tools for next steps.

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