چیستارا — Iranian Legal Corpus

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

With no annotations, the description carries the full burden. It discloses two key behaviors: 'The index series is official data — never approximate it' and 'Dates are Jalali.' These add important operational constraints. However, it does not mention output format, default handling, or potential errors, leaving some gaps.

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 concise sentences, each serving a purpose: the first states the action and legal basis, the second provides a critical data constraint, and the third gives the date system. No redundant or filler content; it is front-loaded and easy to parse.

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 tool with no output schema, the description covers the core legal basis, data source, and date system, which is sufficient for an agent to understand the tool's role. It could add a note about return values or handling of optional months, but the provided context is solid and appropriate for the tool's complexity.

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 does not add parameter-specific details beyond the schema, but it provides context about the calculation basis (art. 522 and Central Bank index) and the Jalali date system, which clarifies the intended meaning of start_year/end_year without restating them.

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 action: 'Calculate خسارت تأخیر تأدیه under art. 522 ق.آ.د.م using the Central Bank price index.' It names the legal basis and the method, distinguishing this from sibling calculation tools (e.g., calculate_diyeh, calculate_inheritance) which cover different legal damages.

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 implies usage for computing late-payment damages under article 522 with the Central Bank index, but it does not explicitly state when to use this tool versus alternatives or provide exclusions. The context is clear enough for an informed agent, but explicit guidance is missing.

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?

With no annotations, the description carries the full burden. It discloses that the calculation uses the current official rate, that fractions are statutory, and that the return includes the governing article and rate source. This is meaningful behavioral context beyond a generic description, though it does not mention edge cases like unrecognized injuries or handling of haram months.

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 tight sentences: the first states purpose and method, the second gives usage guidance and return value. There is no filler, and the most important 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 calculator with 3 parameters and no output schema, the description covers purpose, usage rationale, and return value (amount, article, source). It does not elaborate on error behavior or output structure, but it provides enough for an agent to select and invoke the tool 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?

All parameters are already described in the input schema (100% coverage), so the baseline is 3. The description adds value by connecting the year parameter to the annual rate change and the injury to statutory fractions, exceeding the baseline with useful context.

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 calculates دیه for bodily injuries using the current official rate and fractions from قانون مجازات اسلامی. The verb 'Calculate' plus the specific resource ('دیه for a bodily injury') distinguishes it from sibling calculators like calculate_delay_penalty or calculate_tax.

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 instructs 'ALWAYS use this instead of computing دیه yourself' and explains why (annual rate changes, statutory fractions). This provides clear when-to-use guidance, though it does not explicitly exclude or name alternative sibling tools (e.g., lookup_annual_rate) for cases where only a rate is needed.

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?

With no annotations, the description carries the burden of disclosing behavior. It mentions the legal basis and complexity, and notes that reduction rules are included. However, it does not describe the output format, assumptions, or any limitations (e.g., whether it requires all family members to be specified). This adds some context but leaves significant behavioral aspects undisclosed.

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 and front-loaded with the core purpose. The second sentence adds value by emphasizing reliability and edge cases. There is no fluff 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?

Given the tool has 8 parameters, no output schema, and no annotations, the description could do more to specify what the tool returns and how it handles missing parameters. It explains the legal domain and the complexity, but the agent may not know what to expect as a result (e.g., a numeric share, a breakdown, or a formatted legal report). This is adequate but not thorough.

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 has 100% coverage, so the baseline is 3. The description does not add parameter-level detail beyond the schema, but the mention of حجب نقصانی aligns with sibling_count's schema description. It provides no extra meaning for parameters like total_assets_toman or deceased_gender, so a score 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 clearly states the tool calculates Iranian inheritance shares under specific legal articles (قانون مدنی arts. 862–949) and includes reduction rules (حجب نقصانی). It uses a specific verb ('calculate') and resource ('inheritance shares'), and is clearly distinguishable from sibling tools like calculate_diyeh or calculate_tax.

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 implies usage for Iranian inheritance calculations and explicitly says hand computation is unreliable and to 'always use this tool' for jurisprudential edge cases. It provides a strong context for when to use, but does not mention alternatives or exclusion cases (e.g., when a simple share calculation might not need this). This is clear but lacks explicit when-not-to-use guidance.

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?

