Temsor API — Turkey & EU business data

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

No annotations are provided, so the description carries the transparency burden. It discloses useful behavioral details: 8-character bank codes may resolve to a name, unknown ones return bankName null, test BICs are flagged, and XXX is treated as the primary office. It also warns that a structurally valid BIC may still be unissued, deactivated, or mistyped.

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 front-loaded with a strong purpose statement and each sentence conveys a distinct, useful idea. It is slightly long-winded because it repeats 'checks'/'ISO 9362' and includes payment-file motivation, but it never becomes verbose or irrelevant.

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 validation tool with one parameter and no output schema, the description gives strong context: it explains components, well-known names, test BICs, the directory-lookup caveat, and the possibility of false structural confidence. The only minor gap is that it doesn't describe the exact response shape for an invalid BIC, such as a valid boolean versus thrown errors.

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

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

The schema already explains the bic parameter with 100% coverage, so the baseline is 3. The description mostly restates the same length/spacing constraints and adds behavioral context such as location-code 0 semantics. It does not add meaningfully new parameter-specific guidance beyond that.

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 action ('Checks a SWIFT/BIC against ISO 9362 structure'), names the exact resource, and further explains it splits bank/country/location/branch and may resolve well-known institutions. This clearly differentiates it from the sibling validator tools.

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

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

The description gives clear context for when this tool is relevant: validating BIC structure for payment files, flagging test BICs, and confirming ISO 9362 pattern. It also provides an important when-not guarantee: it is not a SWIFT directory lookup. It does not name alternative sibling tools explicitly, but the exclusion 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?

No annotations are provided, so the description carries the full burden. It discloses important limitations: owner codes are not resolved to a company, and a valid number is self-consistent but not proof the box exists. It also explains the meaning of the category letter (U, J, Z, R). This adds valuable behavioral context beyond the schema.

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

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

The description is concise and well-structured. It opens with a clear one-sentence definition, then provides context, limitations, and category meanings in efficient sentences. There is no wasted wording; every sentence adds value.

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

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

Given the tool's complexity (single parameter, no output schema), the description is quite complete. It explains the standard, common相交s,the李晓明提供背景, limitations, and usage context. It could arguably cover failure scenarios, but for a simple validation tool it is strong.

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% (the single parameter 'code' is fully described in the schema), so baseline is 3. The description adds value by providing an example ('CSQU3054383') and clarifying the structure (owner code, category letter, serial, check digit), which gives semantic meaning beyond the schema's generic description.

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 explicitly states the tool 'Validates an ISO 6346 freight-container number' and enumerates the components (owner code, category letter, serial, check digit), which is a specific verb+resource. It distinguishes itself from siblings by focusing on container validation, unlike bic_validate or shipping_identify.

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

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

The description explains when to use it: 'Bills of lading and terminal scans mistype container numbers constantly; the check digit catches almost all of those before a customs filing.' It implies use for validating container numbers in shipping contexts, but does not explicitly contrast with siblings like shipping_identify, though the context is clear.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses the exact algorithm ('RF and the two digits move to the end, letters become 10–35, remainder must be 1'), the validation-vs-generation decision, the length constraint, and the error behavior ('bad checksum is rejected with 400'). This is exceptionally transparent about how the tool behaves beyond a generic validate-or-generate summary.

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?

Four sentences, each earning its place: the core verb, the SEPA context, the algorithm, and the rejection policy. The text is front-loaded with the main purpose and then layered with increasingly specific behavioral detail without fluff or repetition of structural metadata.

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

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

The description is complete enough for an agent to understand input forms, behavior, and a meaningful error condition. The only notable gap is that for a dual-mode tool with no output schema, the exact successful return value is not explicitly stated (i.e., what a validity check returns vs. what a generated reference looks like). Still, given the algorithmic thoroughness and clear single parameter, the omission is minor.

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

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

The schema parameter itself is well-described ('ISO 11649 RF creditor reference, or a 1–21 character payload to encode'), giving 100% coverage. The description adds practical semantics by explaining that the reference-or-payload distinction is determined by the RF+two-digit prefix, and describes the encoding transformation. It does not fully describe output content, but for a single input parameter the meaning is strongly reinforced.

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

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

The description opens with a precise verb-resource pair: 'Validates or generates an ISO 11649 RF creditor reference', making the tool's scope unmistakable. It also distinguishes the tool from siblings like iban_validate by naming a specific standard (ISO 11649) and adding the mod-97 checksum mechanism. This is more than enough for an agent to know exactly what the tool does.

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: SEPA credit transfers carry RF references, and it explicitly states when validation versus generation occurs: 'If the input already starts with RF and two digits it is validated; otherwise a 1–21 character alphanumeric payload is encoded.' It does not name alternative tools, but the mode switch is so explicit that an agent knows exactly which input type to pass.

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

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

With no annotations, the description carries the full burden. It discloses all verification checks (syntax, domain mail exchanger, disposable, role, typo) and normalization, and explicitly states the absence of SMTP probing. It does not cover authentication needs or rate limits, but provides sufficient behavioral 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?

The description is informative but slightly verbose. It front-loads the main purpose and then explains the rationale. Every sentence adds value, though some trimming could improve conciseness.

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

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

Given the 3 parameters, no output schema, and no annotations, the description provides a good level of context about what the tool does and its methodology. It lacks details on output format and error handling, but is reasonably complete for a verification tool.

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

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

Schema description coverage is low (33%), so the description must compensate. It explains the 'email' parameter by detailing the checks performed, but does not explicitly link the boolean parameters 'rejectRoleAccounts' and 'rejectFreeProviders' to their functions, though 'role-account detection' and 'disposable service' are mentioned. Adds some value but could be more explicit.

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

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

