Text & Number Toolkit

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

Adds substantial context beyond annotations: deterministic output, no logging, response fields, Arabic number–noun agreement, minor-unit handling, and CLDR currency naming. These details help the agent understand domain behavior beyond the safe-read annotation profile.

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

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

The purpose is front-loaded, and the paragraph packs examples, language behavior, style behavior, and response details without obvious filler. Every sentence contributes actionable 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?

Given the output schema and rich annotations, the description supplies the remaining domain context: determinism, no logging, Arabic agreement rules, currency naming, and style semantics. An agent has enough information to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents all parameters; the description still adds useful meaning through the amount example, the 56-language scope, and the effect of style='cheque'. It does not fully restate all parameter constraints, but it adds meaningful domain 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?

States a specific verb and resource: convert a currency amount to words, with concrete domains (cheques, invoices, contracts) and language scope. It is distinguishable from generic siblings like number_to_words by its currency-specific behavior, though it does not explicitly name 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?

Gives clear use contexts ('for cheques, invoices and contracts') and explains that style='cheque' adds the customary wrapper. It lacks explicit when-not guidance or named alternatives, but the intended usage is clear.

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

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

Annotations already cover readOnly/idempotent/non-destructive/closed-world, and the description adds genuinely new behavioral facts: deterministic processing with no AI inside and no logging. The response field list is somewhat redundant given an output schema exists, but the determinism and logging guarantees are real added value.

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 behavioral core (what converts, what stays untouched) is front-loaded in the first sentence, and the second carries guarantees and return shape. The inline list of response fields is a bit dense and largely duplicated by the output schema, slightly diluting efficiency.

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

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

For a two-parameter, read-only transformation with an output schema and full annotations, the description covers purpose, scope, determinism, and privacy. The only gap is the absence of explicit guidance on when to pick this over sibling normalization/formatting tools.

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 'to' enum is documented in the schema but 'text' has an empty description. The description partially compensates by making clear that the entire text is scanned and non-digit characters are preserved, which is the key semantic an agent needs, but it adds nothing about the 'to' values beyond the schema's enum.

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

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

States a specific verb (rewrite) and resource (digits) with the exact three numeral systems named, plus the scope qualifier 'anywhere in a text, leaving everything else untouched.' An agent can distinguish it from format_number or normalize_arabic by intent, 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?

Usage is implied by 'anywhere in a text,' which suggests whole-string conversion rather than formatting a single number, but there is no explicit when-to-use versus normalize_arabic, format_number, or transliterate, and no stated preconditions. The agent must infer the routing decision from sibling 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?

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds meaningful context beyond annotations: it is free, deterministic with no AI inside, nothing is logged, and the response includes confidence, estimated items, sources, version, and warnings.

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 front-loaded, starting with what is detected before moving to response and behavioral notes. Some response-field listing may be redundant with the output schema, but the overall wording is efficient.

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

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

For a single-parameter detection tool with an output schema and rich annotations, the definition is largely complete: it describes outputs, determinism, privacy, and response metadata. The main gaps are input expectations and explicit routing versus sibling tools.

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 only parameter is `text`, but its schema description is empty and the tool description only says the analysis is of 'a text.' It does not add constraints, format expectations, or examples, so it fails to compensate for 0% schema description coverage.

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

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

The description clearly states the resource analyzed and enumerates specific outputs: script proportions, dominant script, RTL/LTR direction, mixed-script flag, digit systems, and script hints. It does not explicitly contrast with sibling tools such as transliterate or convert_digits, so sibling differentiation is left implicit.

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 does not say when to use this tool versus alternatives like transliterate, convert_digits, or normalize_arabic. The output list implies it is for script analysis, but no explicit usage context, exclusions, or alternatives are provided.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new behavioral facts beyond them: deterministic with no AI inside and no logging of inputs, which matters for a formatting utility handling possibly sensitive amounts.

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

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

Front-loaded with the core capability and grouping examples, then the example, then the response. Mostly earns its space, but the enumeration of response fields (data_confidence, estimated_items, sources, data_version, warnings) is redundant given an output schema exists.

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?

