ID & Format Oracle

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, and the description adds genuinely new context: validators are all tried, results are ranked with checksum-bearing types above pattern-only ones, matches are structural not proof of type, and the confidence tiers are explained. It also names the response fields and a disclaimer, which is unusually thorough.

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 behavior and usage trigger, then the example, ranking rule, and confidence semantics. It is dense but mostly earns its space; the enumeration of response fields is somewhat redundant given the output schema, which keeps it from being maximally 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 an output schema and annotations present, the description nonetheless covers the selection logic, ranking order, confidence meaning, example invocation, and the limitation of structural matching. An agent has everything needed to choose and call 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 100%, so the baseline is 3. The description still adds meaning by explaining that country causes national validators to be tried in addition to international ones, and gives a concrete example ('12345678901', 'KW'), which clarifies the scope of the country parameter beyond the schema wording.

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 an exact verb and resource: tries every validator for a country plus international ones and returns the identifier types that accept the value, ranked. The phrase 'Use when a document or form field holds a number of unknown type' cleanly separates it from sibling validate_identifier, which operates on a known 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?

Gives a clear triggering condition (unknown identifier type in a document/form field) and implies the alternative of validating a known type. It does not explicitly say 'do not use when the type is already known' or name validate_identifier, so a small inference step remains.

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, so the safety profile is covered; the description instead adds genuine behavioral context the annotations cannot convey — the data_confidence tiers (high = check-digit algorithm vs low = structure only) and the caveat that results are 'structural validation only — never proof that an identifier is issued or belongs to someone'. That disclaimer is real decision-relevant nuance; it loses a point only because much of the enumerated response field list is redundant with the 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?

Front-loaded with purpose and scale, then usage routing, then response shape — a sensible ordering with no filler sentences. It is dense, though the trailing enumeration of result fields/data_version/sources runs long for content the output schema already provides.

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?

Covers purpose, cost, the routing relationship to validate_identifier, and the crucial interpretive caveat. Since an output schema exists, the return-value explanation is optional. The one gap is scale handling: with 250+ catalogued codes and two optional filters, nothing says whether results are paginated or return fully unfiltered.

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 both filters are fully documented in-schema (ISO alpha-2, 'INTL', and the full category list). The description only restates 'filterable by country and category' and adds no format or edge-case guidance beyond what the schema already says. Baseline 3 applies since the schema is doing 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 and resource ('Catalogue of the identifier codes this service validates'), gives scale (250+ across 90 countries plus international standards), and explicitly names the downstream sibling it feeds ('Call it once to find the right code for validate_identifier'). An agent can separate it from validate_identifier/detect_identifier 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?

Clear usage context: 'Call it once to find the right code for validate_identifier' plus the 'Free' cost signal tells the agent this is the cheap discovery step before validation. It stops short of explicit exclusions (e.g. when to skip the catalogue and call validate_identifier directly with a known code), so it is strong but not a full when/when-not pair.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description focuses on the value-added disclosure: the confidence tiering (high/medium/low), the presence of data_version and sources, and an explicit disclaimer about what validation does not prove. This is meaningful behavioral context an agent cannot infer from 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?

Front-loaded with the validation scope, then the example, then the response contract. The response sentence is dense and parenthesis-heavy but every clause carries interpretive value; nothing is 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?

With an output schema present and full annotations, the description needs little more, and it usefully explains the confidence tiers that a bare schema would not convey. The only mild redundancy is enumerating response fields that the output schema already declares.

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?

Only one parameter, and the schema already documents it fully (100% coverage) including the 8-or-11-character format and the 'EBILAEAD' example. The description repeats the same example rather than adding new constraint detail, 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?

States a specific verb (validate) and resource (BIC, ISO 9362) and enumerates the sub-checks performed: structure, country code, test-BIC flag, bank and branch parts, and bank name lookup. This is clearly distinguishable from siblings such as validate_iban, validate_phone, and validate_postal_code by resource 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?

Usage context is clear from 'structural validation only — never proof that an identifier is issued or belongs to someone,' which tells the agent the limits of what the tool answers. It does not explicitly name an alternative or exclusion, but sibling names make the routing obvious.

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?

The description adds substantial context beyond the read-only, idempotent annotations: it explains the validation rules, the data_confidence levels, the bundled registry limitation, and the important disclaimer that structural validation is not proof of issuance or ownership. These details materially improve safe interpretation of the result.

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 definition is front-loaded with the core action and stays focused, but the response-field enumeration is somewhat dense given that an output schema exists. The disclaimer and confidence semantics justify most of the 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 single-parameter validation tool with annotations and an output schema, the description is complete enough for correct invocation and result interpretation. It covers validation scope, returned data, confidence semantics, provenance, and the structural-only caveat.

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 iban parameter is already documented in the schema. The description gives an example but does not add meaningful syntax or semantic detail beyond what the schema provides.

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

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

