farsi-tools (paid)

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

No annotations exist, so the description carries the full burden. It does add genuinely useful operational context — per-call cost of $0.005 in USDC on Base — which the schema cannot express. However it says nothing about the output format (string of words?), default unit behavior, or handling of non-numeric input.

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

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

A single front-loaded sentence with the core purpose first and the cost note as a parenthetical. No filler, though the parenthetical pricing could arguably live in a metadata field.

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 0% schema coverage, no annotations, and no output schema, the description should explain the parameters and the return shape. It leaves the amount/number ambiguity and the output format entirely unexplained.

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

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

Schema description coverage is 0% for 3 parameters with no types declared for amount or number. The description's mention of 'rial or toman' hints at the unit parameter, but it never explains the distinction between 'amount' and 'number', which is a real source of agent confusion.

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 plus resource ('write a rial or toman amount in Persian words') and includes the Persian phrase (مبلغ به حروف) which aids recognition. It implies a distinction from siblings like fa_numberToWords and fa_rialToman but never names them explicitly.

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

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

The description gives no when-to-use or when-not-to-use guidance, and does not explain how this differs from fa_numberToWords (generic number-to-words) or fa_rialToman (currency conversion). The agent must infer the choice from tool names alone.

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 behavioral burden. It usefully discloses the per-call price ($0.003 USDC on Base), which is real behavioral context, but says nothing about permissions, rate limits, or conversion behavior (e.g., mixed input, non-digit characters).

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

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

A single compact sentence is front-loaded with the core purpose, and the pricing clause is appended tersely. Nothing is wasted, though a short default/behavioral note could earn 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 two-param tool with no output schema the description is mostly adequate, but with no annotations and an undocumented 'to' param, the agent still lacks the default target script and the expected return shape or direction of conversion.

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

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

Schema coverage is only 50%; the 'text' param is documented but the 'to' parameter has no schema description at all. The description partially compensates by naming the three target scripts (Persian, Arabic-Indic, ASCII), which are presumably the 'to' values, but gives no default or accepted string forms.

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 (Convert) and resource (digits) with the exact scripts and codepoint ranges involved, so the agent immediately distinguishes it from siblings like fa_numberToWords or fa_normalize. It is precise about the three numeral systems covered.

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?

There is no when-to-use framing, no mention of related siblings such as fa_normalize or fa_numberToWords, and no indication of when this conversion is or isn't appropriate. Usage is only inferable from the task described.

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 behavioral burden. It discloses a real behavioral trait—the per-call cost of $0.005 in USDC on Base—but says nothing about permissions, whether the transformation is non-destructive, idempotency, or return format, leaving most of the profile undocumented.

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

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

A single front-loaded sentence that states the action first and appends the pricing detail. No filler or redundancy, though it is terse to the point of omitting usage context.

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

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

With full schema coverage and no output schema, the essential calling information is present. However, for a paid utility among 26 overlapping Persian-text siblings, the absence of any disambiguation or output/return behavior leaves a meaningful contextual 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 both the required 'text' and optional 'options' parameters are already documented in the schema. The description adds no parameter-level detail (e.g., what the options object keys do), so the baseline 3 applies.

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

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

States a specific verb+resource pair ('Remove bidi control characters and repair RTL punctuation spacing'), which is concrete and unambiguous. It does not differentiate from possible siblings like fa_normalize, which may also touch Persian text, but the RTL-specific purpose is clear from the wording alone.

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?

No when-to-use guidance and no alternatives named, despite a large sibling set including fa_normalize and fa_digits that an agent might confuse it with. The agent must infer applicability purely from the operation described.

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 the full behavioral burden. It usefully discloses the pay-per-call cost ($0.005, USDC on Base), but says nothing about the return shape (string vs. numeric triple), date-range validity, or error behavior for invalid inputs.

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

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

A single front-loaded sentence with no filler; the parenthetical cost note is compact and operationally relevant rather than padding.

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 stateless conversion tool with no annotations, no output schema, and zero parameter documentation, the description omits the one thing an agent cannot infer: what the call returns. It is not sufficient on its own to 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?