The description specifies a clear verb ('checks') and resource ('e-mail address'), and lists multiple verification aspects (syntax, domain mail receipt, disposable detection, role detection, typo correction, normalization). It distinguishes itself from competitors by explicitly stating what is not done (no SMTP probing).

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

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

The description explains what the tool does and does not do, and provides reasoning for its approach. It implicitly suggests when to use it (when reliable verification without SMTP probing is needed) but does not explicitly mention alternative sibling tools or when not to use it.

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

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

With no annotations, the description carries the behavioral transparency burden, and it does well by explaining null-rate handling, non-EU countries being recognized but returning null rates, the absence of HS/NACE mapping, and the no-roll-forward behavior. It does not specify error behavior for unrecognized countries, which remains a small gap.

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 front-loaded with a concise summary, but the second paragraph contains some repetition: the disclaimer about not being a goods classification appears twice, and the motivation example, while illustrative, is somewhat tangential. Still, the remaining detail is relevant and compact.

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

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

For a simple two-parameter lookup tool with no output schema, the description covers the key behavioral cases: null for missing dates, special handling of non-EU countries, and the no-goods-classification boundary. It does not describe the return shape or error behavior is not fully specified, but for this tool the context is largely complete.

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

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

Input schema coverage is 100%, and the description adds meaningful context to both parameters: asOf governs point-in-time lookup with no fall-forward, and country is the EU/recognized-non-EU key. This goes beyond the schema's simple descriptions of ISO dates and country codes.

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

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

The description clearly identifies the tool as a point-in-time schedule of EU-27 VAT rates (standard, reduced, super-reduced, parking) plus the Union OSS threshold. It explicitly distinguishes itself from a goods classification and from sibling tools like eu_vat_validate by stating that it returns rates, not validation or goods classification.

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 makes it clear this is for looking up dated VAT rate schedules, not for classifying goods, and even explains how it should be used instead of hard-coding rates. It mentions the important limitation that the last known rate is not reused. It could be stronger by explicitly contrasting with eu_vat_validate, but the context is clear.

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

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

With no annotations, the description fully discloses key behaviors: local format check first, never returning 'invalid' on outage, returning 'unknown' with reason, reporting country service status, 24-hour caching, and company name when available.

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

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

The description is concise, well-structured, and front-loaded with the main purpose, followed by essential behavioral details without unnecessary repetition.

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

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

For a tool with no output schema, the description covers return values (unknown, reason, service status, company name) adequately, though it does not list all fields explicitly.

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 description adds clarifying examples and the relationship between vatNumber and countryCode, enhancing understanding beyond the schema.

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

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

The description clearly states the tool validates an EU VAT number against the VIES register, with per-country format checks. It is distinct from sibling tools like email_verify or iban_validate.

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

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

The description provides clear context on when to use (for EU VAT validation) and explains behavior during outages, but lacks explicit exclusions or direct comparisons to other tools.

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 explains how the tool differs from mod-97-only validators, that it checks BBAN structure, that corrected check digits are suggested, and that bankName can be null. A slight internal inconsistency exists between 'bank and branch codes' and the later explanation only mentioning bankName, but overall behavior is well disclosed.

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

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

The description is concise and front-loaded with the core action. Each subsequent sentence adds meaningful information — why stronger validation matters, correction behavior, bank-name limitations, and what the tool is not. No wasted words or repetition.

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

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

Given that there is no output schema, the description compensates by explaining corrective suggestions, null bankName values, and country-specific resolution. It could be more explicit about the exact return fields, but the key behavioral context is present and sufficient for an agent to select and interpret the tool.

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

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

Both parameters (iban and expectCountry) are fully described in the input schema, so the description's lack of extra parameter-level detail is acceptable. It adds no new semantic or syntax information beyond schema coverage, earning the baseline 3.

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?

Opening sentence clearly states the tool's purpose: 'Validates an IBAN from any of 70+ countries: checksum, country length and in-country account structure, and resolves the bank and branch codes.' This names a specific verb, resource, and scope, distinguishing it from the many sibling validation tools by focusing exclusively on IBANs.

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 about when this tool exceeds basic checksum validation and warns against interpreting it as a SWIFT directory. It does not explicitly name alternative tools or state 'when not to use', but the limitations and unique added value are clearly implied.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It clearly discloses the weighted check-digit scheme, the supported layouts, and the important non-standard behavior that a mismatched digit returns HTTP 200 with valid:false. It also clarifies the limitation of the check, which goes beyond the minimal input schema without contradicting any annotations.

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

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

The description is compact yet informative, front-loading the core purpose before explaining formats and edge-case behavior. Every sentence contributes either task definition, input format, or important result behavior. It could trim a slight repetition of the 'not identity proof' point, but it remains well-structured.

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

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

The description covers the tool's input constraints (TD3 and TD1 line lengths), the algorithm context, and the notable valid:false response behavior. Since there is no output schema, it does partially explain the return behavior, though a more complete statement about the full result structure would be helpful. Overall, an agent can infer how and when to use the tool from the text.

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

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

Schema description coverage is 100%, so the schema already documents the MRZ string parameter. The description repeats the TD3/TD1 format details but adds the practical note that TD3 is typical for passports and TD1 for ID cards. This confirms the parameter meaning without offering substantial new semantics beyond the schema.

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

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

The description opens with a specific verb and resource: 'Parses ICAO 9303 TD1/TD3 MRZ and verifies check digits.' It clearly distinguishes itself from the broader validator sibling set by naming the exact standard and formats, and it explicitly clarifies that it is a format check, not identity proof.

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 to use the tool: to parse TD3 or TD1 MRZ strings and verify ICAO check digits. It also provides a notable exclusion by stating it is not identity proof and does not confirm issuance or holder identity, which helps an agent avoid overusing it, though it does not explicitly point to an alternative 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?