The description names a specific verb and resource and clarifies the validation scope: ISO 13616 length, mod-97, and national BBAN rules. It also lists the returned data. It does not explicitly distinguish itself from siblings such as validate_identifier or validate_bic, which keeps it below 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 IBAN-specific scope and the example, but the description does not state when to choose this tool over validate_identifier or validate_bic. No exclusions or routing guidance 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?

Goes well beyond the readOnly/idempotent annotations: it defines the data_confidence tiers (high = public check-digit spec, medium = community checksum/pattern, low = structure only) and states the crucial limitation that results are structural validation only, never proof of issuance or ownership. It also discloses the returned fields (checks performed, reason when invalid, extracted details).

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 purpose, then example, then response shape — a sensible order. It is dense and long for two parameters, and some response-field enumeration overlaps with the output schema, but no sentence is pure 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?

Since an output schema exists, the response summary is largely redundant, but the confidence-tier semantics and the disclaimer add meaning the schema cannot convey. Everything an agent needs to call it correctly is present; only the sibling-selection question is left open.

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 already 100%, and the description still adds value with a concrete worked example ('784-1990-1234567-1' with code 'ae_emirates_id'). It does not add anything about number normalisation beyond what the schema's tolerance note already covers, so it is above baseline but not materially so.

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 ('Validate and normalise one identifier') with a clear scoping constraint, 'whose type you know', which implicitly separates it from detect_identifier. However, the overlap with type-specific siblings (validate_iban, validate_bic, validate_phone, validate_postal_code) is never addressed, so which tool to pick for an IBAN remains ambiguous.

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 phrase 'whose type you know' gives a clear usage condition and implicitly routes unknown-type cases to detect_identifier. It stops short of naming that alternative explicitly, and gives no guidance on when to prefer a dedicated validator (validate_iban) over this general one.

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?

The description adds tremendous value beyond annotations. It defines the three tiers of data confidence (high/medium/low) and provides a critical disclaimer, clarifying that the validation is 'structural' and not proof of active issuance.

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 with technical information (e.g., data_version, sources[], time zones), which necessitates a longer format. However, every sentence provides essential technical context rather than repetition.

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

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

Given the complexity of international telecommunications and identification, the description is complete. It fully outlines the various output formats, derived metadata, and the limitations of the validation.

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?

While the schema coverage is 100%, the description enhances the input semantics by advising when the 'default_region' parameter can be omitted (i.e., when the international format is provided).

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 specifies the function: parsing, validating, and formatting phone numbers. By using this specific functionality, it clearly distinguishes itself from the sibling validation tools (e.g., validate_bic, validate_iban).

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

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

It provides an explicit example of input format (number '050 123 4567', default_region 'AE'), guiding users on when certain parameters are necessary. The focus on phone numbers versus other identifiers makes usage context clear.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive, closed-world), it discloses real behavioral traits: 158-country coverage, handling of no-postal-code countries, a pattern-only scope, and the meaning of high/medium/low data_confidence tiers. Some return-field enumeration overlaps with the output schema, but the confidence semantics and explicit non-guarantees add genuine 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 core purpose is front-loaded in the first sentence, and every part of the paragraph carries useful information. The response-field listing (estimated_items[], sources[], data_version) is somewhat dense and could have been shortened by referring to the output schema, but it does not derail the overall 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?

With annotations, a full input schema and an output schema, the description supplies the missing behavioral context: coverage, confidence tiers, limitations and a concrete example. It is complete for an agent to call correctly, though the response-field detail is somewhat redundant given 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?

Schema coverage is 100%, and both parameters are fully documented in the input schema. The description adds only an illustrative example ('11564', 'SA'), which slightly reinforces the intended format but does not provide syntax or constraint details beyond what the schema already 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 names a specific verb (validate/check) and resource (postal/ZIP code format) and scopes it to 158 countries, which clearly separates it from the IBAN, BIC, phone and generic identifier validators in the sibling list. However, it never explicitly names an alternative tool or routing rule, so it stops short of the 5-level distinction.

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

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

It gives a clear usage boundary with 'Pattern check only' and the disclaimer that it is 'never proof that an identifier is issued or belongs to someone', which tells the agent when not to rely on it. It also notes behavior for countries without postal codes, though it does not explicitly direct the agent to sibling tools for other identifier types.

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