No annotations are provided, so the description must carry the burden. It does disclose that the fee is derived from an official tariff, which implies reliability. However, it does not mention output format, error handling, or behavior when optional parameters (case_type, case_value_toman) are omitted, leaving some behavioral ambiguity.

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 short sentences, front-loaded with the primary action and source. The second sentence adds a clear usage directive. No wasted words.

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 the tool's simplicity and full schema coverage, the description is largely complete. It explains the authoritative source and the basis of calculation. A minor gap is not explicitly noting what the tool returns (e.g., a fee amount), but that is easily inferred from the title and purpose.

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 already provides 100% coverage with descriptions for all four parameters. The description adds context by naming the three key dimensions (case type, stage, outcome) but does not add extra meaning beyond the schema for any parameter, such as how case_value_toman affects the calculation.

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 it calculates the lawyer fee from the official bar-association tariff, specifying the inputs (case type, stage, outcome). This verb+resource+scope is specific and naturally distinguishes it from sibling calculators like calculate_litigation_fee or calculate_notary_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 directive 'Never guess a lawyer's statutory fee' clearly indicates when to use this tool (whenever an official fee is required). It does not explicitly name alternatives or exclusions, but the context is strong enough for an agent to understand this is the authoritative fee calculator.

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?

With no annotations, the description carries the burden. It discloses that the tool relies on current official percentages and that rates are stage-dependent, adding useful context. However, it doesn't address output format, errors, or side effects, though these are minimal for a calculator.

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 that front-load the tool's purpose and usage. No unnecessary words.

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 simple and well-covered by the description plus schema. It lacks explicit output format or default behavior for optional stage, but these are minor gaps for a fee 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%, with descriptions for both amount and stage. The description reinforces that stage is one of three values and that rates depend on stage, but adds little 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 clearly states the tool calculates Iranian court filing fees for a monetary claim at a specified stage, using official percentages. It distinguishes itself from sibling calculator tools by targeting litigation fees specifically.

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 instructs to use this instead of estimating, noting rates are statutory and stage-dependent. This implies when to use, but does not name alternative tools or provide 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?

With no annotations provided, the description carries the full burden. It discloses that the tool reads coin prices and the adjustment index from the database instead of guessing, and explains the conditional behavior around marriage_year. It does not mention side effects or output format, but these are less critical for a read-only calculation tool.

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

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

Two sentences, front-loaded with the core purpose, and every clause adds critical information. The description is concise without being under-specified.

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 the tool's complexity (4 parameters, no output schema, no annotations), the description covers the essential behavior: data sources, conditional parameter usage, and a labeling warning. It does not describe the return format, but that is not explicitly required given the absence of an 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 coverage is 100%, so baseline is 3. The description adds value by explaining the relationship between cash_toman and marriage_year (needed to adjust to today's value) and clarifies that the cash portion stays nominal without it. This goes beyond the simple schema descriptions.

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 identifies the tool as calculating the present-day value of a مهریه, specifying both coin and cash components. It distinguishes itself from sibling calculate_* tools by referencing the live market rate and the Central Bank index, making the purpose unambiguous.

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 actionable guidance: it instructs to ask for marriage_year when there is a cash portion and warns against calling nominal cash 'ارزش روز'. However, it does not explicitly name alternatives or state when not to use this tool in favor of another sibling, 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It adds useful context about using the official tariff and not estimating, but it does not describe what happens with invalid inputs, whether it is a read-only calculation, or the output format. Some value but limited depth.

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 each sentence serving a distinct purpose: stating the calculation, naming the alternative, and giving a usage rule. No wasted words, and the key 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?

Together with the rich input schema, the description provides sufficient context: it identifies the tariff year, distinguishes from a related fee, and warns against estimation. The tool is a straightforward calculator, so the lack of an output schema is not a major gap; the expected result is implicitly a fee amount.

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 detailed descriptions of all three parameters including the enum for doc_type and clarifications like 'for real estate this is ارزش معاملاتی, not market price'. The description itself adds no parameter information, but the schema already handles it, so 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 clearly states the tool calculates the notary office's fee (حق‌التحریر) from the official 1405 tariff for official notary documents. It uses a specific verb-resource pair and explicitly distinguishes itself from حق‌الثبت, which helps differentiate it from sibling 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?