Despite no annotations, the description elaborates on the validation algorithm (Luhn variant with letter expansion), which explains why swapped letters are caught, and clarifies that a valid ISIN does not prove security existence. This gives meaningful insight into the tool's behavior and limitations.

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

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

The description is concise and front-loaded with the purpose, followed by contextual examples and caveats. Each sentence adds value 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 validation tool with one parameter and no output schema, the description covers the algorithm, accepted country code exceptions, and a clear caveat about interpretation. It does not explicitly state return values, but given the low complexity and typical validation semantics, the description is nearly 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?

The schema fully covers the single parameter with length and example. The description adds context about what the validation checks (country code, national identifier, check digit) but does not provide additional parameter-specific semantics beyond that. Baseline of 3 is appropriate given full schema coverage.

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

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

The description clearly states the tool validates an ISIN per ISO 6166, specifying the three components checked (country code, national identifier, check digit). This is specific and distinguishes it from sibling validators like iban_validate or bic_validate.

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

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

The description provides contextual when-to-use guidance via the portfolio/corporate-action failure scenario and explains edge cases (XS/EU prefixes). It does not explicitly name alternatives but identifies the tool's unique behavior and limitations, giving clear context for usage.

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

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

With no annotations, the description fully covers behavioral aspects: it explains the local checksum pre-check, caching (24 hours), rate limits (60/min), error handling (returns 'unknown' on timeout/rate limit, 404 meaning not found), and clarifies that 'status' refers to registration status, not entity status. This is exemplary transparency.

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

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

The description is dense and informative, covering multiple aspects (validation, caching, rate limits, errors, status clarification) without redundancy. It is slightly long but each sentence adds value, so it remains concise and well-structured.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers expected return data, potential errors, and operational constraints. It does not detail the exact JSON output structure, but that is acceptable without an output schema. The description is comprehensive enough for an agent to use 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?

The schema provides a description for the only parameter 'lei' ('Legal Entity Identifier, 20 characters'), giving full coverage. The tool description adds context about checksum validation but does not significantly enhance the parameter meaning beyond 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?

The description clearly states the tool's purpose: 'Looks up a Legal Entity Identifier in the GLEIF register' and specifies the returned data (legal name, registration status, country, BIC). It distinguishes itself from sibling validators like 'lei_validate' by focusing on lookup rather than validation.

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

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

The description implies usage for individual LEI lookups by mentioning checksum pre-check and a single GET request. It explicitly states 'This is not a replacement for GLEIF’s own API for bulk,' providing guidance against bulk use. However, it does not directly compare with sibling tools like 'lei_validate'.

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 well. It explains that the tool performs checksum validation only, does not call external services, and clarifies that a valid checksum does not guarantee registration. This transparently sets expectations about side effects and limitations.

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

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

The description is concise without being terse. It is well-structured: a clear purpose statement, a practical rationale, algorithm details, and a caveat about registration. While slightly verbose, each sentence adds relevant information and avoids redundancy.

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

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

Given no output schema, the description does not need to explain return values. It covers the tool's behavior, limitations, and alternative usage, making it sufficient for an agent to decide when to call it. Minor omissions like error handling are not critical for a validation tool.

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

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

The schema description already specifies 'Legal Entity Identifier, 20 characters,' providing basic semantics. The tool description adds valuable detail about the LEI structure (first 4, next 14, last 2) and the checksum algorithm, enhancing the understanding of the parameter beyond the schema.

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

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

The description clearly states the tool's purpose: 'Validates a 20-character Legal Entity Identifier (ISO 17442) with the ISO 7064 mod-97 check digits.' It also distinguishes it from other validators by focusing on LEI and explicitly notes that it does not call GLEIF, which is a separate concern.

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

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

The description provides explicit usage guidance: it is suitable for 'KYC and MiFID reporting' when a checksum check is needed, and it advises using GLEIF's API if registration status is required. This clearly differentiates when to use this tool versus alternatives.

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

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

With no annotations provided, the description carries the full behavioral burden, and it delivers: it explicitly states the measurement boundary ('only initialize and tools/list are ever called — never tools/call'), explains the daily crawl, and discloses the security-relevant storage of historical descriptions. This gives a clear picture of the tool's safety 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 description is longer than typical, but each sentence earns its place: the registered gap, the daily measurement process, the security motivation, and the tool-call boundary are all useful context. It is slightly discursive but well organized and front-loaded with the essential statement of what the tool is.

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, no-output-schema tool, the description provides a strong contextual frame: what data is collected, how often, what is never called, and why historical descriptions matter. It does not describe the output/return shape for the various views, but the schema's per-view descriptions help fill that 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?

The schema covers 89% of parameters with descriptive comments, so the description does not need to re-explain each field. The description adds general context (search, changes, server history, review scores) but does not go beyond the schema in explaining parameter-specific behavior or required combinations per view.

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

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

The description opens with a specific verb and resource: a 'searchable, dated archive of what every public MCP server actually exposes.' It clearly distinguishes the tool from the unrelated sibling validation/lookup tools by defining its own niche as an index, change feed, and rug-pull detector.

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 identifies concrete use cases: tool-level search, uptime tracking, and security change detection. It explains when this endpoint is uniquely valuable ('the only way to learn what a server exposes'), but it does not explicitly state when not to use it or name alternative search/validation tools.

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

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

With no annotations, the description carries the full burden. It discloses that the archive 'can only accumulate forward — it cannot be reconstructed after the fact,' which is a critical behavioral constraint. It also notes that providers overwrite pages and drop models quietly, explaining why the endpoint exists, and mentions that price points land in a shared time series. Missing details like auth requirements or rate limits, but the most important behaviors are covered.

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 front-loaded with the core purpose, then provides context and use cases, and ends with a critical limitation. Every sentence adds value: the problem statement, the three questions answered, the pointer to series/history, and the append-only note. It is concise for the conceptual richness it conveys.

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

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

