FiLot: gold prices and gold bar records

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety bar is low; the description adds genuinely useful behavior: a brand-coverage list, a documented fallback (estimate plus Galeri 24 Sentra Buyback line) for unlisted brands, partial-fit price handling, and an explicit 'numbers only, no advice' stance on offer_idr. It stops short of describing ordering, currency rounding, or what happens when a brand/size has zero matches.

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 dense and mostly earns its place, but it is delivered as a single ~110-word run-on sentence with nested parentheticals and a mid-sentence clause shift ('and a world-gold-price estimate when no dealer FiLot reads prices the brand'), which is hard to parse on first read. Bullet-like structure would serve this complexity far better.

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 carries the return-value burden and does so: best fitting price, partially-fitting prices, dealer and day, world-value comparison, and offer comparison. What remains missing is the shape of the response for a brand/size with no data at all.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the key semantic that grams is the weight of exactly ONE bar and enumerates brands, but adds no syntax or format detail beyond what the schema already documents.

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: what Indonesian dealers pay today to buy back ONE bar of a given brand and weight, in rupiah. That is enough to separate it from gold_price_on_date (asking/spot price) and world_gold_price, but no sibling is named, so the routing is left to inference.

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 implicitly defines the use case (valuing a bar someone wants to sell) and describes which brands get real dealer quotes versus the FiLot/world estimate fallback. However, it never states when to pick this over gold_price_on_date or verify_gold_bar_record, nor any prerequisites, so guidance is implied rather than explicit.

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 safety (readOnly, idempotent, non-destructive). The description adds valuable context beyond annotations: data availability start dates (22 Oct 2026 for world price, 25 Sep 2026 for Antam buyback), the fact that the world price reflects 'the day's last reading', and that the result is 'signed, with a link to check it'. This gives the agent useful expectations about output provenance 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 a single long sentence with nested parentheticals, which makes it somewhat dense. The core purpose is front-loaded, but phrases like 'for records such as a tax return, an inheritance or a purchase' and 'A record of the price, not advice' add length without much operational value. It could be more structured for easier parsing.

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 carries the burden of explaining return values, and it does so adequately: world price in any currency, Antam buyback for Indonesia, signed with a verification link, plus data coverage dates. It lacks exact output format details but provides enough context for an agent to understand what it will get.

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 all three parameters thoroughly. The description mentions 'any currency' (aligning with the currency parameter) and 'for Indonesia' (hinting at the Antam buyback data), but adds no syntax, format, or behavioral details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the resource (gold price on a past date) and the specific data returned (world price in any currency, plus Indonesia Antam buyback). It distinguishes itself from current-price siblings by emphasizing 'past date', though it does not name any alternative tool explicitly.

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

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

Usage is implied by 'on a past date' and 'for records such as a tax return, an inheritance or a purchase', but there is no explicit guidance on when to use this versus siblings like world_gold_price or gold_buyback_prices. The agent must infer that this is for historical lookups rather than current prices.

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 readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the ingestion cadence (3 times a day) and the freshness indicator (latest price day per source), which tells an agent whether the underlying data may be stale. It does not describe return format, but that gap is minor relative to what it does add.

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 efficient sentence with no filler, and the key content (which sites are read, at what cadence, and the freshness marker) is front-loaded. It is a fragment rather than a full sentence, but nothing in it is wasted.

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

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

With no parameters, no output schema and a simple read-only metadata payload, the description covers the essentials: the sources, the cadence, and the fields per source. Only minor detail is missing (how many sources, exact return shape), which is acceptable given the tool's simplicity.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no parameter semantics to compensate for. The description correctly spends its words on the return content instead.

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

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

The description names the specific resource — the Indonesian dealer websites whose prices FiLot ingests, plus the products and latest price day — so an agent knows exactly what metadata this returns. It doesn't explicitly differentiate itself from siblings like gold_buyback_prices or indonesian_gold_tax, but the subject matter is distinct enough to be identified without opening another 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?