The description provides explicit usage guidance: 'Distinct from حق‌الثبت (use calculate_stamp_duty for that)' names an alternative tool, and 'Never estimate the tariff' sets a clear constraint on how to use the tool. This covers when to use it and when not to.

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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It does disclose a key behavioral trait—that it uses the 'current official minimum wage'—which is valuable. However, it does not mention output format, assumptions, or edge cases, leaving significant gaps.

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 consists of two concise sentences. The first sentence states the core purpose with specificity, and the second gives a usage directive. There is no redundancy or unnecessary detail, making it highly efficient and well-structured.

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 has no output schema, so the description should explain what the tool returns. It does not mention the return value (e.g., total amount in Toman) nor any assumptions or limitations. For a calculation tool, this is a significant gap, leaving the agent underinformed about the result.

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 100% coverage with clear descriptions for both parameters ('Years of service (may be fractional)' and 'Monthly wage in Toman'). The description does not add extra meaning beyond the schema, 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 uses the specific verb 'Calculate' and clearly identifies the resource as 'Iranian employee's end-of-service entitlements' under 'قانون کار', listing components (حق سنوات، عیدی، مانده مرخصی). This clearly distinguishes it from sibling tools like calculate_tax or calculate_diyeh, making the purpose unambiguous.

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 by specifying the target (Iranian employee) and the legal framework (قانون کار), and it explicitly advises using this tool 'instead of computing by hand.' However, it does not explicitly name alternatives or state when not to use, so it falls short of a full 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?

With no annotations provided, the description carries the full burden for behavioral disclosure. It does not mention anything about how the calculation works, whether amount_toman is required for all types, what the return value looks like, or any edge cases. This is a significant gap for a calculation tool.

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

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

Two sentences, front-loaded with the main purpose and immediately distinguishing from a sibling tool. No wasted words.

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 has 2 parameters and no output schema. The description explains the main scope but fails to mention that some enum types (e.g., will, power_attorney) are not explicitly listed, and it does not state that the result is in Toman or that amount_toman is required only for rate-based types. The schema covers parameter details, but the description is slightly incomplete for a calculation 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 description coverage is 100%, so the schema already documents both parameters. The description adds some context about document types but does not materially enhance understanding of the parameters beyond the enum list. 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 clearly states the tool calculates حق الثبت (registration duty) for a specific set of document types, using a specific verb and resource. It distinguishes itself from the sibling tool calculate_notary_fee by explicitly naming the alternative.

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 explicit guidance on when to use this tool versus the alternative ('Distinct from حق التحرير (the notary's own fee — use calculate_notary_fee for that)'). This makes the appropriate context 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?

With no annotations, the description must carry the safety and behavior burden. It discloses important nuances: inheritance rates depend on asset kind and heir class, no general exemption, pre/post-1395 date differences, and property basis. This adds significant context beyond a simple calculation, but it does not cover behavioral specifics for salary or rental taxes.

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, front-loaded with the main purpose, then concise caveats. No filler or redundancy, 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 an 8-parameter tool with no output schema, the description covers key edge cases (inheritance exemptions, date changes, property basis) but does not explain return values or salary/rental calculation nuances. However, the comprehensive schema fills most gaps, making this adequately complete overall.

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

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

Schema coverage is 100%, so the schema already documents all 8 parameters. The description adds some semantic value by clarifying the property basis (value_toman) and inheritance dependency on asset_kind/heir_class, but this is marginal given the baseline of 3 for high 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 it calculates four Iranian tax types with a specific verb-resource pair ('Calculate Iranian salary, property-transfer, inheritance or rental tax'). However, it does not differentiate from the sibling tool 'calculate_inheritance', which overlaps with the inheritance tax scope, so it misses the 5-level distinction.

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

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