The description covers the 'why' and 'what' thoroughly, including specific use cases and the historical context. However, it stops short of mapping the three use cases to specific `view` values or parameter combinations (e.g., which view answers the cost question), and it does not describe output structure. The rich schema descriptions partially compensate, so the tool is usable but leaves some interpretation to the agent.

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 high (80%), so the baseline is 3. The description itself does not elaborate on any specific parameters, leaving semantics to the schema. While the `view` parameter is implicitly referenced via 'catalog' and 'events' in the schema descriptions, the tool description adds no parameter-level 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 opens with a clear, specific statement: 'Dated archive of LLM prices, context windows, announced retirement dates and quiet delistings across 400+ models and 50+ providers.' This identifies both the resource (LLM pricing/lifecycle data) and the action (archiving). It also differentiates from sibling validation tools by focusing on model data rather than universal identifiers or country-specific facts.

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

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

The description explicitly lists three use cases: contract/budget cost lookups, dependency audits for silently removed models, and migration planning for announced/moved retirement dates. It also directs users to the `series/history` endpoint for full time-series queries, clearly delineating when to use which tool. This is exemplary 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 of behavioral disclosure. It explains the probe methodology (daily, temperature 0, three repeats), the condition for reporting drift (agreement among repeats and disagreement with previous run, same-day disagreement is noise), and the limitation that the alias-to-model mapping cannot be answered retroactively without this record. This is rich behavioral context covering how the tool operates and its constraints, though it does not specify output format or error behavior.

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

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

The description is concise at ~150 words but dense with essential information. It is well-structured: first a one-sentence summary, then methodology, then the drift detection rule, then view explanations. Every sentence adds value: no fluff, no repetition of schema content. The first sentence clearly states purpose, and the rest provides necessary behavioral 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 tool's complexity (5 optional parameters, 3 views, no output schema, no annotations), the description is quite complete. It explains the core methodology, the drift definition, the purpose of views, and the key constraint (no retroactive aliases). It lacks specification of return structure or error cases, but with no output schema, the agent might need more information about response format. However, for a data retrieval tool, this level of detail is strong and likely 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?

Schema description coverage is 80% (4 of 5 params described: days, view, provider, severity; limit lacks description). The description adds meaning beyond the schema by explaining the 'aliases' view answers a question that cannot be answered retroactively, and that severity is only for events. It clarifies the purpose of each view in the context of drift detection, which adds value beyond the schema's simple labels. The one undocumented parameter (limit) is self-explanatory due to naming.

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

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

The description clearly states the tool records what changed behind a provider endpoint (alias resolution and behavior shifts) with specific details on methodology (daily fixed probe suite, temperature 0, three repeats). It distinguishes from siblings like model_archive and series_history by focusing on endpoint drift measurement, not just archival or historical series.

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

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

The description explains why this tool is needed (providers update models behind stable names) and when it is appropriate (to answer 'what was actually behind an alias on that day'). It implies usage for drift detection but does not explicitly state when not to use it or mention alternatives. The context of independent measurement suggests it complements rather than replaces other tools, but no direct exclusions or alternative names are given.

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?

Even though annotations are absent, the description thoroughly discloses behavior: output is text only, line endings are LF, IBAN spaces stripped and uppercased, mod-97 not required, non-EUR rejected, structured remittance emptied, and unstructured remittance copied. This is far beyond a typical description and fully satisfies the annotation burden.

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 well-structured and front-loaded, but 'does not send money' and 'does not render a QR image' appear twice. Minor redundancy, but each sentence otherwise conveys a necessary behavior of the EPC payload.

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 no output schema and no annotations, the description covers all essential aspects: what the tool does, what it returns, edge cases, accepted currency, line-ending format, and what is intentionally omitted. An agent has enough to call the tool correctly and interpret the result.

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

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

Schema coverage is 100%, but the description still adds meaningful parameter behavior: it specifies that unstructured remittance is copied if given, structured/purpose remain empty, current currency is rejected, and IBAN normalization rules. This is valuable context beyond the schema field descriptions.

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

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

The description opens with a specific verb ('Builds') and names the exact standard and version (EPC069-12 v3.1 V2 SCT). It clearly differentiates itself by adding 'Does not send money; returns text only, no PNG,' preventing confusion with sibling tools that validate or process payments.

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

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

Provides clear context (European payments encoded in QR) and exclusions (does not send money, no PNG, non-EUR currencies rejected). No sibling tool appears to be an alternative, but no explicit 'when not to use' or direct comparison is given, so it stops short of a 5.

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

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

With no annotations, the description fully discloses behavioral traits: normalizes to E.164, classifies line types (including special ranges), resolves province for Turkish landlines, and returns both E.164 and national notation. Also honestly states the limitation on operator detection with portability caveat.

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?

Well-structured: opening summary, usage context, detailed behavior, and honest limitation. Each paragraph is purposeful, though the last paragraph could be slightly tighter without losing clarity.

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 no output schema, the description covers key aspects: input format, two output notations, line type classification, province resolution, and operator caveat. It is fairly complete for a complex validation tool, though explicit output structure details would enhance completeness.

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% (both parameters described), so baseline 3. The description adds significant semantic value by explaining that defaultCountry defaults to TR, and how Turkish numbers are handled in depth (area codes, special ranges). This goes beyond the schema's minimal descriptions.

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

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

The description clearly states the tool validates and normalizes phone numbers to E.164, classifies line type, and resolves province for Turkish landlines. It distinguishes from sibling tools by focusing on phone validation with Turkish specifics.

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

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