Schema description coverage is 0% across all 3 required parameters, so the description must compensate and does not. There is no hint of accepted formats or ranges (e.g., four-digit year, 1-12 month) beyond the self-evident parameter names.

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

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

States a specific verb and resource ('Convert a Gregorian date to the Jalali calendar') with the conversion direction made explicit, which lets an agent instantly distinguish it from the sibling fa_jalaliToGregorian without opening either schema.

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

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

The direction of conversion implies when the tool applies, but the description never states when to prefer it over the reverse sibling or any prerequisite/edge-case conditions. Usage is inferable from the name only.

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 usefully discloses the payment model ($0.005 per call, USDC on Base), which is a real behavioral trait not derivable from schema, but says nothing about behavior on unknown/ambiguous city names or how the province is formatted in the response.

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

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

A single front-loaded sentence with the primary action first and the cost parenthetical at the end. Nothing wasted, nothing missing at the sentence level.

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 trivial lookup with no output schema and no annotations, the description covers both input (city) and output (its province). Missing only edge-case behavior (unknown cities, ambiguity between aliases, Persian-only requirement) to be 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% – all three parameters (name plus text/value aliases, all in Persian) are documented in the schema. The description adds no parameter detail beyond that, so baseline 3 applies.

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

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

Specific verb+resource+output: looks up an Iranian city and returns its province. This is clearly distinguishable from sibling fa_iranProvince/fa_iranProvinces, which go the other direction. It stops short of naming alternatives, so not a 5.

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 implied by the description (you have a city name and need its province), and the per-call cost gives a reason to route here sparingly. However, there is no explicit when-to-use/when-not or reference to a sibling lookup 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?

No annotations are provided, so the description carries the full burden. It does disclose the payment model ($0.005 per call, USDC on Base), which is genuinely useful behavioral context, but it omits error behavior and what is returned when the date is not a holiday, which an agent needs for a check 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?

A single tight sentence with the core purpose front-loaded and the cost note appended. No waste, though the pricing could arguably live in metadata rather than the description.

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-param check tool with no annotations and no output schema, the description covers purpose, return value, and cost, but leaves the Jalali input format and the non-holiday result undefined.

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

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

Schema coverage is 0% and none of the three params (year, month, day) are described. The phrase 'Jalali date' does add real meaning – the year is a Jalali year (~1300-1400), not Gregorian – but no format, range, or validation rules are given.

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 ('Check') and resource ('Jalali date is an Iranian public holiday') plus the return value ('its name'). The singular/plural naming lets an agent infer it differs from sibling fa_iranHolidays, but the description never explicitly contrasts them.

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?

No when-to-use guidance, no prerequisites, and no alternative named. The agent must infer from the name that fa_iranHolidays returns the full list while this checks one date.

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 does disclose genuinely useful behavioral context — cost ($0.005 per call) and payment method (USDC on Base) — which an agent needs before invoking a paid tool. But it says nothing about the return format, pagination, or error behavior for invalid years.

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

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

A single front-loaded sentence with zero waste; the resource is named first and the pricing detail is parenthetical. Nothing could be cut without losing information.

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 one-parameter read tool this is nearly adequate, but with no output schema and no annotations the description should at least hint at what is returned (a list of holiday dates/names) and how it relates to fa_iranHolidayCheck. Those gaps leave the agent guessing.

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

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

Schema coverage is 0% and the bare schema only says 'year: number'. The description compensates for the most important ambiguity by specifying the year is Jalali (Solar Hijri), not Gregorian. It does not state format (e.g., 1403 vs 1403.0) or valid range, so the gap is only partially closed.

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

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

States a specific verb+resource: 'Official Iranian public holidays for a Jalali year.' An agent knows this returns a holiday list, not a validation. However, it never distinguishes itself from the sibling fa_iranHolidayCheck, which likely serves the adjacent single-date use case.

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?