It provides clear context on when to use the tool and special handling: 'ask before calling' for inheritance and property basis being 'valore ma'ati', not market price. But it does not explicitly mention alternatives or exclusions with sibling tools, so it falls short of a 5.

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

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

With no annotations, the description carries the burden. It discloses that the tool returns rows with a `unit` field, warns about the rials vs. percent distinction, and emphasizes reading `unit` to avoid misreporting. This is meaningful behavioral context beyond a simple fetch, though it doesn't detail pagination or error cases.

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 dense but well-structured: it opens with the core action, lists examples, gives usage directives, and ends with a critical warning. No sentence is wasted, though the enumeration of keys could arguably be trimmed since the schema already shows examples. Overall it earns its length.

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

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

For a simple lookup tool with two params and no output schema, the description is complete. It specifies what data is available, how to use it, when to prefer it, and how to interpret the results (unit field). The mention of the `unit` field provides enough return-value context for correct invocation.

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% with descriptions for both parameters, but the description adds richer semantics by listing many valid rate_type examples (min_wage, court_fee_financial_first, cbi_price_index, lawyer_tariff_nonfinancial) and the pattern court_fee_*/lawyer_tariff_*. It clarifies the yearly nature of the data, complementing the schema without redundancy.

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: 'Fetch official Iranian yearly rates from the database' and enumerates specific rate types (min_wage, court_fee_*, etc.). It also distinguishes from siblings by explicitly redirecting دیه to calculate_diyeh, making the tool's scope unambiguous.

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?

Provides explicit when-to-use guidance: 'ALWAYS use this instead of recalling a rate — yearly figures are exactly what models misremember.' It also names an alternative for a specific case: 'For دیه use calculate_diyeh instead.' This is clear 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?

With no annotations, the description fully discloses behavior. It reveals that the tool returns verbatim text and conditionally provides several fields ('when we hold them'), and importantly warns that summary fields are 'machine-written explanations — NOT statute text; never quote them as law'. This is a substantial transparency caveat beyond mere operation.

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?

Every sentence is purposeful: core action, usage condition, anti-paraphrase rule, source URL requirement, and a clear list of return fields with an important caveat. It is dense but well-structured, and the front-loaded purpose is immediately clear. No filler or 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?

Given the absence of an output schema, the description compensates thoroughly by enumerating all potential return fields and their meanings, including warnings about summaries not being law. It covers the main lookup behavior, optional fields, and related articles with URLs. This is complete for a lookup 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?

Schema description coverage is 100%, so the schema already documents both parameters with Persian examples. The description adds contextual use ('e.g. «ماده ۱۰ قانون مدنی»') but no additional parameter syntax or semantics. Baseline 3 applies as the schema does the heavy lifting.

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 'Fetch' and resource 'verbatim text of a specific article', with a clear condition 'when you already know the law and the article number'. This distinctly separates it from sibling search tools like search_law_articles, and includes a concrete example «ماده ۱۰ قانون مدنی».

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 you already know the law and the article number') and for what purpose ('verify wording before quoting it'). The directives to 'never paraphrase' and 'link the source_url' are strong usage constraints. It does not explicitly name alternatives but the condition implies using search when unsure.

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?

With no annotations, the description carries the full burden. It discloses that deadlines differ by case type and that the tool returns the governing law and article, which is useful. However, it does not explain the exact output format (e.g., structured list vs. narrative), what happens when procedure_name is omitted, or any error conditions. It adds some behavioral context but is 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?

The description is two sentences. The first sentence communicates purpose, scope, and output; the second gives a clear usage rule. It is front-loaded, concise, and every clause earns its place. 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?

Given the tool's simplicity (2 parameters, one enum, no output schema), the description covers the essential context: what the tool does, how to use it, and a caution about case-type variability. It lacks explicit mention of the return structure when listing all procedures, but the schema hints at that behavior. Overall it is sufficiently complete for selecting and invoking the 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?