Explicitly recommends use in signup and checkout flows for canonical storage and early error rejection. Also clarifies what the tool does not do (report current mobile operator) and provides caveats about number portability, helping the agent avoid misuse.

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 discloses the matching algorithm (transliteration, fuzzy matching), the explanation of hits, and the `asOf` archive limitation. It does not mention authentication, rate limits, or explicit read-only behavior, but for a screening tool the key behavioral aspects are well covered.

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

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

The description is two structured paragraphs with all sentences contributing new information—no filler. It is somewhat lengthy but appropriately detailed for an 8-parameter tool, and it is front-loaded with the main purpose.

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

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

For a tool with no output schema, the description explains the hit explanation and `coverage` field, and provides parameter usage notes. It lacks explicit response structure details and error conditions, but is sufficiently complete for an experienced engineer.

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 88%, giving a high baseline, and the description adds meaningful guidance: `birthYear` as the 'single strongest false-positive filter', `type` narrowing removes false positives, and `asOf` being bounded by archive coverage. This goes beyond the schema, though not all parameters receive such enhancements.

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

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

The description opens with a specific verb ('Screens a name') and resource ('six official sanctions lists'), enumerating the exact lists (OFAC, UN, EU, OFSI, SECO, Canada). This clearly distinguishes it from sibling verification and parsing tools.

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

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

Provides clear guidance on when to supply `birthYear` (strongest false-positive filter) and `asOf` for auditor questions, implying intended contexts. However, it doesn't explicitly contrast with alternatives or state when not to use it, so it falls short of a 5.

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

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

Since no annotations are provided, the description carries full burden and does an excellent job. It discloses that the tool normalizes data (JPY-style 100-unit quotes), the default date behavior (fillGaps carries last value across weekends/holidays), and the evidence attachment feature (source URL and content hash) for long-term defensibility. This goes far beyond a basic description and provides important behavioral insights.

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

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

The description is three sentences, front-loaded with the core purpose, then providing essential detail without fluff. Every sentence adds value: purpose, current data scope/normalization, and optional parameters with their benefits. No redundant or tautological 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?

The description is complete given the tool's complexity: 6 optional parameters with good schema coverage, no output schema, no annotations. It explains the key behaviors an agent needs to know (catalogue listing, gap filling, evidence retrieval). The only minor gap is lack of explicit return structure, but no output schema exists, so the description's level is appropriate.

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

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

Schema description coverage is 67%, so the description partially compensates. It explicitly names `seriesId`, `fillGaps`, and `includeEvidence` with meaningful context beyond the schema (e.g., what fillGaps does, why includeEvidence matters). It doesn't explain 'from'/'to' formats but the schema already provides patterns and descriptions, and 'limit' is self-explanatory. The additional context on seriesId (catalogue listing) is valuable.

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

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

The description clearly states the tool returns 'the accumulated history of public data series with change statistics and a source receipt for every point.' It specifies the resource (public data series, specifically FX data) and the action (return history), distinguishing it from siblings like tr_fuel_prices or model_archive which likely serve different data types.

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

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

The description gives explicit usage context: 'Leave `seriesId` empty to list the catalogue' and explains the fillGaps and includeEvidence options for typical use cases. It doesn't explicitly state when not to use this tool vs alternatives, but given the diverse sibling tools, the unique functionality (time series history) makes usage 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?

No annotations provided, but the description fully discloses behavior: checksum verification (fully for S10, not-verified otherwise), ranked list for Turkish carriers, and explicit out-of-scope (delivery status). Rationale given for design decisions.

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 somewhat lengthy but every sentence adds value. It front-loads the main purpose and then explains nuances. Could be slightly tighter, but still 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?

Despite no output schema, the description explains return values (canonical link, ranked list, verification status) and covers edge cases, limitations, and rationale. Complete for the intended use.

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

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

Schema coverage is 100%, but description adds context: country hint narrows candidates, tracking number accepts spaces/dashes. It also explains behavioral implications (ranked list) beyond parameter definitions.

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

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

The description clearly states it identifies carrier, validates tracking number, and returns canonical tracking link. The verb 'identifies' and specific resource 'carrier for tracking number' are precise, and the tool is distinct from siblings which are other validation/address tools.

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

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

The description explains when to use (order systems routing customers) and provides context about limitations (Turkish carriers overlapping, ranked list). No explicit alternatives mentioned, but siblings are other domains, so the guidance 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?

Since no annotations are provided, the description carries the entire burden of behavioral disclosure, and it does so impressively. It reveals that the tool may return 'checksum: not-verified' for countries without public algorithms, that it refuses to guess the country, and that it does not query tax authorities. This goes beyond a simple 'validates' claim, offering critical caveats that directly affect output interpretation. The only small gap is the absence of explicit mention of errors for invalid input, but given the coverage, a score of 4 is warranted.

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 and content-rich, packing substantial information into two paragraphs. The first sentence front-loads the core purpose and method. The second paragraph provides the rationale and specific edge cases. While it is longer than a terse one-liner, every sentence adds unique and valuable context—no filler or fluff. It could be slightly more structured with bullet points for the list of countries, but this does not detract from overall effectiveness.

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

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

For a tool with no output schema and no annotations, the description is quite complete. It explains the validation logic, the varying outcomes, and the critical limitation about not contacting authorities. It also anticipates a common use case (onboarding forms) and explains the design choice to refuse country guessing. The only missing piece is an explicit statement about what the return value looks like or error behavior for invalid countries, which a brief mention would have elevated it further. Nonetheless, it covers the essential aspects comprehensively.

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

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