There is no when-to-use guidance and no mention of the obvious alternative (fa_iranHolidayCheck). The agent must infer from the name alone whether this is the right tool for checking one date versus listing a year's holidays.

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, but it does add genuinely useful non-schema context: the pay-per-call cost ($0.005, USDC on Base) and the shape of the returned data (capital and major cities). It still omits error/not-found behavior and whether a missing province yields an empty result or an error, which matters for a paid call.

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

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

A single sentence that front-loads the action and resource, then tacks on the return payload and cost. No filler, no repetition of the tool name, nothing to cut.

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

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

No annotations and no output schema, so the description must cover behavior and results; it partially does by naming the returned fields and the price. But with zero required parameters and three interchangeable name fields, it never tells the agent that a province name must be supplied, nor what happens on a miss.

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 three parameters (name plus its text/value aliases) are already documented in the schema, making the baseline 3 appropriate. The description adds only "by name" and says nothing about the alias behavior or that the Persian-script name is expected.

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

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

States a specific verb and resource ("look up an Iranian province") plus the payload ("capital and major cities"), so the agent knows exactly what comes back. However, it never distinguishes itself from the near-identical sibling fa_iranProvinces (plural listing) or fa_iranCity; only the phrase "by name" hints that this is a single-record 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?

There is no explicit when-to-use guidance and no mention of the obvious alternative fa_iranProvinces or fa_iranCity. The agent must infer from the singular name that this returns one province rather than a list, which is exactly the kind of routing decision the description should make explicit.

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, so the description carries the full burden. It does disclose a genuinely useful behavioral trait — cost ($0.003 per call, USDC on Base) — and the payload contents ('capitals and major cities'), but says nothing about read-only semantics, result size, or pagination/limit behaviour.

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

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

A single front-loaded sentence with no waste; scope, payload, and price are all packed into minimal text.

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

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

For a zero-param read-only listing with no output schema, the description covers what is returned (provinces, capitals, major cities) and the cost. It lacks only layout detail, which is minor and unrecoverable from structured fields since no output schema exists.

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?

Zero parameters, so there is no parameter semantics to document; baseline 4 applies. The description correctly signals a no-argument, list-everything call.

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?

Specific verb + resource + scope: 'List all 31 Iranian provinces with capitals and major cities'. The plural/'all 31' framing implicitly separates it from the singular sibling fa_iranProvince, but the description never names that sibling, so differentiation is inferred rather than stated.

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?

No when-to-use guidance and no mention of alternatives, even though fa_iranProvince (single province) and fa_iranCity (city-level) are obvious competing siblings. The agent must infer selection from the tool name alone.

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 the full burden. It discloses the billing model ($0.005 per call, USDC on Base), which is genuinely useful context, but says nothing about how invalid dates are handled, whether the call is read-only/idempotent, or what form the result takes. Return format is left entirely unknown since there is no output 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?

A single compact sentence with the core purpose front-loaded. The pricing parenthetical is ancillary to selection but is functional information rather than filler, so the sentence still 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 three-parameter conversion tool with no output schema and no annotations, the definition should state the returned format (e.g., ISO date string vs. component object) and input validation behavior. It omits both, leaving the agent unable to interpret the result or predict failure modes.

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 three parameters (year, month, day) have 0% schema description coverage, so the description must compensate. It only weakly implies the values are Jalali-calendar components via 'Jalali (Solar Hijri) date' — useful to prevent passing a Gregorian year — but gives no ranges, numbering conventions, or field-to-value mapping.

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 (Convert) plus resource (Jalali/Solar Hijri date to Gregorian calendar), naming both the source and target calendar explicitly. This direction specification is exactly what distinguishes it from the sibling fa_gregorianToJalali, so an agent can pick the right one without opening either schema.

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

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

There is no when-to-use guidance, no mention of the reverse sibling fa_gregorianToJalali, and no statement of prerequisites or constraints (e.g., valid Jalali ranges). The conversion direction is the only implicit routing signal.

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 burden. It usefully discloses cost ($0.01 per call, USDC on Base) and the stopword-filtering behavior, but says nothing about return format, ordering, or what happens on empty/non-Persian input.

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

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