Schema coverage is 100%, with both parameters well-described. The description adds a bit of semantic flavor by listing example procedural names in Persian, but this is largely redundant given the schema already documents the enum for case_type and examples for procedure_name. The description does not provide significant new meaning 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 opens with a specific action: 'Look up Iranian procedural deadlines' and clarifies the resource (procedural deadlines), the governing law/article returned, and the filtering by case type. It provides examples of procedural types and differentiates the tool from siblings like lookup_statute_of_limitations by focusing on procedural deadlines specifically.

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 guidance: 'Use when the user asks how long they have for a procedural step' and warns against answering from memory. It clearly states when to use the tool but does not mention alternatives or exclusion cases, such as when statute of limitations would be more appropriate.

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?

With no annotations, the description carries the full burden. It discloses that the tool returns the governing article along with the punishment and warns against relying on memory, providing useful behavioral context. It lacks details on edge cases (e.g., unknown crime_type) or the role of crime_grade, but overall it is transparent for a read-only lookup.

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: the first front-loads the core purpose with specific punishment types and article citation; the second provides usage guidance and a safety rule. Every sentence earns its place with no redundancy or fluff.

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 the tool's simplicity (2 params, no output schema), the description covers purpose, usage context, and a caution. It does not explicitly spell out the output format, but the name and description ('statutory sentencing range' + 'with the governing article') make it predictable. Minor lack of explicit alternative disambiguation prevents 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 description coverage is 100% with clear parameter definitions: crime_type includes Persian examples and crime_grade is described as an optional 1–8 grade. The description adds only the 'Iranian crime' context, which is not parameter-specific. Baseline of 3 is appropriate when the schema already documents parameters fully.

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 specifies 'Look up the statutory punishment for an Iranian crime' and enumerates punishment types (imprisonment, fine, lashes, قصاص, دیه) with the governing article. This clearly distinguishes it from sibling tools like lookup_law_article, which likely retrieve generic legal text rather than sentencing ranges.

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 'Use when the user asks what the punishment for a crime is, or for criminal-risk analysis.' It also adds a caution ('Never state a sentencing range from memory'). However, it does not explicitly mention alternatives or exclusion criteria, so it stops short of a full 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention whether the lookup is read-only, whether it requires special permissions, how current the legal data is, or what the response format looks like. The description is too brief to convey these traits.

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: one states the purpose and scope, the other gives usage context. Every word is functional, no redundancy, and it is front-loaded with the key meaning. Excellent conciseness.

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 lookup tool with a clear schema and no output schema, the description is largely sufficient. It explains what it does and when to use it. It lacks details about return values or limitations, but these are not critical for a straightforward legal lookup, keeping it slightly above the minimum viable.

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 parameters described. The description adds only a vague reference to 'case category' but does not provide further semantics beyond what the schema already documents. This aligns with the baseline 3 for high 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 function: 'Check Iranian limitation periods (مرور زمان) — prosecution, execution, and filing deadlines — for a case category.' It specifies the resource (limitation periods), the verb (check), and distinguishes it from related lookup tools like lookup_law_article or lookup_procedure by its focus on time limits.

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 guidance: 'Use when the user asks whether a claim is time-barred or how long they have to file.' While it does not mention alternatives or when not to use it, the context is clear and practical, earning a 4 rather than 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?

With no annotations present, the description carries the full burden and does so well. It discloses that advisory opinions are 'authoritative guidance, not binding law' and instructs the assistant to 'say so when citing.' It also specifies returned fields (opinion number, date, excerpt, source_url), giving full behavioral transparency.

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, each earning its place: what it is, when to use it, and a critical caveat plus return format. The description is front-loaded with purpose and contains no wasted words.

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 2-parameter search tool with no output schema, the description is complete. It covers the purpose, usage context, return fields, and an important caveat about non-binding status. Nothing critical is missing for an agent to select and invoke this tool 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 schema describes the query parameter with examples, but the limit parameter has no description. The tool description itself adds no parameter-level information (e.g., that query is in Persian or that limit is capped at 5). With schema description coverage at only 50%, the description should compensate but does not.

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 precisely identifies the action ('Search'), the resource ('advisory opinions of the Judiciary's legal department'), and the nature of the content ('official, citable interpretation of Iranian statutes'). This clearly distinguishes it from sibling tools such as search_case_law and search_circular.

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 states when to use the tool: 'Use when the user asks how a provision is officially interpreted, or to support an argument.' It does not offer when-not-to-use guidance or alternatives, but the usage context is clear 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?

No annotations are provided, so the description carries the full burden. It discloses that it returns excerpts with source_url, which is useful behavioral info. However, it doesn't detail any limits (beyond schema's max=5), rate limits, or other behavioral traits. It's a read-only search tool, but the description doesn't explicitly state that; still, it's implied sufficiently for a 3.

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 concise sentences, front-loaded with the main action. Every sentence provides value: what it searches, when to use it, and what it returns. No wasted words.

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 search tool with 2 parameters and no output schema, the description covers the core aspects: purpose, usage context, and return format. Minor gaps exist (e.g., Persian query requirement is only in schema, not description), but the description is adequate for 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?

