NBG Rates (National Bank of Georgia)

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: rate publication at ~17:00 Tbilisi with next-day validity, carried-over rates on Sundays/Mondays/post-holidays flagged via carriedOver and effectiveDate, and an explicit 'error, never a guess' failure mode. That is exactly the extra context an agent needs to interpret results.

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

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

One dense paragraph, front-loaded with the core purpose, then usage, then output/date semantics. Every sentence carries information, though the 17:00/carried-over timing block is lengthy and could be tightened without losing meaning.

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 4-parameter conversion tool with annotations and an output schema, the description covers input constraints, the GEL routing rule, output-field usage (resultRounded vs result), date/rollover behavior, and error semantics. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it constrains 'from'/'to' to currency sides (one may be GEL), explains the implicit GEL conversion and the 'via' output value, and clarifies 'date' is a Tbilisi calendar day defaulting to today with post-17:00 forward availability.

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 opening sentence names a specific verb and resource ('Converts an amount between two currencies') and pins the rate source and effective-date semantics. This clearly separates it from nbg_convert_many (bulk) and nbg_rate_history (historical listing), so an agent can route correctly 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?

It gives concrete usage context: either side may be GEL, non-GEL pairs route through GEL with a 'via' value, and the date defaults to today in Tbilisi. It also implies the single-pair use case but never explicitly names an alternative tool (e.g. nbg_convert_many) or states exclusions, so it stops short of a full when/when-not statement.

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

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

The annotations already cover read-only, open-world, idempotent, and non-destructive behavior, but the description adds substantial operational context: per-item error isolation, when total becomes partial via skipped, NBG outage fallback, resultRounded vs result semantics, Tbilisi calendar rules, rate publication timing, and carriedOver/effectiveDate behavior. It also states that unpublished rates return an error rather than a guess.

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?

Despite its length, the description is front-loaded with purpose and then proceeds through item independence, aggregation, rate timing, and output-field guidance. Each sentence carries necessary behavioral detail for a complex batch-rate 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?

An output schema exists, but the description still explains crucial return-field semantics like resultRounded, result, total, skipped, carriedOver, and effectiveDate. Combined with detailed failure and rate-publication rules, an agent has enough context 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%, and the nested item fields are already documented with descriptions and defaults. The description reinforces date semantics ('calendar days in Tbilisi', default today) but adds little beyond what the schema already states for the items parameter.

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

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

States a specific verb (Converts), the resource (a list of amounts), and the key scoping rule (each at the official NBG rate in force on its own date). The phrase 'one call for a list of invoices' makes the batch purpose distinct from the single-conversion sibling nbg_convert.

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

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

Gives clear context for use: converting a list of invoices in one call, with items answered independently. It does not explicitly name when to use nbg_convert instead or state exclusions, so it falls short of full alternative routing.

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

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

Annotations already declare readOnly/idempotent/openWorld, and the description layers substantial extra behavior on top: carriedOver/effectiveDate semantics, the guarantee that unpublished dates return an error 'never a guess,' and the nbgQuantity quoting convention. This is real context the agent cannot get from structured fields.

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 nearly every sentence carries operational weight (timing, carried-over handling, error guarantee). It runs long at roughly 200 words, and the final output-formatting instruction partly duplicates what the output schema covers, but there is little true filler.

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

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

For a rate-lookup tool with an output schema, it covers everything an agent needs: default date, business-day publication timing, carried-over behavior, error-on-unpublished, and how to present multi-unit quotes. Nothing material 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%, so date, language and currencies are already fully documented, including the 17:00 timing note that the description repeats. The extra detail about nbgQuantity and GEL landing in unknownCodes concerns output interpretation rather than the input parameters, so baseline 3 applies.

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

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

States a specific verb+resource: official NBG GEL exchange rates 'in force on one calendar date.' The single-date framing implicitly separates it from nbg_rate_history, but no sibling is named explicitly, so it stops short of full sibling differentiation.

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?

Offers operational timing guidance (default is today; after 17:00 Tbilisi tomorrow can be requested), which implies when the tool applies. However, it never says when to prefer this over nbg_convert, nbg_convert_many or nbg_rate_history, leaving tool selection 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 already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the list is a today-only snapshot, absent codes may still have history, and nbgQuantity explains the quoting unit (with a concrete JPY example) that would otherwise be misinterpreted as a raw price.

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

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

Three sentences, each carrying distinct load: scope, historical caveat, and unit semantics plus alternative routing. The scoping statement is front-loaded and there is no filler.

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

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

An output schema exists, so return values need no prose explanation, and the annotations cover the safety profile. What remains — the today-only scope, the historical-gap caveat, and the quoting-unit semantics — is exactly what the description supplies.

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

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

Schema description coverage is 100% and the single language parameter is fully documented in the schema, including the en/ka enum and the default. The description adds nothing about the parameter, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Lists every currency NBG publishes a GEL rate for today') and scopes it to today's published set. It explicitly routes rate retrieval to the sibling nbg_get_rates, so an agent can distinguish it from nbg_get_rates without opening either schema.

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

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

Gives explicit routing: 'for the rates themselves call nbg_get_rates', which names the alternative and the condition that selects it. It also warns that a missing code may still have historical rates, preventing a false negative when the agent is deciding between this tool and nbg_rate_history.

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 only cover the safety profile (readOnly, idempotent, non-destructive, open world); the description goes well beyond them by disclosing carry-over semantics, the effectiveDate/carriedOver fields and when to quote them, the error on unpublished dates, the Tbilisi calendar basis, and the one-request-per-call limit. This is exactly the behavioral context an agent needs to interpret results correctly.

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 and scope are front-loaded in sentence one, and every sentence carries information (carry-over, errors, summary, request budget). The middle section is a dense run-on that takes effort to parse, but there is no filler to cut.

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

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

For a 3-parameter, single-request range query with an output schema, the description covers the edge cases that matter: carry-over days, unpublished-date errors, and the server-computed summary. Even though an output schema exists, the explanation of carriedOver semantics is the key to correct interpretation and is fully provided.

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; the description adds genuine meaning beyond the schema by fixing the unit (GEL per one unit) and the timezone basis (Tbilisi calendar days), neither of which appears in the parameter descriptions. It restates the 366-day cap rather than adding to it.

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

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

The first sentence names a specific resource (official NBG rate), its unit basis (GEL per one unit), and its exact scope (every calendar day of an inclusive range up to 366 days). That scope is clearly distinguishable from the convert and list_currencies siblings, which serve different jobs.

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

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

Usage is implied by the range-based framing, but no sibling is named and there is no explicit statement of when to prefer this over nbg_get_rates or nbg_convert. The closest thing to guidance is operational ('one NBG request per call', 'report summary rather than deriving them'), which governs use of the result rather than tool selection.

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