A single front-loaded sentence with the core purpose first and parenthetical qualifiers for filtering and pricing. No wasted words, though the trailing pricing parenthetical slightly interrupts the core statement.

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 no-annotation, no-output-schema tool with three parameters, the description covers purpose, cost, and filtering but omits return shape (keyword list? scores?) and the meaning of 'limit'. It is adequate but leaves real gaps 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?

The description adds no information about any parameter. Schema coverage is 67%, and the undocumented 'limit' parameter (no schema description, no enum) is left completely unexplained in both places, so the description fails to compensate for that 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?

States a specific verb (extract) and resource (frequent keywords) with a qualifier (stopword-filtered, Persian text). It is easily distinguished from siblings like fa_stats or fa_similarity, which serve different purposes.

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 purpose implies when to use it (keyword extraction from Farsi text), but there is no explicit when/when-not guidance or reference to an alternative sibling such as fa_stats. Usage is inferable rather than stated.

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, and it does disclose useful operational context the schema cannot: pay-per-call pricing of $0.01 in USDC on Base. It also enumerates the normalization passes. However, it says nothing about idempotency, whether the original text is returned unmodified on failure, or the return shape, so the behavioral picture is only partial.

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

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

A single dense sentence that front-loads the verb and operation list and appends the cost signal with no wasted words. Every clause 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 stateless text transformer with 100% schema coverage the description is close to sufficient, and it usefully adds pricing. It still omits what comes back (normalized string) and how the options parameter alters behavior beyond one example, leaving a modest gap given no annotations or output schema exist.

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

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

Schema description coverage is 100%, with 'text' documented (Persian value, max 100000 characters) and an options example already embedded in the schema, so the baseline is 3. The description's mention of 'digits' loosely hints at the options flag but adds no syntax or default information beyond what the schema supplies.

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 (Normalize) plus the resource (Persian text) and enumerates the transformations performed (Arabic->Persian letters, ZWNJ, spacing, digits), which lets an agent distinguish it from narrow siblings like fa_digits or fa_fixRtl. It stops short of explicitly naming which sibling to prefer, so it is clear but not fully differentiated.

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?

There is no when-to-use or when-not-to-use guidance and no routing to alternatives. An agent must infer that this is the broad, multi-step cleanup tool versus the single-purpose siblings, which is left entirely unstated.

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 behavioral burden. It discloses a cost ($0.01 per call, USDC on Base), which is useful behavioral context, but it omits other important traits such as whether the operation is pure, what the return type is, and whether authentication is required for payment.

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, tightly constructed sentence that front-loads the core action and appends the Persian translation and pricing. Every element earns its place with no redundancy.

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

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

For a simple one-parameter conversion tool with a fully documented schema and no output schema, the description is nearly complete. It states the transformation and mentions cost, though it could optionally clarify that the output is a text string, but that is not strictly required.

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 fully documents the single parameter, including accepted formats (integer, string digits, commas, Persian digits). The description adds no additional meaning beyond what the schema provides, making the baseline 3 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 states a specific verb ('Write') and resource ('integer as Persian words'), clearly indicating a number-to-text conversion. It implies a distinction from sibling fa_amountToWords by specifying 'integer' rather than 'amount', but it does not explicitly name or contrast 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?

There is no guidance on when to use this tool versus alternatives, nor are there any prerequisites or exclusions. The description only states what the tool does, leaving the agent to infer context from the name and sibling list.

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 behavioral burden. It usefully discloses the cost ($0.003 per call) and payment rail (USDC on Base), which is real context an agent cannot get from structured fields, but says nothing about validation behavior, error cases, or what the response contains.

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

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

A single compact sentence with the core purpose front-loaded and no filler. The trailing parenthetical mixes conversion rate, price, and payment network, which is slightly overloaded but still tight.

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 0% schema coverage, no annotations, no output schema, and an undocumented 'number' parameter, the description leaves an agent unable to invoke this correctly beyond passing a bare amount. Direction of conversion and accepted unit values are the critical missing pieces.

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

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

