چیستارا — Iranian Legal Corpus

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

Annotations already signal read-only, idempotent, and non-destructive behavior. The description adds meaningful constraints beyond that: the index series must be official and never approximated, and all dates must be interpreted as Jalali. This is useful behavioral context 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?

Three short sentences with no filler. The most decision-relevant facts—legal basis, official-data warning, and Jalali dates—are front-loaded and 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 calculation tool with fully documented parameters, the description is sufficient to select and invoke it correctly. It does not describe the return value, but no output schema exists and the computed damage amount is a natural output, so this is 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 all six parameters are already documented. The description does not add parameter-level meaning beyond the schema; it only reinforces the Jalali date convention already stated in 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 ('Calculate'), the exact legal basis (art. 522 ق.آ.د.م), the data source (Central Bank price index), and the date system (Jalali). This clearly distinguishes it from sibling calculation tools like calculate_diyeh or calculate_lawyer_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 clearly implies when to use this tool: for late-payment damages under Art. 522 using the official Central Bank index. It does not explicitly name alternatives or exclusions, but the legal-article anchor gives enough context to route an agent correctly among the calculate_* siblings.

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 mark it read-only and idempotent; the description adds that it uses the current official rate, that the rate changes every Persian year, that fractions are statutory, and that the result cites the governing article and rate source. This directly addresses how the tool behaves and why manual calculation is unreliable, without contradicting any annotation.

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: the purpose and method are first, the usage mandate and rationale second, and the output details last. Every sentence contributes either to selecting the tool or understanding its result.

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 calculation tool with no required parameters, a richly documented schema, and safety annotations, the description covers the key agent-facing concerns: why this tool must be used, what rate applies, and what the result contains. It does not specify edge-case behavior or error handling, but no output schema exists and the description provides the essential usage context.

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

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

Schema description coverage is 100%, so the schema documents every parameter, including the enum meanings and the 'fraction only when no injury_type fits' rule. The tool description adds no parameter-level information beyond what the schema already conveys, 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?

The description names the exact operation ('Calculate دیه for a bodily injury'), the source of truth ('CURRENT official rate' and 'قانون مجازات اسلامی'), and the output ('Returns the amount with the governing article and the official rate source'). It is immediately distinguishable from sibling calculators because it is the only one for statutory blood money.

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

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

It gives a strong when-to-use directive: 'ALWAYS use this instead of computing دیه yourself,' supported by the reason that the full-دیه rate changes annually and fractions are statutory. It does not explicitly name sibling alternatives or state exclusion 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 cover the safety profile (read-only, idempotent, non-destructive). The description adds useful behavioral context by specifying the governing legal articles, the inclusion of حجب نقصانی reductions, and the reliability rationale, but it does not disclose return format or assumptions about debts/wills. For a computation tool with strong annotations, this is adequate though not exhaustive.

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 tightly written sentences: the first carries the operational scope and legal citation, the second gives a concise usage directive. There is no filler and the most important facts are 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?

The tool is legally complex and has no output schema, but the description provides strong legal anchoring and an explicit reliability/usage directive. The main omission is the return format, though it is reasonably inferable from 'inheritance shares'; optional-parameter defaults are also not stated, but the schema covers parameter meanings well.

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 eight parameters. The description does not add per-parameter details beyond the legal framing; even the mention of حجب نقصانی is already echoed in the sibling_count parameter description. Baseline 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') with a precise resource ('Iranian inheritance shares') and a legal basis (قانون مدنی arts. 862–949), and explicitly names the حجب نقصانی reduction rules. This clearly distinguishes it from sibling calculators such as calculate_diyeh or calculate_lawyer_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?