The input schema already provides 100% description coverage for both parameters, including format and meaning ('ISO 3166-1 alpha-2'). The description adds value by specifying that the 'tin' can include spaces or punctuation, and that 'country' is required to avoid ambiguity. It reinforces the semantic importance of the 'country' parameter by explaining why it is required (the same digits can be valid in multiple places). This exceeds the baseline for high schema coverage, justifying a 4.

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 is exceptionally clear: it explicitly states the tool validates tax identifiers for 25+ countries, specifies the method (checksum where public, format-only where not), and differentiates itself from sibling validation tools like 'eu_vat_validate' and 'tr_vat' by noting it covers multiple country formats and refuses to guess the country. It also provides a concrete list of supported checksum algorithms, leaving no ambiguity about its function.

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

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

The description explicitly addresses when to use this tool: for validating tax identifiers from a specific country, especially in scenarios like onboarding forms where garbage data is collected. It also clearly states what it does NOT do (does not ask tax authorities whether the number is issued), which actively prevents misuse. While it doesn't name sibling alternatives like 'eu_vat_validate', the context implies this is a broader, more comprehensive validation, and the specificity of the use case makes the guidance strong.

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 transparency burden. It discloses normalization of abbreviations, province/postcode cross-checking, misspelling repair, confidence scoring, and an `unparsed` list so nothing is silently dropped. It lacks explicit error-handling details, but is otherwise transparent for a parser 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?

The description is compact and front-loaded: the first sentence states the core function, the second adds behavioral guarantees, and the third provides usage context. Every sentence contributes value without unnecessary 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 parsing tool with no output schema and no annotations, the description covers the input nature, output components, normalization behavior, confidence score, unparsed fallback, and target use cases. This gives an agent enough context to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so a baseline of 3 applies. The description adds useful context about free-form Turkish addresses and cross-checking the province against the postcode, but it does not materially elaborate on the `defaultProvince` parameter 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 states a specific verb and resource: 'Splits a free-form Turkish address into neighbourhood, street, building, floor, flat, district, province and postcode.' This clearly distinguishes it from sibling validation and invoice tools in the Turkish toolset.

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 context for when to use the tool: 'Built for shipping, checkout and CRM systems that receive Turkish addresses typed by humans.' It does not explicitly name alternative tools or state when not to use it, but the use-case framing 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?

With no annotations provided, the description carries the full transparency burden. It discloses important behavior: Hijri-calendar feasts are read from an announced table, and years without official announcements return `confirmed:false` rather than guessed values. It does not describe the full return shape or behavior when both `addDays` and `end` are supplied, but the core behavioral caveat is well covered.

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

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

The description is three short sentences, front-loaded with the core purpose and followed by a necessary caveat and use-case list. Every sentence earns its place; the final fragment is slightly informal but not wasteful.

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, so the description should explain return values more fully; it only mentions `confirmed:false` without describing the overall response structure. It also does not address edge cases like supplying both `addDays` and `end`, or whether start/end dates are inclusive. For a 4-parameter tool with no annotations and no output schema, this leaves some important gaps.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by defining business days in the context of Turkish holidays and half-day eves, which directly clarifies how `addDays` and `countHalfDaysAsWork` should be interpreted. It does not clarify the relationship/conflict between `addDays` and `end`, but the schema already documents each parameter individually.

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

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

The description uses a specific verb-resource pair: 'Adds business days or counts them between two dates' and clearly scopes it to Turkish public and religious holidays. This distinguishes it from the sibling validation and lookup tools, which serve entirely 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 description explicitly names target use cases: 'delivery promises, SLA clocks, payment terms and shipping estimates.' It does not mention when not to use the tool or name alternatives, but the context is clear enough for an agent to select it appropriately.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It effectively does so by explaining carry-forward behavior (`effectiveFrom`, `carriedForward: true`), change events with percentage moves, and the inclusion of source URL and content hash for auditability. This goes well beyond a basic operation description.

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 dense paragraph that front-loads the primary purpose and then flows into usage details and audit features. Every sentence contributes meaningful information without redundancy or fluff, achieving a high information-to-word ratio.

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 that there is no output schema and no annotations, the description is remarkably complete. It covers the main query modes, edge cases (such as unchanged prices), and the nature of the response (including fields like `effectiveFrom`, `carriedForward`, source URL, and content hash). An agent can confidently select and invoke the tool based on this description alone.

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 83%, which sets a baseline of 3. The description adds meaningful semantics beyond the schema: it explains that `asOf` carries forward the previous price if unchanged, that `from`/`to` returns percentage changes, and that `province` empty lists coverage. While not every parameter gets such depth (e.g., `includeDistricts`), the added value is substantial.

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

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

The description clearly states the tool's function: retrieving petrol, diesel, and heating-oil pump prices for all 81 Turkish provinces, with support for past-dated prices. It uses a specific verb ('prices for...') and resource ('81 Turkish provinces'), and its focus on fuel prices distinguishes it from the sibling tools (e.g., email verification, invoice parsing).

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

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

The description provides concrete usage scenarios: using `asOf` to get the price on a specific date, using `from`/`to` to retrieve change events, and leaving `province` empty to list coverage. It gives clear context on when to use different parameter combinations, but it does not explicitly state when not to use the tool or mention alternatives (though no direct siblings exist).

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that totals are recomputed and sent totals ignored, VKN/TCKN checksums are verified, the amount is written in Turkish words, and the document is neither signed nor transmitted. These are meaningful behavioral traits beyond a generic 'builds an invoice' statement and set clear expectations for side effects.

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 front-loaded with a one-sentence summary followed by a focused paragraph of necessary context. Every sentence adds relevant information about validation, rounding constraints, non-goals, or next steps, 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 tool's high complexity—17 parameters, nested objects, no output schema—the description covers input format, processing behavior, validation, limitations, and the nature of the returned artifact. It tells the agent enough to know when and how to invoke the tool and what to expect back without requiring an output schema.

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

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