Schema description coverage is 0% across three parameters, and the description does not compensate: it never explains that 'unit' selects conversion direction, nor what 'number' is for, nor what type 'amount' takes. The rate constant is helpful domain knowledge but does not map to any 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?

States a specific verb and resource ('Convert an amount between Iranian rial and toman') and even supplies the conversion constant (1 toman = 10 rial). No sibling tool in the fa_* list performs currency conversion, so it is trivially distinguishable from the validators and text utilities around it.

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?

There is no when-to-use guidance, no statement of which direction the conversion runs, and no indication of what values the 'unit' parameter accepts. The only implied usage is the verb itself, with nothing about exclusions or prerequisites.

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

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

No annotations exist, so the description carries the full burden. It does disclose a genuinely useful behavioral fact — cost of $0.005 per call paid in USDC on Base — but says nothing about the return shape (presumably an array of sentence strings), length limits on the output, or how ambiguous delimiters are treated.

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

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

A single sentence that front-loads the action and the handled characters, then appends cost. No filler at all.

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 annotations and no output schema, the description should state what comes back from a split (list of strings? single string?) and whether empty input is an error. For a two-parameter tool this is close to adequate, but the return contract is left entirely unstated.

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 text parameter documents the 100000-character limit, so the schema does the work. The description adds nothing about the parameters, and the example options value ({"digits":"ascii"}) is only in the schema, so baseline 3 applies.

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

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

Specific verb+resource ('Split Persian text into sentences') with the delimiter set named, which makes the operation unambiguous against siblings like fa_normalize or fa_stripHtml. No sibling is explicitly named as an alternative, but none competes for this task.

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 only implied by the operation itself — an agent can infer when splitting is wanted, but there is no explicit when-to-use, when-not, or comparison to a sibling tool. The price note helps with cost decisions but is not usage 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?

With no annotations, the description carries the burden and discloses the algorithm (trigram Jaccard), output range, and a concrete cost/payment detail ($0.01 per call, USDC on Base). It does not describe payment flow or error behavior, but for a simple stateless similarity function this is substantially transparent.

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

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

A single front-loaded sentence states the algorithm, input domain, output range, and cost with no wasted text. Every element is relevant to invoking or interpreting the tool.

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 function with no output schema, the description provides the return range and cost. It omits interpretation details such as 0 meaning dissimilar and 1 meaning identical, but the Jaccard metric and stated range make the return value sufficiently clear.

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 would be 3, but the description adds meaningful domain semantics by specifying that both inputs are Persian strings. It does not explain trigram or normalization handling, but it compensates beyond the schema's generic 'first string'/'second string' labels.

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 operation and resource: trigram Jaccard similarity between two Persian strings. It also states the output range (0..1), making the tool's purpose unambiguous and distinguishable from all sibling Persian text utilities.

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 metric itself implies the tool's use case, but there is no explicit guidance on when to choose this tool versus other string utilities or when not to use it. No alternatives are named, leaving usage conditions 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the pay-per-call cost model ($0.005 per call, USDC on Base), which is real value an agent cannot get from structured fields, but it says nothing about latency, failure modes, or how the paid call is settled. The cost disclosure lifts it above a bare 2.

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

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

A single compact sentence with the purpose front-loaded and the enumerated metrics immediately after. The pricing parenthetical is short and materially relevant, so nothing is wasted.

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?

There is no output schema, and the description compensates by naming the returned metrics (chars, words, lines, ZWNJ count) plus the cost of a call. Only the 'options' parameter behavior (e.g. the digits setting) is left entirely to the schema, 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 coverage is 100%, so both parameters (text, options) are already documented in the schema, and the description adds no syntax or format detail beyond naming ZWNJ as a computed metric. Baseline 3 is appropriate when 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?

