چیستارا — Iranian Legal Corpus

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds substantive domain behavior: the fee is shared equally among arbitrators, the 1.5 billion rial cap, and the 5–30 million rial range for non-financial claims. No error/edge behavior is described, hence 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?

A single dense sentence that is front-loaded with the purpose and the governing bylaw, and every clause (bands, cap, sharing rule, non-financial handling) carries weight. It would read more easily if split, but there is no wasted 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?

No output schema exists, yet the description fully specifies the fee logic an agent needs to interpret the result. The one residual ambiguity is the rial cap versus the Toman-denominated claim_toman input, which is disclosed but not reconciled, keeping 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% (baseline 3), but the description goes further by explaining how the fee relates to parameters — the marginal bands apply to the claim amount, the result is shared equally among arbitrators, and non-financial claims use a flat per-arbitrator range. This adds real meaning to both claim_toman and arbitrators.

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 (calculate حق‌الزحمهٔ داوری), anchors it to a named bylaw (approved 1401/06/05) and outlines the exact computation bands and cap. An agent can distinguish this fee from calculate_lawyer_fee, calculate_diyeh and the other calculate_* 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?

Gives a concrete applicability condition — it applies when the arbitrator and the parties have not agreed a fee — which tells the agent the statutory-default scenario. It does not name alternatives or an explicit when-not-to-use, 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?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower, yet the description adds substantial context: the data source (Central Bank official monthly table), the exact computation, the graceful-degradation behavior when data is missing, and the Jalali date convention.

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 operation and legal basis, then the formula and fallback rule. Dense but every element earns its place; only the mixing of Persian/English legal terms adds minor parsing overhead.

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 does need to convey return behavior: it says a number is returned when the table is loaded and a limitation message plus link otherwise. It stops short of specifying the result's unit or precision, a minor gap for a six-parameter calculator.

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, but the description adds meaning the schema does not: it ties the month parameters to the formula (index of payment month ÷ index of due month) and explains why start_month matters (ruling 850 reads that month's index). The Jalali note reinforces the schema's date semantics.

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 (calculate) and resource (late-payment damages / خسارت تأخیر تأدیه), names the governing legal basis (art. 522 ق.آ.د.م, ruling 850), and gives the exact formula used. This clearly separates it from the sibling calculators (diyeh, mahrieh, arbitration fee, etc.).

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 tells the agent what to do when the CBI table is unavailable (return the limitation plus the official link, never approximate), which is genuine invocation guidance. It does not, however, explicitly state when to prefer this tool over sibling calculators or what conditions make it inapplicable.

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, so the safety profile is covered. The description adds real value beyond that: it discloses that the tool auto-applies the CURRENT official rate, uses statutory fractions, and returns the governing article plus rate source. Does not cover edge/failure behavior, but the added context is substantial.

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?

Three tight sentences, front-loaded with purpose, then usage directive, then return shape. Every sentence earns its place with no redundancy.

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?

No output schema exists, and the description compensates by describing the return (amount + governing article + rate source). Given 100% schema coverage and a rich annotation set, the definition is largely self-sufficient; only minor gaps around ambiguous/multi-input cases remain.

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 per-parameter meaning is fully documented in the schema. The description adds only domain framing (current rate, statutory fractions) rather than parameter-specific guidance, so the baseline of 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 (Calculate) and a specific resource (دیه / blood money for bodily injury), which is naturally distinct from the sibling calculators (mahrieh, inheritance, various fees). An agent can tell exactly what this tool computes 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?

Explicit directive: 'ALWAYS use this instead of computing دیه yourself', with the reason (rate changes yearly, fractions are statutory). Strong when-to-use guidance, though no explicit when-not or named alternatives (e.g. when to prefer a different calculator for a non-injury case).

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 the safety bar is low; the description goes further by disclosing the actual computation behavior (5% of the judgment sum, half on settlement, zero if complied within ten days, 10% of three months' rent). It stops short of stating rounding, currency output, or result format.

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 definition and the rate before any caveats, and every clause carries a distinct rule. It is, however, one very long compound sentence whose nested statutory clauses would be easier to scan as a short list.

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, one required, no nesting, and annotations that already cover the safety profile, the description supplies the substantive legal context an agent needs to choose `kind` and `timing` correctly. The remaining gap is that no output schema exists, yet the description never indicates the shape or currency of the returned fee.

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 baseline is 3; the description adds genuine meaning by explaining what each branch costs rather than just naming the enum values (e.g. eviction = 10% of three months' rent, shora_settlement = art. 27 exemptions). It does not spell out the exact timing/shora_timing semantics beyond 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?

States a specific verb (Calculate) and a precise, named resource (نیم‌عشر اجرایی / state execution fee on a civil judgment), then enumerates the exact statutory bases (art. 158, 159, 160, art. 27). This is clearly distinguishable from siblings such as calculate_arbitration_fee, calculate_litigation_fee, and calculate_stamp_duty.

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 implicitly tells the agent which branch applies by tying each rate to a factual scenario (money judgment, eviction, non-financial, Shora settlement), which is enough to pick a value of `kind`. However it never states when to prefer this tool over the neighboring fee calculators, nor any exclusions or prerequisites.

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 safety (readOnly, idempotent, non-destructive), so the bar is lower, yet the description adds rich behavioral context: the marginal ladder for valuation, a hard 1,350,000,000 rial cap, percentage add-ons for named subject matters, and the crucial caveat that 'residual' returns only the floor of a 20,000,000–100,000,000 rial range. It also discloses the legal articles driving the behavior, which goes well beyond 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?

The description is a single dense paragraph but is front-loaded with the core purpose and then systematically covers each kind, exclusions, and caveats. Every sentence carries legal or operational information; it could be easier to scan with structure, but it is 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?

For a complex, annotation-rich calculator with no output schema, the description is nearly complete: it explains the three modes, caps, add-ons, exclusions, and the limited return of 'residual'. It does not explicitly state the return format for 'valuation' and 'evidence', though a numeric fee is strongly implied, leaving a minor gap.

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 description coverage, the baseline is 3, but the description adds meaning beyond the schema by explaining that 'valuation' is a marginal ladder on the subject value with a per-expert cap, and by tying modifiers to specific articles and percentage effects. The schema already documents each parameter fully, so this is incremental but real added value.

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 precise verb ('Calculate') and resource ('official تعرفهٔ دستمزد کارشناسان رسمی دادگستری'), and pins the legal instrument (1405 tariff superseding prior ones). It clearly distinguishes the three supported kinds (valuation, residual, evidence) from each other and from the dozens of unmodeled specialties, so an agent can immediately tell what the tool does and does not cover.

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 strong context for when each 'kind' applies, and explicitly bounds scope by warning that other specialties (arts. 13–55) are not modelled. It even says 'Never guess a court expert's statutory fee,' which is useful. However, it does not name or route to sibling tools like calculate_lawyer_fee, leaving the choice of this calculator versus other fee calculators implicit.

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, non-destructive, closed-world behavior, so the description only needs to add what they cannot. It does add real behavioral context: output is exact fractions that always sum to the estate, and out-of-scope heirs produce a refusal carrying the governing articles rather than an estimate. It stops short of describing return structure, precision/rounding, or currency handling.

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 dense sentences, front-loaded with the core purpose before the scope restriction, with no filler. The parenthetical Persian legal terms carry genuine signal, though the second sentence is long and packs the refusal policy, its rationale, and a directive into one breath.

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 an 11-parameter calculation tool with no output schema, the description supplies the key contract (fractions summing to the estate, refusals with citations) but never sketches the shape of a successful response — per-heir breakdown, article citations, or units — which the missing output schema leaves undocumented.

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 baseline is 3; the description earns an extra point by framing the parameter space conceptually — spouse/parents/children are the accepted inputs, and the mother's حاجب (mapped to sibling_count/brother_count/sister_count) is a recognized input dimension. It adds meaning beyond the terse per-field schema text.

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 ('Calculate Iranian inheritance shares ... of the spouse, parents and children') plus the governing legal basis (arts. 861–949). It is unmistakably distinct from the fee/tax/lookup siblings in the toolset, and even enumerates the doctrines handled (رد، نقص، mother's حاجب).

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 states the boundary condition: grandchildren and class-2/3 heirs are refused, 'never estimated — do not compute those yourself,' which tells the agent when not to expect a result and not to substitute its own math. It does not, however, name the sibling tool (e.g., lookup_law_article) to route to for those refused cases.

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 the full safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description only needs to add context. It does add two useful facts: the default no-argument behavior and the legal provenance (budget law 1405, table 16). It says nothing about return units, currency, or whether the sum is itemized.

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 calculation and its legal basis, followed by the default-behavior caveat. The item enumeration is long but functionally useful for matching a user's request to this tool. No filler 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?

A read-only, single-parameter calculator with no output schema; the description covers what is summed and what happens when no services are supplied. The remaining gap is the return shape (total only vs. itemized breakdown) and currency units, which an agent would have to discover by calling 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% and there is a single optional parameter, so the baseline is 3. The description goes beyond the schema by explaining the consequence of omitting 'services' (the whole schedule is returned), which the schema's mere 'not required' does not convey. Repeating an id to count twice is documented in the schema rather than the description.

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 ('sum') and a well-scoped resource ('fixed judicial service fees of 1405, budget law 1405, table 16'), and enumerates the covered items (criminal complaint, criminal record certificate, notice service, objections, appeals, Administrative Justice Court petitions, translation seals). It is legible against most siblings, though it never explicitly distinguishes itself from the closely related calculate_litigation_fee.

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 gives one concrete usage cue — 'Without services, returns the whole schedule' — which tells the agent it may call with no arguments to get the full fee table. It offers no guidance on when to prefer this tool over calculate_litigation_fee or calculate_execution_fee, so selection among the fee calculators remains implicit.

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 this as a read-only, idempotent, non-destructive computation, so the safety profile is covered. The description adds genuinely new behavioral context: the result is a deterministic tariff figure that does not scale by winning or losing, and `stage` is a proportional share of the whole-case fee. It does not state what the returned value looks like or its units, which is the remaining 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?

Front-loaded with the core computation model (ladder vs. range), then the stage-share rule, then the outcome-independence caveat and a routing imperative. Dense with statutory citations but each sentence carries a distinct, actionable fact; slightly citation-heavy 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?

For a complex 8-parameter, high-enum tool with no output schema, the description covers the branching logic (which case types use which tariff article) and the fee's outcome-independence, which is what an agent needs to pick parameters correctly. The only omission is what the tool returns and in what units, though the schema's Toman-denominated fields make this largely inferable.

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 is 3, but the description adds cross-parameter logic the schema does not: it explains the ladder-vs-range split that determines whether case_value_toman even matters, and clarifies that stage is art. 21's share of the whole-case fee. That dependency structure meaningfully improves correct parameter selection.

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 (calculate) and resource (حق‌الوکاله / lawyer's statutory fee) and pins the exact source of truth (آیین‌نامهٔ تعرفهٔ حق‌الوکاله 1398/12/28), which implicitly separates it from the other fee calculators in the sibling set. It never names a sibling directly nor says which calculator to use for court costs, arbitration, or expert fees, so sibling routing is left to inference.

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 conditional usage: financial claims follow the art. 9 ladder, while family/non-financial/criminal/admin matters are a value-independent min–max range, and the closing imperative 'Never guess a lawyer's statutory fee' tells the agent to always route here rather than estimate. It stops short of explicit when-not or alternative-tool direction (e.g., vs. calculate_litigation_fee).

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, and destructiveHint, so the safety profile is covered. The description adds useful context about using 'current official percentages' and statutory rates, but it does not disclose what the function returns or how invalid parameter combinations are handled. This is adequate but not rich.

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 two sentences with no filler. It front-loads the action and scope, then adds a concise usage rationale. Every sentence earns its place.

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 high schema coverage and annotations covering safety, the definition is mostly complete. However, the description's 'monetary claim' framing ignores the non_financial case_type, and there is no output schema or return-format hint, so an agent handling a non-financial claim could be uncertain.

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 documents all parameters, their enums, and dependencies. The description reinforces the stage terminology in Persian but adds no new parameter-level semantics beyond what the input schema provides.

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 verb and resource: 'Calculate Iranian court filing fees (هزینهٔ دادرسی)' and names the stages (بدوی / تجدیدنظر / فرجام), which distinguishes it from sibling calculators. It loses a point because it says 'for a monetary claim' even though the schema also supports non_financial cases, making the stated scope slightly narrower than what the tool actually handles.

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 gives a clear reason to invoke the tool: 'Use this instead of estimating — the rates are statutory and stage-dependent.' This establishes the context for when it should be used, though it does not mention when not to use it or explicitly name an alternative sibling 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?

Annotations already signal readOnly, idempotent, and non-destructive behavior, and the description adds meaningful context: rates are sourced live from the database rather than approximated. It also discloses that without marriage_year the cash portion stays nominal and must not be labeled 'ارزش روز', which is important behavioral detail not present in the 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?

The description is three sentences with no filler. The purpose is front-loaded, the data-source warning is explicit, and the conditional user input requirement is stated clearly. Every sentence earns its place.

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 calculator with no required parameters and no output schema, the description explains the inputs, the external data dependency, and the user question the agent should ask. It could explicitly state the return format or currency, but the 'Toman' parameter and the phrase 'present-day value' make the output reasonably inferable.

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 adds value by clarifying the conditional role of marriage_year: it is required whenever there is a cash portion, and omitting it leaves the cash unadjusted. This goes beyond the schema's simple 'needed to adjust' phrasing.

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: calculate the present-day value of مهریه from coin count at live market rate plus cash adjusted by the Central Bank index. The term 'مهریه' and the cited legal provision clearly distinguish this from the sibling calculators such as calculate_delay_penalty and calculate_diyeh.

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 gives clear procedural guidance: never guess coin prices or the adjustment index because the tool reads them from the database, and ask for marriage_year when a cash portion exists. It does not explicitly list when-not-to-use alternatives, but the calculation context is specific enough that an agent can infer when this tool applies.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by specifying that the calculation must use the official 1405 tariff and must never be estimated, which informs the agent that exact official values are required rather than approximations. This goes beyond what the schema and annotations state.

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 three short sentences with no filler. It front-loads the core purpose, immediately gives the critical sibling distinction, and ends with a concise behavioral rule. Every sentence earns its place.

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 three-parameter calculation tool with no output schema, the description gives enough context about source (1405 tariff), exactness, and sibling differentiation. It does not explicitly describe the return shape, but for a fee calculator the output is fairly inferable. The rich schema and annotations fill the remaining gaps.

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 already provides meaningful descriptions for doc_type, amount_toman, and obligor_count, including rate-based versus fixed-fee distinctions. The description does not add parameter-level semantics, but the baseline of 3 applies because the schema carries the full weight.

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 ('Calculate'), a clear resource (حق‌التحریر, the notary fee), and a specific basis (the official 1405 tariff for دفاتر اسناد رسمی). It explicitly differentiates from حق‌الثبت by naming calculate_stamp_duty, so an agent can distinguish this from its most similar sibling 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?

The description gives an explicit when-not/alternative statement: 'Distinct from حق‌الثبت (use calculate_stamp_duty for that).' It also instructs the agent to 'Never estimate the tariff', which sets a clear execution expectation. This is sufficient routing guidance within the calculator sibling group.

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 establish that the tool is read-only, idempotent, and non-destructive, so the description only needs to add context. It adds that the calculation uses the current official minimum wage and applies under the Labor Code, which is useful, but it does not disclose output format, rounding, or statutory-cap behavior.

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 two sentences with no filler: the first explains what the tool computes and the legal/minimum-wage basis, and the second gives a clear usage directive. Every phrase earns its place.

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 six-parameter calculation with no output schema, the description gives a clear high-level capability but omits what the response contains, how years and months combine, and how contract_type affects the result. The fully documented schema mitigates much of this gap, making it adequate but not fully complete.

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 documents all six parameters. The description mentions the entitlement categories but adds no parameter-specific semantics beyond the schema, so the baseline score 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 states a specific verb ('Calculate') and a specific resource ('Iranian employee's end-of-service entitlements'), listing the main components (حق سنوات، عیدی، مانده مرخصی) and the governing law. This clearly separates it from the many calculate_* siblings for fines, fees, and other legal amounts.

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 says to use this tool instead of computing by hand, which is a direct usage signal. It does not name sibling alternatives or exclusion cases, but the subject matter is specific enough that an agent can route to it without ambiguity.

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, so the safety profile is covered. The description adds real behavioral context beyond that: the 0.5% rate, the fixed-tariff regime, and the explicit refusal of marriage/divorce and company registration, telling the agent what will not be computed. It stops short of describing output format, but for a deterministic calculator that gap is small.

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 definition and rate in the first sentence, with the sibling disambiguation and refusals following. It is dense with parentheticals and legal citations, but every clause carries routing or scope information; only slight tightening would help.

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 calculator with no output schema and full schema coverage, the description supplies scope, statutory basis, rate, refusals and sibling routing — enough for correct invocation. It omits any note on output shape or rounding, which is the only remaining gap.

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 doc_kind, amount_toman and count are already documented in the schema, making baseline 3 appropriate. The description reinforces that amount_toman applies to 'a financial document' and mentions the 0.5% rate, but adds no syntax, units or boundary detail the schema does not already supply.

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 (Calculate) and a precisely named resource (حق‌الثبت, the STATE registration duty on a notarised document), and explicitly distinguishes it from the sibling calculate_notary_fee. The legal grounding (art. 123, art. 124) makes the scope unmistakable.

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 both the alternative and the condition that selects it: 'Distinct from حق‌التحریر (the notary's own fee — use calculate_notary_fee).' It also states when the tool does NOT apply (marriage/divorce and company registration are refused), which is exactly the when-not guidance this dimension rewards.

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 establish read-only and idempotent behavior. The description adds genuinely useful behavioral context: inheritance has no general monetary exemption, heir class and asset kind affect rates, pre/post-1395 death dates differ, and property assessment uses valori not market price. This goes beyond the structured annotations without contradicting 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 description is compact and front-loaded, with the tax types in the first sentence and the most critical caveats immediately after. Every sentence contributes useful information, and there is no filler or 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?

For a tool with 8 parameters and four tax modes, the description covers the trickiest legal conditions and tells the agent when to ask for more information. The absence of an output schema means the return format is not documented, but the tool's purpose as a calculator makes the result type inferable, so this is only a minor gap.

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 baseline is 3. The description adds meaning beyond the schema by clarifying that the inheritance value has NO general monetary exemption and that the property value_toman must be the valori-based amount rather than market price. This helps an agent interpret the numeric parameters correctly.

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 clear verb and resource: calculate Iranian taxes for salary, property-transfer, inheritance, or rental. It enumerates the exact tax types, making the tool's scope immediately understandable, but it does not explicitly differentiate from the sibling calculate_inheritance, so it falls just short of fully distinguishing 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?

The description gives explicit usage context: for inheritance, the agent should ask before calling because death-date era changes the calculation, and property tax is based on valori rather than market price. It does not state when-not-to-use the tool or name alternative tools, so it lacks explicit exclusions.

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, closed-world), so the description is free to add data-interpretation behavior instead: rows carry a `unit` field where «rials» means Rial and «درصد» means percent, with an explicit warning never to report a percentage as a Rial amount. It does not add auth, rate-limit or error behavior, so a 4 rather than 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 and each sentence carries a routing rule or an interpretation caveat that earns its place. Slightly dense and mildly repetitive in the 'ALWAYS use this instead of recalling' reinforcement, which keeps it just short of 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?

With no output schema, the description must carry return-value guidance, and it does the most important part by explaining the `unit` field and the Rial-vs-percent trap. It still does not describe the rest of a row's shape (value, year, provenance), so it is strong but not fully complete for a 2-param lookup with no 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 the baseline is 3, but the description supplies additional concrete rate_type keys not present in the schema examples (court_fee_*, salary_tax_exemption_annual, sanavat_daily) and clarifies the semantics of the returned unit field. This is genuine added meaning beyond the two described parameters.

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 (fetch) and resource (official Iranian yearly rates) and enumerates the concrete keys it serves: min_wage, court_fee_*, salary_tax_exemption_annual, sanavat_daily. It explicitly differentiates itself from siblings by naming calculate_delay_penalty, calculate_mahrieh, calculate_lawyer_fee and calculate_diyeh as the correct homes for those figures.

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 when (always prefer this over recalling a rate, since yearly figures are what models misremember) and explicit when-not with named alternatives for delay damages, mahr, lawyer fees and diyeh. Nothing about tool selection is left to inference.

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 only cover the safety profile (readOnly, idempotent, non-destructive). The description goes well beyond that, disclosing the return contract (section_path, clauses, summaries, keywords, topics, answers_in_text, related_articles) and a critical caveat that summary/summary_plain are machine-written and must never be quoted as law, plus the part-continuation behavior.

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 one long paragraph but front-loaded and dense: purpose first, then usage directive, then return contents. Every clause adds information, though the parenthetical enumeration of return fields is somewhat heavy and 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?

With no output schema, the description bears the full burden of explaining returns, and it does so thoroughly, including which fields are answers, which are related articles with source_urls, and explicitly which fields are NOT statute text. An agent has everything needed to call it and quote responsibly.

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, article_number and part are already documented in the schema, including the part-continuation convention. The description adds citation-format examples ('بند ۲ ماده ۱۹۰') but little that the schema does not already carry, 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?

The first sentence gives a specific verb+resource ('Fetch the VERBATIM text of a specific article') and adds the operative precondition ('when you already know the law and the article number'). This distinguishes it functionally from search_law_articles, though the alternative is never named explicitly.

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 cleanly states the context of use (known law + article number, for verifying wording before quoting) and a strong directive ('Never paraphrase an article from memory'). It stops short of naming the sibling search tool or spelling out the inverse condition (use search when you don't know the number), so there is no explicit exclusion.

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 this read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful context that deadlines differ by case type and that the agent must never answer from memory, which informs expected behavior beyond the 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?

Three sentences with no filler: purpose and examples, explicit when-to-use, and a critical caution about not answering from memory. The most decision-relevant information is front-loaded.

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 read-only lookup with full schema documentation and no output schema, the description is sufficient: it states inputs, outputs, and usage context. It could add a note about returning a list of all procedures when procedure_name is omitted, but the schema already conveys this.

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 the schema already documents both parameters, including enum values, the optional procedure_name, and the behavior when omitted. The description adds context like 'by case type' and example procedure names, but this does not substantially go beyond the structured 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 names a specific action ('Look up Iranian procedural deadlines') with concrete examples (مهلت تجدیدنظر، واخواهی) and states the output includes governing law and article. It is clearly distinct from sibling calculators and article lookups, though it does not explicitly name a differentiating sibling like lookup_statute_of_limitations.

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 says 'Use when the user asks how long they have for a procedural step,' giving clear invocation guidance. It does not explicitly say when not to use it or mention alternatives, but the condition is sufficiently specific for an agent to route correctly.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by noting the result includes the governing article and by instructing the model not to invent sentencing ranges from memory. 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?

Three tight, purposeful sentences: action and scope first, then trigger conditions, then a guardrail. Every sentence earns its place and nothing is redundant or 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?

For a simple two-parameter lookup tool with solid annotations and full schema coverage, the description provides enough context: what it returns (statutory punishment plus governing article), when to use it, and how to behave (never from memory). It could mention sibling alternatives, but complexity is low and no critical 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 description coverage is 100%, so the schema already documents both parameters (crime_type and crime_grade). The description adds no parameter-specific guidance beyond mentioning 'crime' generally, so it stays at the baseline without compensation.

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 a specific verb ('Look up') and a specific resource ('statutory punishment for an Iranian crime'), enumerates the covered punishment types (imprisonment, fine, lashes, قصاص, دیه), and mentions the governing article. This clearly distinguishes it from generic law-article lookup or calculation tools.

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 states when to use the tool: 'when the user asks what the punishment for a crime is, or for criminal-risk analysis.' It also adds a hard exclusion: 'Never state a sentencing range from memory.' It does not name sibling alternatives such as lookup_law_article, but the usage context 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=true, idempotentHint=true, and destructiveHint=false, so the safe read-only nature is covered. The description adds meaningful behavioral scope by specifying that it covers Iranian limitation periods across prosecution, execution, and filing deadlines, which is useful context beyond the 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?

The description is two sentences long, front-loads the core function, and contains no filler. The usage trigger is placed in the second sentence without redundancy.

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 lookup tool with one required enum field and read-only annotations, the description covers the essential context: what is checked, which deadlines, and when to invoke it. It does not describe return format, but no output schema exists and this omission is acceptable given the tool's simplicity.

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 case_category and crime_grade are already documented in the schema. The description restates the idea of a case category but adds no new semantic detail about the parameters, such as how crime_grade interacts with the criminal category.

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 ('Check'), a clear resource ('Iranian limitation periods'), and the three deadline types covered (prosecution, execution, filing). It also ties the tool to case categories, making its function distinct from the calculator siblings and lookup_law_article.

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 the agent when to use the tool: when the user asks whether a claim is time-barred or how long they have to file. It does not explicitly name alternatives or list when not to use it, but the trigger conditions are concrete and actionable.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: the non-binding nature of advisory opinions and the return shape ('opinion number, date, and excerpt with source_url'). No contradiction with the 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?

The description is three sentences with no wasted words. It leads with the core purpose, then quickly gives the usage signal, a citation caveat, and the return fields. Every sentence earns its place.

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 helpfully states what the tool returns ('opinion number, date, and excerpt with source_url'). It also covers the key usage context and the legal status of the results. Minor omissions like pagination or result ordering are acceptable for a simple 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?

The schema provides a Persian query example and default/min/max for limit, but the description itself adds no parameter-level detail. With 50% schema description coverage, the description does not compensate for the undocumented limit parameter, though limit's semantics are largely inferable from its name and bounds.

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 ('Search') and a precise resource ('advisory opinions ... of the Judiciary's legal department'). It clearly distinguishes this from sibling tools like search_case_law, search_circular, and search_law_articles by emphasizing 'official, citable interpretation of Iranian statutes.'

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 says 'Use when the user asks how a provision is officially interpreted, or to support an argument.' It also warns that advisory opinions are 'authoritative guidance, not binding law' and instructs the agent to say so when citing. It does not name alternative tools or provide explicit when-not-to-use conditions, 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?

Annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond annotations: it covers binding precedent and returns excerpts with source URLs. Since there is no output schema, this return-format disclosure is valuable, though sorting or pagination behavior is not 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 two sentences with no filler. It front-loads the resource and purpose, then gives a use case, then states the output shape. Every sentence earns its place.

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 read-only search tool with two parameters, the description covers what it searches, when to use it, and what it returns. A minor gap is that it does not explicitly distinguish itself from the many lookup/search siblings, but the phrase 'how courts have actually decided an issue' supplies enough context for an agent to route 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 query parameter is described in the schema as 'The legal issue, in Persian,' and the limit parameter is constrained to 1–5 with a default of 5, making its purpose inferable. However, the description adds no additional parameter guidance beyond what the schema already provides, and limit's semantics are not explicitly stated despite only 50% schema description coverage.

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 verb and resource: 'Search 31,000+ Iranian court rulings and آرای وحدت رویه (binding precedent).' It also signals what it returns, 'excerpts with source_url,' and distinguishes it from statutory or advisory-opinion tools by saying it covers 'how courts have actually decided an issue.'

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 says to use this tool 'when the user asks how courts have actually decided an issue, or for precedent supporting a position.' This gives clear when-to-use guidance, though it does not name specific sibling tools or say when not to use it.

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 this as read-only, idempotent, and non-destructive. The description adds useful behavioral context by stating that it returns excerpts with source_url, which is valuable given there is no output schema. It does not contradict the 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?

The description is a single, well-structured sentence that front-loads the core purpose, then adds the authoritative source context, and ends with the return behavior. Every phrase contributes meaning with no redundancy or 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?

For a straightforward search tool with two simple parameters, the description covers the purpose, the domain of interest, and the return format. The annotations cover the operational safety profile, and the schema covers parameter constraints, so nothing essential 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 input schema describes the query parameter as 'Topic, in Persian,' and the limit parameter has default/min/max constraints, so the schema carries most of the semantic weight. The description does not add further parameter-level detail, but the available schema information is adequate for this simple two-parameter tool.

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 a specific verb ('Search') with a clearly identified resource: official circulars and directives from judiciary and government bodies. It also highlights that these are the source of current official RATES and procedures, which distinguishes it from sibling tools like search_case_law or search_law_articles.

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 clear context for when to use this tool by identifying it as the source of current official rates and procedures. It does not explicitly name alternatives or state when not to use it, but the contrast with calculator/lookup siblings is reasonably 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 cover readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds useful behavioral context beyond annotations: it is semantic + keyword search, returns exact article number, law title, excerpt, and source_url, and warns about amended articles. This extends the agent's understanding of expected behavior without contradicting 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?

The description is reasonably compact: two sentences, front-loaded with the tool's core function and followed by usage direction and return details. The all-caps directive is emphatic but purposeful. No sentence is filler, though the description could be trimmed slightly 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 there is no output schema, the description appropriately lists the key returned fields: article number, law title, excerpt, and source_url. It also provides the core use context and citation expectations. It does not mention how to choose between alternatives or edge cases like amended-article handling, but for a read-only search tool with annotations already covering safety, this is largely complete.

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 67%, so the schema already documents query and law_filter. The description adds that search is semantic + keyword and that it covers full text, which helps interpret the query parameter. However, it does not elaborate on limit behavior or law_filter semantics beyond the schema, and the description does not compensate heavily for the undocumented limit parameter.

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 a specific verb and resource: 'Semantic + keyword search across the full text of Iranian statutes.' It also enumerates covered laws and 60,000+ articles, making the resource concrete. It does not explicitly name or contrast sibling tools like lookup_law_article, but 'search' vs the family of 'lookup' tools provides implicit differentiation.

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 gives explicit when-to-use guidance: 'USE THIS BEFORE ANSWERING ANY QUESTION ABOUT IRANIAN LAW — do not rely on memory.' It also explains why, citing misremembered article numbers and amended-article traps. However, it does not state when a user should prefer a sibling tool such as lookup_law_article or search_case_law, so exclusions/alternatives are missing.

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