The schema description coverage is 50% (query is described, limit is not). The description adds some context for the query ('how courts have actually decided an issue') but does not explain the limit parameter at all. It fails to compensate for the gap in schema coverage, leaving the limit parameter's purpose unclear from the description alone.

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 'Search 31,000+ Iranian court rulings and آرای وحدت رویه (binding precedent)', clearly stating the verb (search) and resource (court rulings and binding precedent). It distinguishes itself from siblings like search_law_articles and search_advisory_opinions by focusing on court decisions. The title also provides a bilingual clarification.

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 courts have actually decided an issue, or for precedent supporting a position,' which gives clear when-to-use context. It does not name alternatives or provide exclusions, so it misses the full 5-point criteria for explicit alternatives.

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?

With no annotations provided, the description carries the full burden for behavioral disclosure. It does disclose the return format (excerpts with source_url), which is helpful. But it does not mention any limits, potential side effects, permissions, or other behavior that could be relevant, leaving the agent to rely on schema defaults.

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 concise, with two sentences that front-load the purpose and then add the return format. Every sentence contributes value, with no redundancy or irrelevant detail.

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 search tool with two parameters and no output schema, the description provides a solid overview: purpose, source context, and return format. It is mostly complete, though it could mention the default/max limit behavior to fully round out the picture.

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 provides descriptions for only one of two parameters (query has 'Topic, in Persian', limit has none), giving 50% coverage. The tool description does not explain the limit parameter or add any semantics beyond the schema, so it fails to compensate for the gap.

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

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

The description clearly states the action ('Search') and the resource ('official circulars and directives'), specifying they come from judiciary and government bodies. It distinguishes itself from sibling search tools by emphasizing that these circulars are the source of current official rates and procedures.

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 useful context about when to use this tool—when seeking current official rates and procedures—which helps differentiate it from sibling lookup tools. However, it does not explicitly state exclusions or name alternatives, so it leaves that inference to the reader.

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?

No annotations exist, so the description carries full transparency burden. It discloses search scope, return fields (article number, law title, excerpt, source_url), and warns about amended articles. It doesn't cover every edge case, but it meaningfully explains what the tool does and why it exists.

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 four sentences, front-loaded with the core purpose, followed by usage directive, return details, and citation instruction. Every sentence contributes meaningful information with no filler or 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?

Given the tool's complexity (search over 46k articles, citation needs), the description covers scope, when to use, what is returned, and how to cite. It lacks an example query and explicit note about result ranking or amendment recency, but is sufficiently complete for effective use.

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% (query and law_filter have descriptions; limit only has constraints). The description adds value by advising Persian gives better recall for query and giving an example for law_filter, going beyond the schema. Limit is left to schema constraints, which is acceptable.

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: 'Semantic + keyword search across the full text of Iranian statutes,' with concrete details (46,000+ articles, law names). It clearly distinguishes from sibling tools like lookup_law_article by emphasizing broad full-text search rather than retrieving a single known 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?

Usage is explicitly instructed: 'USE THIS BEFORE ANSWERING ANY QUESTION ABOUT IRANIAN LAW', with a strong rationale (memory pitfalls, amended articles). It doesn't explicitly mention alternatives (e.g., lookup_law_article for exact article retrieval), but the directive is clear and context-rich.

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