Names a specific operation ('statistics') on a specific resource ('Persian text') and enumerates exactly what is measured (chars, words, lines, ZWNJ count). The metric list implicitly separates it from extraction-style siblings like fa_sentences or fa_keywords, though no sibling is named explicitly.

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

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

There is no statement of when to reach for this tool versus the many other fa_* tools, and no prerequisites or exclusions. The only contextual note is pricing, which is a cost fact rather than usage 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?

With no annotations, the description carries the full burden, and it does disclose one real behavioral trait the schema lacks: the cost model ($0.005 per call, USDC on Base). However, it says nothing about whether entities are decoded into characters, how malformed HTML is handled, or the return format, which are meaningful gaps for a no-annotation 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?

A single front-loaded sentence with no filler; the pricing clause is arguably tangential but is genuinely useful context. Nothing is wasted.

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 text-transformation utility with full schema coverage, the description is nearly complete, and no output schema means return details are less critical. It falls just short of 5 because it never states what the stripped output looks like or how entity decoding behaves.

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's mention of 'tags and entities' loosely frames the operation but adds no meaning beyond the schema, and notably does not clarify the opaque 'options' 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?

States a specific verb+resource ('Strip HTML tags and entities from text'), so an agent immediately knows the operation. It doesn't explicitly contrast with the many fa_* sibling utilities, but the purpose is unambiguous and distinct from any of them.

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?

No guidance on when to use this versus siblings such as fa_normalize or fa_digits, and no prerequisites or exclusions are given. The agent must infer usage entirely from the tool name and description.

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, and it does disclose a genuine behavioral trait: the cost model ($0.01 per call, USDC on Base). However, it does not explain how payment is actually settled (wallet, API key, auto-charge), nor return format or failure behavior, leaving key invocation details unstated.

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

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

A single front-loaded sentence with no filler; the core operation leads and the pricing/option qualifiers follow. Nothing redundant.

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 3-parameter tool with no output schema and no annotations, the description omits what the transliteration returns (plain string? slug alongside text?), what 'slug' actually changes in the response, and the mechanics of the paid call. Adequate for the core operation but not complete for confident 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 67%: 'text' is well documented (including the 100k limit) and 'options' has an example, but 'slug' is a bare boolean in the schema. The description recovers some ground by labeling slug as an 'optional URL slug', adding semantic meaning the schema lacks. 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 ('Transliterate') and both the source script (Persian/Arabic) and target (Latin), which unambiguously separates it from siblings like fa_normalize, fa_fixRtl, and fa_digits. An agent can identify what this does 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?

No guidance on when to use this versus fa_normalize or fa_fixRtl, no stated preconditions, no exclusions. The only contextual hint is the slug option and price, neither of which tells the agent when this tool is the right choice.

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 behavioral burden. It does disclose cost and payment rail ($0.005 per call, USDC on Base) and the validation method, but it never says what happens on a failed Luhn check (error vs. false), whether the issuing-bank lookup can fail independently, or whether any auth is required.

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?

One sentence, front-loaded with the action and resource, with the cost detail trailing. No filler or redundant restatement of the tool name.

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?

There is no output schema, and the description does at least state the primary return (issuing bank), which is the key missing piece for a validator. However, it omits the failure semantics of an invalid card and any indication of the response shape, leaving a real gap for a validation tool with no annotations.

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

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

With a single parameter at 100% schema description coverage, the schema already documents '16-digit Iranian bank card number'. The description reinforces the domain (Iranian PAN, Luhn-checkable) but adds no format, normalization, or edge-case detail 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?

States a specific verb (validate) and resource (Iranian bank card / PAN) and adds the mechanism (Luhn check digit) plus the output (issuing bank). This clearly separates it from sibling validators such as fa_validateNationalId, fa_validateSheba, and fa_validatePostalCode.

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 no when-to-use guidance, no conditions for selecting it over the other fa_validate* tools, and no exclusions. The only additional context is pricing, which is not usage 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 carries the full behavioral burden. It usefully discloses the payment model ($0.005 per call, USDC on Base), which is real behavioral context. However, it never states what validation returns (boolean, structured result, error behavior), which is a notable gap given no output 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?