Schema coverage is 53%, so the description adds value by explaining how parameters affect output: line amounts/VAT subtotals/payable amount are recomputed, checksums on tax numbers are verified, and the amount is written in words. This goes beyond the schema's structural descriptions. It does not systematically explain every parameter, but the schema already covers many details and the description adds the most consequential behavioral 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 opens with a specific verb and resource: 'Builds a UBL-TR e-Invoice or e-Archive XML document from plain JSON.' It clearly states the tool's transformation (JSON to XML), its domain (Turkish e-Invoice/e-Archive), and implicitly distinguishes it from siblings like tr_invoice_parse by focusing on construction rather than parsing.

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: use this when selling into Türkiye and needing a UBL-TR document before the integrator step. It also communicates non-goals explicitly ('It does not sign the document and does not transmit it'), which helps the agent understand where this tool fits in a workflow. It does not explicitly name alternative tools or exclusion conditions, so it stops short of a 5.

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

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

No annotations are provided, so the description must cover behavioral traits. It does disclose key behaviors: namespace-agnostic parsing, normalizing single-line documents to arrays, and reporting amount mismatches via warnings instead of returning wrong totals. However, it does not mention error handling, rate limits, or other operational specifics, which is acceptable given no annotations but still some gaps exist.

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 few functional sentences, front-loaded with the core purpose and behavior. The third sentence about 'engineering time' is a few rhetorical flourish that does not add operational value, making it slightly less crisp but still efficiently structured.

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

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

Given a single parameter, no annotations, and no output schema, the description covers essential what the tool does and critical anticipations: defines the output categories, explains normalization policy, and warns about amount mismatch. It lacks a sample output format and error handling notes, but for the complexity level, it is reasonably 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?

The only parameter 'xml' is fully described in the schema with 100% coverage. The description adds behavioral context about processing the input (namespace handling, normalization) that goes beyond the schema description, providing some added meaning about how the input is interpreted.

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 explicitly states the tool parses UBL-TR e-Invoice or e-Archive XML into clean JSON and specifies the output includes parties, line items, taxes, and totals. This clearly distinguishes it from sibling tools like tr_invoice_build (building invoices) and other validation tools.

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

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

The description implies the tool is for parsing e-Invoice XML but does not explicitly state when to use it vs. alternatives. It does not mention counterpart tools like tr_invoice_build or what should be used for building invoices, leaving usage context 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 to carry the burden, the description provides deep behavioral context: statutory references, ceiling application semantics, which taxes apply or don't, and the tool's limits. Goes well beyond a basic description of what the tool calculates.

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?

Information-dense with no wasted sentences; even the legal citations and tariff context serve as behavioral cues for the agent. The prose is slightly ornate in the middle section but remains functionally relevant to understanding the tool's behavior.

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

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

For a tool computing three legal entitlements with tax nuances, the description covers input semantics and the legal limitations thoroughly. Missing a description of the return-value shape, which would help agents chain this with downstream logic.

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

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

The input schema already has 100% coverage with rich parameter descriptions, so the baseline is raised. The description adds value by explaining how parameters interact ('the ceiling is applied to the monthly wage, not the total') and the tax implications of the salary inputs. This enriches the agent's understanding of what changing the parameters actually computes.

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 specific verb 'Computes' with clearly enumerated resources (severance, notice, annual-leave) and inputs. Distinguishes itself from sibling validator/parser tools by describing computation logic and legal basis. The description reads as a domain-specific calculation tool rather than a generic validation function.

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

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

Explicitly lists boundary conditions with the 'What this will not tell you' section, warning about entitlement determination and legal consequences. Clearly states tax treatment (stamp tax, income tax exemption). Lacks explicit naming of alternative/sibling tools for when this endpoint is inappropriate, preventing a 5.

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

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

No annotations are present, so the description carries the full burden. It discloses non-obvious behaviors: 'bin' never 'bir bin', the kuruş part is read separately, and both decimal formats are accepted and disambiguated automatically. It does not describe return shape or error handling, but it adds meaningful behavioral detail beyond the schema.

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

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

The description is two short paragraphs, front-loaded with the core action and followed by useful Turkish-language rules. The final sentence is slightly promotional ('no off-the-shelf API until now') but still reinforces the use case, so there is minimal waste.

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

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

For a tool with no output schema and no annotations, the description should clarify return value and edge-case behavior; it does not. It covers purpose, use cases, and key formatting rules well, but wrapHash behavior and the exact output format remain gaps.

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

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

Schema description coverage is only 50%, and the description adds valuable amount-format semantics ('1.234,56' and '1,234.56' accepted) beyond the schema. However, currency is only self-evident from its enum values and wrapHash is left completely unexplained, so the description does not fully compensate for the coverage gap.

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

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

The description opens with a specific verb and resource: 'Writes a monetary amount out in Turkish words'. It also differentiates the tool from generic libraries by calling out Turkish-specific rules and the invoice/cheque/promissory-note context, making its purpose unmistakable.

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

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

The description explicitly frames the tool for invoices, cheques, and promissory notes, and notes it is a mandatory Turkish e-invoice field, giving clear when-to-use context. It does not name alternatives or state when not to use it, but the context is strong enough for selection.

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

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

With no annotations provided, the description carries the full burden, and it delivers thoroughly. It explains the legal rules under Turkish notification law (7201) and HMK, including the deemed-received calculation, holiday shifting, and arife exceptions. It also discloses constraints (only 'hmk' supported, no guessing of period days) and the meaning of basisDate for electronic notifications. This goes well beyond what a schema could convey.

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?