Gives clear guidance to use this tool for any Iranian inheritance-share calculation, and even says 'always use this tool' because hand computation is unreliable. It does not explicitly list when-not-to-use or name alternative calculators, but the domain is sharply bounded.

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 readOnly, idempotent, non-destructive behavior, so the bar for description-added context is lower. The description usefully adds domain behavior: the tariff does not scale by outcome, `stage` is a share of the whole-case fee (60/40), and range-based vs ladder-based calculation differs by case type. It could go further on return format, though a calculator tool's output is largely self-evident.

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 dense, front-loaded sentences. Sentence one gives the governing regulation and the two fee structures; sentence two covers the stage share; sentence three is the usage warning. No 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 read-only calculator with 100% schema coverage and no output schema, the description is close to complete: it names the governing statute, the two calculation regimes, and the stage-share rule. What is thin is the outcome/arts. 12–23 behavior and the cassation edge case, but those are covered by schema descriptions.

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 every parameter already has an enum + description. The description reinforces the meaning of `stage` (art. 21 share) and the ladder/range split, but does not add syntax or format details beyond what the schema provides. Baseline 3 is correct here.

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 the specific action (calculate حق‌الوکاله) against a named regulation (آیین‌نامهٔ 1398/12/28) and describes the fee structures it handles (marginal ladder vs. min-max range). This is enough for an agent to distinguish it from calculators like calculate_diyeh or calculate_litigation_fee, though it never explicitly names 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 explains the internal logic of when financial claims use a marginal ladder vs. when family/criminal/admin matters use a range, and warns not to guess a statutory fee. But it does not tell the agent when to pick this tool over calculate_litigation_fee or lookup_law_article — the sibling routing is left 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 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds no behavioral detail beyond calculation scope, which is acceptable but not additive.

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 concise sentences with the core purpose front-loaded and the differentiator placed second. Every sentence earns its place, with no filler or repetition.

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 read-only calculation tool with robust annotations and a documented enum, the description is largely sufficient. A small gap remains: the listed document types omit schema values like mortgage, power_attorney, and will, and the amount_toman dependency is not fully explained.

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 lists some transaction categories present in the tx_type enum but does not clarify which transaction types require amount_toman or how rate-based calculations vary. It does not add meaningful value beyond the schema.

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

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

The description uses a specific verb 'Calculate' and a specific resource 'حق‌الثبت (registration duty)', then immediately distinguishes it from حق‌التحریر/notary fee. This makes the tool's purpose and its difference from calculate_notary_fee immediately clear.

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 names the alternative tool calculate_notary_fee and gives a clear when-not: use that for the notary's own fee. The stated scope of document types also makes it obvious when this tool is the right choice among the many sibling calculators.

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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: rates come from a database, and each row's `unit` field must be read because «rials» vs «درصد» changes the meaning of the value. It does not add auth/rate-limit detail, but for a read-only lookup that is minor.

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 rate enumeration are front-loaded, followed in order by the two exclusion rules and the unit caveat. It is dense with Persian terms and caveats, but in a high-stakes legal-rate domain each sentence carries a distinct routing or interpretation instruction rather than 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 two-parameter, read-only key lookup with no output schema, the description supplies everything an agent needs: the available keys, the optional-year default (also in schema), the alternatives for out-of-scope figures, and how to interpret the returned unit. Nothing material to correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description nevertheless adds value by listing the concrete rate keys and the court_fee_* pattern, which clarifies what rate_type accepts beyond the schema's short example list, and by pointing at the returned unit semantics for interpreting results.

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 from the database) and enumerates the exact rate keys it serves (min_wage, court_fee_*, salary_tax_exemption_annual, cbi_price_index, sanavat_daily). It explicitly distinguishes itself from calculate_lawyer_fee and calculate_diyeh, so an agent can route correctly among the many calculate_* 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?

Gives explicit when-to-use ('ALWAYS use this instead of recalling a rate'), when-not (حکالوکاله is NOT an annual rate; for دیه use calculate_diyeh), and names the alternative tools by name. The conditional routing is fully spelled out rather than inferred.

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 mark this as read-only and idempotent, so the description's extra detail is additive and valuable. It clearly warns that summary fields are machine-written and must never be quoted as statute text, explains conditional fields, and notes that related_articles carry their own source_urls. This is excellent behavioral disclosure.

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

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

The description is efficiently front-loaded: the core action, the condition for use, and the key instruction about verbatim quoting all come first. The longer field list earns its place because there is no output schema, and each field is labeled with what it is and how it should or should not be used.

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 explain return values, and it does so thoroughly: verbatim text, section_path, clauses, summary vs statute, answers_in_text, and related_articles. It also covers citation behavior and the source_url. An agent has everything needed to call this tool and interpret its results 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 description coverage is 100%, with both required parameters already explained (law name in Persian and article number). The description reinforces the meaning by giving an example ('ماده ۱۰ قانون مدنی') but does not add substantial semantic detail beyond the schema. Baseline 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?

The description opens with a specific verb and resource: 'Fetch the VERBATIM text of a specific article'. It also states the precondition — knowing the law and article number — which clearly separates this from broad article search. The title reinforces the exactness of the lookup.

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 guidance on when to use the tool ('when you already know the law and the article number') and instructs agents to quote the returned text rather than paraphrase from memory. It stops short of naming an alternative tool for cases where the article number is unknown, so it lacks a fully explicit when-not-to-use statement.

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.