A single, front-loaded sentence that carries the resource, format, and pricing with no wasted words. Efficient, though the trailing pricing parenthetical slightly interrupts the core purpose statement.

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 single-parameter validator the description is nearly complete, but with no output schema it should state what a call returns (valid/invalid, error shape). That omission leaves the agent guessing about the result of the call.

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 single 'value' parameter is already documented as an 11-digit legal-entity national ID. The description only restates the same 11-digit constraint, adding no syntax, formatting, or normalization 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?

States a specific verb (Validate) and resource (Iranian company national ID / شناسه ملی اشخاص حقوقی) and specifies it is 11 digits. This distinguishes it functionally from the individual-ID sibling fa_validateNationalId, though it does not name that sibling explicitly.

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

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

The description gives no when-to-use guidance, no exclusions, and does not point to alternatives. With many near-siblings (fa_validateNationalId, fa_validateEconomicCode, fa_validateBankCard, fa_validateSheba), an agent gets no help deciding when a company national ID applies versus those other validators.

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 and does add genuinely useful behavioral context: the per-call cost ($0.005) and the payment rail (USDC on Base). However, it says nothing about what 'validate' means operationally (format-only vs. check-digit algorithm) or how invalid input is reported, so meaningful behavioral gaps remain.

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?

One compact sentence, front-loaded with the action and resource, followed by the format and pricing in a tight parenthetical. No sentence is wasted and nothing important is buried.

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 one-parameter validator this is nearly complete, but with no output schema the description never tells the agent what a validation call returns (boolean, valid/invalid payload, error shape). That single omission keeps it from being fully self-sufficient.

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?

There is a single parameter with 100% schema description coverage, so the schema already documents 'value' as a 12-digit economic code. The description's '(کد اقتصادی, 12 digits)' restates that constraint without adding syntax or edge-case detail, matching the baseline 3 when 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?

States a specific verb ('Validate') and a precisely named resource ('Iranian economic code', کد اقتصادی) with the 12-digit format constraint. This clearly distinguishes it from siblings such as fa_validateNationalId, fa_validateCompanyId, and fa_validateSheba without needing to open any schema.

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

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

The description gives no indication of when to use this tool versus the other validators, nor any prerequisites or exclusions. It only describes what the tool validates, leaving the agent to infer usage context from the name alone.

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 usefully discloses the cost ($0.005 per call, USDC on Base) and that it validates, normalizes, and resolves area code to city. But it does not describe the return format, error behavior, or authentication requirements, which are important for a tool with zero annotation coverage.

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, front-loaded sentence that includes the core action, scope, outcome, and cost. Every element earns its place with 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 low complexity (one required parameter), rich schema coverage, and no output schema, the description is nearly complete: it states purpose, normalization, area-code resolution, and cost. It could be improved by briefly indicating the return value or handling of invalid inputs, but it is functional as-is.

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% for the single parameter, so the schema already documents that the value is a landline in any common format. The description adds 'Iranian landline number' but does not provide additional syntax, format examples, or constraints 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 states specific verbs (validate, normalize, resolve) and a precise resource (Iranian landline number) with the additional outcome of resolving area code to city. This clearly distinguishes it from siblings like fa_validateMobile and fa_validateBankCard.

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 implied by the purpose: use for Iranian landline numbers. However, the description does not explicitly say when to use this versus alternatives such as fa_normalize or fa_validateMobile, nor does it mention prerequisites or 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, the description carries the full burden. It adds genuinely non-obvious context: cost ($0.005 per call, USDC on Base), which is valuable. However, it omits whether normalization returns a canonical string, how invalid inputs are reported, and what the return shape is.

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

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

A single front-loaded sentence with the action first and the cost detail parenthetically appended. Nothing wasted, nothing buried.

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 one-parameter tool with no output schema and no annotations, the description still leaves the return value (canonical number vs boolean) and error behavior unclear. The pricing disclosure is helpful but doesn't complete the behavioral 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?