An output schema exists, so return values need not be explained, and the description instead wastes a clause listing them. Everything an agent needs to call it correctly is present: scope, example, determinism, and no-logging guarantee; only explicit sibling routing is absent.

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 high (83%) and already documents locale, currency, decimals and numbering well. The description adds marginal but real value by showing the three-parameter interplay (locale+style+currency) and illustrating grouping outputs per locale, though the per-locale grouping examples largely echo the schema's locale hints.

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 (format/number) and enumerates the exact behaviors: grouping variants, decimal mark, currency symbol placement, Arabic-Indic digits under CLDR. It is clearly not parse_number or number_to_words, but it never names or explicitly contrasts with those siblings, leaving the agent to infer the boundary.

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 worked example (1234567.891 / en_IN / currency / INR) implies when the tool applies, but there is no explicit when-to-use, when-not, or routing to alternatives such as number_to_words or format vs. parse_number. 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?

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the description correctly spends its words elsewhere: 'Free', 'deterministic (no AI inside)', and 'nothing logged' are genuine behavioral facts not present in structured fields. Listing the response envelope (data_confidence, estimated_items, sources, data_version, warnings) is partly redundant with the existing 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?

Three short sentences, purpose first, then cost/determinism, then response shape. The explicit enumeration of response fields is the only low-value material, since an output schema already exists and the agent will see those fields at call time.

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 parameters, full annotations, and an output schema, the surface area is small and the description covers the essentials: what data it exposes, that it is free and non-AI, and that nothing is logged. The missing piece is workflow guidance, which is scored separately under usage.

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 tool takes zero parameters, so the baseline is 4 and there is nothing for the description to compensate for. The description does not waste space inventing parameter semantics.

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

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

The description names the resource — languages for words, Arabic-grammar currencies, and locale notes — but never uses a verb like 'list' or 'returns', leaving the action implied by the name alone. An agent can infer it is a metadata/enumeration tool, but the phrasing 'Languages available for words, the curated Arabic-grammar currencies' is ambiguous about exactly what is enumerated.

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 call this versus the conversion siblings (number_to_words, amount_to_words, etc.), nor any suggestion such as checking supported languages before requesting word output. The agent must infer the workflow entirely.

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

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

Annotations already cover read-only, idempotent and non-destructive semantics, and the description adds genuinely new behavioral facts: "reports exactly which rules changed the text," "deterministic (no AI inside)" and "nothing logged." The privacy and determinism guarantees are meaningful context an agent could not infer from the schema or annotations.

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

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

Two dense sentences with zero filler, front-loaded with the operation and its rule set before any response detail. Every clause carries information an agent can act on.

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 9-parameter tool with an output schema, the definition covers the rule set, optionality, determinism and logging behavior, which is enough to call it correctly. Minor gaps remain: no guidance on non-Arabic or empty input, and the response field enumeration largely duplicates the output schema.

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

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

At 78% schema description coverage the schema already documents nearly every flag with examples (٠-٩ → 0-9, ة → ه). The description largely restates that list rather than adding new semantics; its only added signal is calling out ة→ه and ى→ي as optional, which the schema's default:false already conveys.

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

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

Uses a specific verb-plus-resource opening ("Clean Arabic text") and enumerates the exact transformations applied, immediately separating it from siblings such as detect_script or transliterate. The stated goal ("for matching, search and storage") tells an agent what class of task this serves.

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

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

The description gives clear context for when this tool applies (matching, search, storage normalization) and flags the two spelling-changing rules as optional, which is the key usage decision. It stops short of naming alternatives or stating when not to use it (e.g., when detection via detect_script is the actual need).

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral facts — deterministic output with 'no AI inside', nothing logged, and a warning/confidence envelope — which matter for trusting the result. The return-field list partly duplicates the output schema, keeping it just short of a 5.

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

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

Dense but front-loaded: the capability, mode list, and example come first, with the response/determinism note second. The response-field enumeration is somewhat compressed into a run-on list, but no sentence 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?

With full annotation coverage and an output schema present, the description needs only to convey purpose, mode semantics, and trust characteristics — all of which it does. The one substantive gap is routing guidance relative to the near-synonym sibling amount_to_words, which is left to inference.

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 all three parameters are already documented in the schema, giving a baseline of 3. The description adds a little value by illustrating the 'to' enum in a worked example and noting Arabic-Indic digit acceptance is handled, but it introduces no new syntax or constraints for 'language' beyond what the schema states.

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 transformation (number → words) and enumerates the three variants it produces (cardinal, ordinal, year) across 56 languages, with a concrete worked example. It does not, however, distinguish itself from the sibling amount_to_words, which an agent could plausibly confuse with this tool.

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 through the example (number 2026, language 'en', to 'year'), with no explicit statement of when to pick this over amount_to_words or parse_number/format_number. It also doesn't point to list_languages for discovering valid language codes despite advertising 56 supported languages.

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

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