Although lengthy, every sentence contributes substantive legal or usage information. The purpose is front-loaded, followed by relevant legal background, then explicit limitations. There is no fluff or redundancy; the density is justified by the tool's complexity.

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 complex legal-computation tool with 8 parameters and no output schema, the description is remarkably complete. It explains the underlying law, the computation logic, edge cases (arife, judicial recess), and what it does not do. An agent has all necessary context to decide whether and how to call the tool, and to interpret its 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%, and each parameter already has a descriptive definition (e.g., 'type' explains the meaning of basisDate). The description adds valuable legal context—such as why basisDate for electronic is the reached date, and the significance of hasAttorney—which enriches understating beyond the schema. This is more than the baseline 3, but the schema already does a lot of work.

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

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

The description opens with a precise, verb-led statement: 'Computes the deemed-received date and the HMK deadline (with holiday shifting) for a Turkish notification, from the date the underlying event actually happened.' This clearly identifies the resource (Turkish notification deadlines) and the exact computation performed, distinguishing it from all sibling validation/lookup tools.

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

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

The description explicitly states what it does NOT cover: 'What this will not tell you: whether the notification was itself valid, or what a specific periodType... is in days for your case' and advises the caller to supply periodDays themselves. It also notes the limitation to the 'hmk' law family. However, it does not explicitly compare against alternative tools since none of the siblings are similar, so it falls just short of a 5.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It explicitly states pure local computation, microsecond latency, and deterministic results, which is helpful. However, it does not describe error handling, what happens for invalid inputs, the exact response structure, or any assumptions (e.g., country-specific rules). It goes beyond trivial, but leaves gaps.

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

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

The description is concise and well-structured: first sentence lists the types and auto-detection, second sentence highlights value-added resolution and performance. No repetition of schema info, and every sentence adds substance. It is front-loaded with the core purpose.

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

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

The tool handles multiple data types and has no output schema, so the description should clarify return format. It hints at extra details (bank, province, GS1 prefix) but does not describe the overall response structure (e.g., valid flag, details object) or error behavior. Given the breadth of inputs, this is a notable gap for an agent to know what to expect.

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

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

The input schema already describes both parameters thoroughly (coverage 100%), including type enum and value constraints. The description adds that type is optional and auto-detected, which reinforces the schema's own description. It does not add significant new parameter-level details beyond what schema already provides, so a baseline score is appropriate.

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

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

The description clearly states the tool validates a wide range of Turkish identifiers (national ID, tax number, IBAN, licence plate, etc.) from a single endpoint with auto-detection. It also lists additional capabilities ('resolves the bank behind an IBAN, the province behind a licence plate...'), making its purpose distinct from sibling tools like iban_validate or tin_validate.

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

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

The description implies a general-purpose, one-stop-shop role ('from one endpoint') but does not explicitly state when to prefer this tool over dedicated validators, nor when not to use it. It mentions auto-detection as a convenience, but lacks explicit comparisons or exclusions (e.g., 'if you need only IBAN, use iban_validate').

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

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

With no annotations provided, the description carries the full disclosure burden and does so thoroughly. It explains the supported rates, that withholding is a fraction of VAT or a GİB code, that the 2026 threshold is reported but `applies` is always null, and that the result is not a legal opinion. This goes well beyond a typical tool description.

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

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

The description is compact, front-loaded with the main purpose, and every sentence supplies useful information. It packs domain context, parameter behavior, threshold caveat, and a legal disclaimer into three sentences without fluff or repetition.

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

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

There is no output schema, so the description must partially explain return behavior, and it does: it mentions net/VAT/withholding splits, the threshold comparison, and the always-null `applies` field. However, it does not fully enumerate the output structure or handling of invalid inputs, which would have made it 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema. It clarifies that withholding is a fraction of the VAT itself, narrows the fraction range to '2/10 through 10/10', and explains the named-code option from the GİB partial-withholding list, which enriches the parameter understanding.

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

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

The description opens with a specific verb and resource: 'Splits a Turkish amount into net, VAT and (optionally) withholding.' It further distinguishes this calculator from sibling invoice/validation tools by naming the exact Turkish VAT domain concepts (KDV dahil/hariç, tevkifat) and the split responsibility between seller and buyer.

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

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

The description clearly states when this tool should be used: 'For invoice lines and checkout totals that have to show KDV dahil / hariç' and for withholding (tevkifat) situations. It gives strong context and domain applicability, though it does not explicitly name alternatives or state when not to use it.

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

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

With no annotations, the description fully carries the transparency burden. It details that forbidden letters and shifted characters cause rejection, that the check digit mismatch does not fail the VIN, and that the tool outputs fields like `checkDigitMatch` and `valid` with specific meanings. It also states limitations clearly.

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

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

The description is concise yet informative, with two paragraphs that flow logically from general validation to specific behaviors and limitations. It avoids unnecessary fluff while covering important details.

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

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

The description provides a thorough overview of what the tool validates, how it handles edge cases, and what output fields to expect (e.g., `checkDigitMatch`, `valid`). It also clarifies non-goals, making it complete for the given information. Since no output schema is provided, this level of detail is adequate.

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 parameter `vin` in the schema already has a description ('Vehicle identification number, 17 characters') and constraints (minLength 11, maxLength 24), covering the basics. The tool description adds context about validation behavior but does not further explain the parameter itself (e.g., accepted formats or examples). Baseline is 3 since schema coverage is 100%.

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

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

The description clearly states the tool 'validates a 17-character VIN' and lists specific aspects (forbidden letters, ISO 3779 check digit, WMI region/manufacturer, model year, plant). This is specific and distinguishes it from sibling validation tools like bic_validate or email_verify.

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

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

The description implies usage when a VIN needs validation, and it clearly sets expectations by explaining what the tool does not do (does not decode the full vehicle, does not prove the VIN was issued). However, it does not explicitly contrast with alternatives beyond the natural inference from the tool name.

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