Schema description coverage is 100% and the single 'value' parameter is already documented as 'mobile in any common format', so the schema does the heavy lifting. The description's 'normalize' hints at an output convention but adds no syntax or format detail 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 states a specific verb ('validate and normalize') and a specific resource ('Iranian mobile number'). It clearly distinguishes itself from the sibling fa_validateLandline and the other fa_validate* tools by naming the exact data type.

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 purpose implies when to use it (validating a mobile number), but the description offers no explicit conditions, no mention of the natural alternative fa_validateLandline, and no guidance on when normalization applies versus plain validation. Usage is only inferable.

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 usefully discloses pricing and the payment mechanism ($0.005 per call, USDC on Base), which is real value beyond structured fields, and 'check digit' hints at the algorithm. However it says nothing about the return result (boolean/valid-invalid shape) or behavior on malformed input.

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

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

A single sentence that front-loads the core action and folds the cost note into a compact parenthetical. Every element earns its place with 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 one-parameter validator with no annotations and no output schema, the description covers the action, the target, and cost, but omits return semantics and failure behavior. Adequate but with clear gaps an agent would have to discover by calling it.

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

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

Schema description coverage is 100% for the single 'value' parameter, and the description adds no syntax or format detail beyond what the schema already states ('10-digit national ID'). Baseline 3 applies when 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?

States a specific verb (Validate) and resource (Iranian national ID / کد ملی), and the 'check digit' qualifier pins down exactly what is being validated. This clearly distinguishes it from the sibling validators for bank cards, company IDs, mobile numbers, etc.

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

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

Usage is only implied by the resource name; there is no explicit guidance on when to use this versus the many sibling validators, nor any stated preconditions. Given the self-describing ID type, an agent can infer the right context, but nothing is stated.

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 does disclose genuinely useful operational context — the pay-per-call price and settlement chain ($0.005, USDC on Base) — but it never says whether this is a pure read-only check or what a pass/fail verdict looks like.

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

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

A single front-loaded line: identifier, format constraint, localized name, then cost. No filler, nothing that could be dropped without losing information.

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 annotations and no output schema, the description should at minimum indicate the shape of the result (boolean vs. object with reason/region). A validator's entire value is its verdict, and that is left completely undocumented.

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

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

Schema coverage is 100% for the single 'value' parameter, so baseline is 3. The description's '10 digits' constraint and Persian term merely restate what the schema already specifies, adding no syntax or format detail beyond it.

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 (Validate) plus a precise resource (Iranian postal code, 10 digits) with the local term کد پستی. Against the fa_* sibling set, the resource noun alone separates it cleanly from fa_validateNationalId, fa_validateSheba, etc.

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

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

The description says nothing about when to reach for this versus the other validators, nor any precondition (e.g. input must already be normalized digits). Usage is only inferable from the resource name.

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, and it does disclose two useful traits: the mod-97 verification method and the cost model ($0.005 per call, USDC on Base). However, it says nothing about what a call returns (boolean vs. structured result) or how invalid input is reported, which is a meaningful gap for a validator.

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?

One front-loaded sentence with the core purpose first and pricing appended parenthetically. No filler, nothing redundant.

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 single-parameter, no-nesting validation tool the description is nearly sufficient, and the cost disclosure is a bonus. The only shortfall is that, with no output schema, the return value (valid/invalid signal or error shape) is never described.

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 single 'value' parameter is documented as 'IR + 24 digits'. The description's 'Iranian IBAN/Sheba' framing adds meaning but no format or syntax detail beyond the schema, so the baseline 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?

States a specific verb (Validate) and a precise resource (Iranian IBAN/Sheba / شبا) and even names the algorithm (mod-97 check), which cleanly separates it from the other fa_validate* siblings like fa_validateBankCard or fa_validateNationalId.

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 tool's role as a Sheba validator is implied clearly, but there is no explicit when-to-use guidance, no mention of prerequisites, and no routing to or from the sibling validate tools. Adequate but leaves the agent to infer context.

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