Goes well beyond annotations by disclosing that the engine is deterministic ('no AI inside'), that 'nothing logged', which Hijri convention is used (Umm al-Qura), and what precision/language/relative-base metadata is returned. These are non-obvious behavioral traits an agent would otherwise not know.

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

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

Front-loads the core purpose with examples, then covers params and response shape. It is dense and packs several ideas into one paragraph, but virtually every clause carries information; minor trimming of the fully-duplicated example would help.

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

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

For a 6-param tool with an output schema and full annotation coverage, the description supplies everything needed: input formats, when to pass hints, determinism/privacy behavior, and a sketch of the response. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so parameters are already well documented. The description adds only mild value by echoing 'Pass languages and date_order when known' and noting relative base is reported, but adds no syntax or format 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 and resource ('Turn a date written in natural language... into an ISO date/datetime') with concrete multilingual examples including Hijri. This clearly separates it from numeric siblings like parse_number or convert_digits.

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

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

Gives actionable guidance ('Pass languages and date_order when known') and implies the tool's context via examples. However, it never explicitly contrasts with siblings or states when NOT to use it (e.g., for pure numbers), leaving some inference to the agent.

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

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

Annotations already cover read-only, idempotent, closed-world and non-destructive behavior, so the bar is lower. The description still adds real value: it declares determinism ('no AI inside'), the fact nothing is logged, that heuristic fallbacks are clearly flagged, and that confidence/warnings are surfaced — all beyond what the annotations say.

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

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

It is front-loaded with the transformation and its examples in a single dense sentence plus a worked 'de' example. The enumerated response fields (result, data_confidence, estimated_items[], sources[], data_version, warnings[]) duplicate the existing output schema and are the one part that does not fully 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 two-parameter, read-only tool with an output schema and full schema coverage, the description supplies what structured fields cannot: determinism, no logging, heuristic flagging. The only omission is an explicit statement of what happens when the text cannot be parsed at all, which warnings[]/data_confidence only hint at.

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 text and locale are documented with the same examples, making the description largely redundant here. Its only marginal addition is restating that locale separators are tried first with a flagged heuristic fallback.

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+deliverable: turn human-written number text into an exact decimal, with four concrete input shapes. That clearly separates it from format_number (the inverse direction) and number_to_words, though it never names a sibling explicitly, so sibling differentiation is left implicit.

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 examples (use it when you hold a human-written numeric string) and the locale-then-heuristic precedence tells the agent how to pick a locale. There is no explicit when-to-use vs when-not-to-use guidance and no pointer to convert_digits or format_number as 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavioural facts: deterministic with no AI inside, nothing logged, confidence flagging for Arabic, and the shape of the response. The 'not an official spelling' warning is exactly the kind of caveat an agent needs to decide whether the output is safe to use downstream.

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

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

Front-loaded with the core verb and scope, then caveats, then behaviour. The trailing enumeration of response fields (result, data_confidence, estimated_items[], sources[], data_version, warnings[]) partly duplicates the output schema, which costs some tightness, though the 'deterministic, nothing logged' clause in the same sentence still 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 one-parameter, read-only, idempotent tool with full schema coverage, this description covers purpose, inputs, output shape, determinism, privacy, and the main quality caveat. An agent has everything needed to call it and to interpret a low-confidence 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?

Schema coverage is 100% for the single 'text' parameter, so the baseline is 3; the description goes slightly beyond by enumerating accepted scripts and warning that certain inputs (Arabic names) yield degraded, low-confidence output. It adds no format or length constraints on the input, so it does not fully compensate for anything the schema lacks.

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 — 'deterministic romanisation of any script to plain ASCII' — and enumerates the covered scripts (Cyrillic, Greek, CJK, Devanagari, Thai, Arabic). It is clearly distinguishable from siblings like detect_script (identifies script) or normalize_arabic (script-specific normalisation) without opening any schema.

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

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

Names concrete use cases — slugs, sorting, matching, and systems that reject non-ASCII — which gives an agent a clear trigger condition. It also flags a caveat case (Arabic names produce a consonant skeleton flagged low confidence). It stops short of explicitly naming alternatives such as detect_script or normalize_arabic as the preferred tools in overlapping situations.

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