Tanod Finance

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

Beyond the annotations (readOnly/idempotent/non-destructive/openWorld), it discloses case-sensitivity rules per address format, latency ('under 0.1 s, first call up to 1 s'), price (USD 0.002), a shared free-tier pool, and the disclaimer/list_date semantics. This is exactly the extra behavioral context the annotations cannot 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?

Purpose is front-loaded and the dense detail (formats, return fields, limits, pricing, disclaimer) is largely information-bearing. It is long and reads as a wall of text, but almost every clause earns its place for a paid, caveat-heavy screening tool.

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

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

With no output schema, the description enumerates the return fields (matched, matches with sdn_uid/sdn_name/etc., list, list_date, list_addresses, source, disclaimer) and covers scope, caveats, cost, and latency. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and there is a single parameter, so the schema already carries the format. The description still adds value by explaining the case-sensitivity distinction between EVM/bech32 (case-insensitive) and base58 BTC/TRX (exact match), which the schema does not state.

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 ('screen one crypto address against the US OFAC SDN list's digital currency addresses'), naming the exact list and scope. The word 'one' implicitly distinguishes it from the sibling check_sanctions_batch, so an agent can tell them apart.

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

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

It gives rich usage context: scope limits (OFAC SDN crypto addresses only, no other lists, no clustering/ownership/exposure analysis), the caveat that a non-match does not clear an address, and verification guidance. However, it never explicitly names check_sanctions_batch as the alternative for multiple addresses, so routing between siblings is left to inference.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description layers on substantial extra behavior: 422 vs 5xx error semantics with explicit 'not charged' notes, typical latency (<0.1 s, up to 10 s on refresh), caching signals returned (`cached`, `stale`), per-IP daily quota shared across routes, and the ECB attribution/licensing constraint. This is well beyond what the annotations provide.

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

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

Front-loaded with purpose, then inputs, returns, error/pricing, then licensing — a sensible order. It is dense and somewhat long, repeating 'ISO 4217' three times and duplicating parameter details already in the schema, but nearly every sentence carries operational or compliance 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?

No output schema exists, and the description compensates by enumerating the return fields (`base`, `date`, `rates`, `cached`, `stale`, `attribution`). Combined with error behavior, rate limits, pricing, and latency, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: the ~30-currency default for `symbols`, the previous-publication-day fallback for non-publication dates, and the fact that non-EUR bases yield cross rates computed to 8 significant digits. It also restates the parameter list, which is redundant but harmless.

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

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

States a specific verb+resource ('foreign-exchange reference rates for a base currency') and pins the source ('European Central Bank (ECB) euro foreign exchange reference rates'), which cleanly separates it from the crypto-flavored siblings like get_token_price and get_swap_quote. An agent can identify the tool's domain without opening the schema.

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

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

Usage context is implied rather than stated: the ECB sourcing and the 90-day date window tell the agent this is for official daily FX reference rates, not live trading quotes. However, no alternative or sibling is named, and there is no explicit 'use this instead of X' or when-not-to-use guidance. Minimum-viable routing information.

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?

Well beyond the readOnly/idempotent/openWorld annotations, it discloses the 422 failure mode for unsupported country/subdivision/language/year, that failures are not charged, latency (~0.1 s), price (USD 0.001), and a shared free pool of 10 calls per IP per UTC day. It also flags the accuracy limitation of the underlying rules for lunar, religious and one-off holidays.

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

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

Front-loaded with the core purpose, then inputs, return shape, errors, performance and pricing in a logical order. Slightly dense and repeats a few schema details (year range, country examples), but nearly every sentence carries information an agent needs.

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

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

With no output schema, the description still sketches the return shape (`holidays` rows of {date, weekday, name} plus count, source and note). Combined with error behavior, latency, pricing, rate limits and accuracy caveats, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it restates country as ISO 3166-1 alpha-2 with examples, clarifies subdivision accepts either a code or a name, and explains that invalid values produce a 422 naming the supported values — failure semantics the schema does not convey.

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

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

States a specific verb and resource — 'public holidays of a country for a year' — and the title adds the utilpeek namespace. No sibling in the list covers holidays, so there is no ambiguity about which tool to reach for.

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

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

There is no competing sibling tool to route away from, and the description supplies a genuine usage boundary: results are computed from python-holidays rules, not an official calendar, so legal/payroll use requires confirmation with an official source. It does not spell out when to prefer subdivisions or language variants, 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?

Annotations already cover readOnly/idempotent/openWorld, but the description adds substantial behavioral context beyond them: 422 (unbilled) for unsupported pairs, latency 0.2-1 s, USD 0.002 cost, a shared 10-reads/IP/day free pool, and an untrusted-data warning about page/on-chain strings.

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

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

Dense and front-loaded with the core read action, then inputs, return fields, failure mode, timing and cost. It is long and somewhat run-on, but nearly every clause carries operational information an agent needs.

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

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

With no output schema, the description enumerates the returned fields (price as exact decimal string, decimals, round_id, updated_at, age_seconds, stale with heartbeat rule, feed address), plus error and cost behavior. An agent has everything needed to call 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% so the baseline is 3, but the description adds meaning the schema does not: which pairs are valid on ethereum vs base, and that chains are limited to ethereum|base. The enum values themselves are already in the schema.

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

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

States a specific verb and resource ('read a token price from a Chainlink on-chain price feed') and explicitly distinguishes itself from the DEX-spot-price approach used by siblings like get_swap_quote. An agent can tell what this returns without opening the schema.

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

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

The framing as a 'deterministic oracle answer, not a DEX spot price' implicitly routes the agent away from spot-quote siblings, and the free-tier/pricing context helps decide when to call. However, it never states an explicit 'use this instead of X when...' condition, so the guidance is context rather than a rule.

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

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

Annotations already declare it read-only, idempotent, non-destructive and open-world, but the description adds materially more: an invalid identifier is a normal charged answer vs a 422 malformed request (not charged), the value is processed in memory and not logged or stored, typical latency under 0.1s, price USD 0.001, and a shared 10-call/day free tier across utilpeek routes.

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?

Content is front-loaded: purpose, inputs, returns, charging semantics, scope limits, privacy, price. The one redundancy is re-listing the full 25-value kind enumeration verbatim from the enum, but the rest of the prose is dense and earns its place.

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

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

There is no output schema, and the description compensates by naming the return fields (`valid`, `reason` with sample failure values, `compact`, `formatted`, kind-specific `detail`) and explaining billing/error semantics. An agent has everything needed to call it and interpret the result 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% and the enum fully enumerates kinds, so the description largely restates structured data. It adds only marginal semantic value (luhn = generic mod-10, the card-number prohibition), which is already mirrored in the schema's kind description, so the baseline applies.

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

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

States a precise verb+resource ('check the format and check digits of an identifier') and immediately names the exact domain via the `kind` enumeration. It also carves out what it is NOT (not an existence, registration, registry, bank or VIES check), so an agent can place it against siblings like check_sanctions or inspect_domain without reading schemas.

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

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

Gives explicit when-to-use (offline format/check-digit validation), when-not (existence/registration/active status), and named alternatives (no VIES call; the EU `vat` kind is format-only). It further constrains input with a hard exclusion: no payment card numbers and none under `luhn`, which prevents a foreseeable misuse.

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