There is no when-to-use guidance and no alternatives are named. The intended use (checking data provenance or whether a price source has gone stale) must be inferred from the phrase 'the latest price day of each', with no explicit framing of when an agent should call this instead of the price siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real value beyond them: 'Nothing is stored and no receipt is kept' confirms no persistence, the price-source sentences explain the openWorld behavior, and 'A general calculation, not a fatwa' sets the authority boundary. It does not disclose rate limits or failure modes for price lookups.

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 verb and resource, then conditions. Dense but every clause carries information (nisab thresholds, price sources, madhhab handling, disclaimer). It is a single long paragraph that could be split for scanability, which keeps it below a 5.

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 7-parameter calculator with full schema coverage and no output schema, the description covers methodology, pricing sources, worn-jewellery handling and the non-fatwa disclaimer. The main gap is that it never says what the result contains (zakat due, nisab status, both-views breakdown), which matters since there is no output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining the religious and numerical rationale behind parameters: 85 g gold / 595 g silver nisab, 2.5% rate, one hijri year haul, karat-vs-fineness handling, and why worn_jewellery offers multiple views. This meaningfully aids correct parameter selection.

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: 'Work out zakat (zakat al-mal) on a person's gold', immediately distinguishing it from the sibling tools, which are all price lookups, tax, or record verification. The scope (per-person gold zakat calculation) is unambiguous.

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 conditional context for the key branches: Indonesia uses the Antam buyback price, elsewhere the world gold price in the person's currency; worn jewellery is shown both ways unless the person states a madhhab. It does not explicitly route away from siblings or say when not to use it, but the conditional guidance is 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?

The annotations already establish that this is a read-only, idempotent, non-destructive, non-open-world tool. The description adds meaningful provenance and limitation context by naming BULI2 as the source, noting it has not been reviewed by a tax consultant, and clarifying that the output is general information rather than tax advice.

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: it first identifies the tax facts covered, then adds the source and disclaimer. Every sentence adds useful information, and there is no redundant restatement of the tool name or annotations.

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 informational tool with one optional language parameter and no output schema, the description is complete enough. It defines the subject matter, lists the tax areas covered, and discloses the source reliability limitation, so an agent can decide whether to call it.

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?

There is only one optional parameter, lang, and the schema fully documents its enum values and default. The description does not mention the parameter, but with 100% schema description coverage, the schema already carries that burden, so the baseline score of 3 is appropriate.

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

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

The description states a specific resource, Indonesian tax facts for physical gold bars, and enumerates the exact topics covered: VAT, PPh 22, individual buyers, selling back, the Rp 10 million limit, stamp duty, and Antam buyback deductions. This makes it clearly distinguishable from sibling tools about prices, zakat, verification, and world gold prices.

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 topic scope implies when the tool is relevant, but there is no explicit guidance on when to use it versus alternatives such as gold_zakat or the price tools. The caveat that it is general information and not tax advice is useful, but it does not route the agent between sibling 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?

Annotations already declare readOnly, idempotent, openWorld, non-destructive, so the safety profile is covered. The description adds distinct context: it checks against the public Solana blockchain, requires an exact link from the owner or papers, and clarifies the verification target is the record, not the physical metal. It does not mention response format or error cases, but with annotations this is solid.

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 tightly packed sentences, front-loaded with the action and target, then the accepted link forms, then scope limitations. 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?

Given only one parameter, full schema coverage, no output schema, and rich annotations, the description covers purpose, input requirements, and scope limits well. It could go slightly further on what a verification result looks like, but for a read-only single-input tool it is complete enough.

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 link parameter is already documented. The description adds the two URL patterns as examples, which mildly reinforces the expected format beyond the schema, but the schema already carries the primary meaning. Baseline 3 is appropriate.

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

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

Specific verb (checks/verifies) and resource (FiLot gold bar record) against a named target (public Solana blockchain). It also clearly delimits scope: 'It verifies the record, not the metal' and 'A serial number alone is never checked,' distinguishing it from any sibling that might deal with prices/tax.

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 states the required input form (owner share link or delivery check link) and explicitly rules out an alternative input (serial number alone). This tells the agent when this tool applies and what it cannot be used for.

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 goes further by naming the upstream data sources (gold-api.com and open.er-api.com), noting the returned timestamp, and flagging the world-market indication caveat — genuine context beyond the annotations, though caching/freshness or rate-limit behavior is unstated.

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, front-loaded with the core deliverable and units before the data-source provenance and caveat. Dense but each sentence contributes; the source attribution is arguably secondary and could be trimmed.

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 must convey the return shape, and it does: price per gram, troy ounce and kilogram plus the read timestamp, in the requested currency. Combined with the market-indication caveat, an agent has everything needed to call and interpret it.

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 both parameters are already documented with their ISO 4217 pattern and default. The description restates the currency examples and format but adds nothing new, and it never mentions the 'lang' parameter at all. Baseline 3 applies when the schema carries the parameter burden.

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 resource (today's world spot gold price) with explicit units (one gram, one troy ounce, one kilogram of fine gold) and scope (the currency asked for). The closing line 'A world-market indication, not what any dealer pays or charges' implicitly separates it from the sibling gold_buyback_prices, so an agent can distinguish it 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 is implied rather than stated: the market-vs-dealer caveat steers the agent away from buyback tools, but there is no explicit 'use X instead' or condition listing. No prerequisites or exclusions (e.g. historical prices, date arguments) are given.

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