FiLot: Indonesian gold prices and bar records

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, yet the description adds genuinely useful behavior: multiple quote tiers (highest price fitting every bar, prices fitting only some bars such as 2026 Antam), per-quote dealer and day, and a world-gold-price estimate fallback when no dealer lists the brand. The garbled clause 'when no dealer FiLot reads prices the brand' obscures part of the fallback logic.

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 intent is front-loaded, but the body is one dense run-on sentence and contains a corrupted phrase ('when no dealer FiLot reads prices the brand'), which costs clarity. There is real information here, but it is not cleanly 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?

With no output schema, the description carries the return-shape burden and largely does so: it enumerates the highest price, partial-fit prices with dealer and day, and the estimate fallback. Combined with full schema coverage of the three inputs and solid annotations, an agent has enough to call 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?

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by tying the brand parameter to concrete coverage behavior (which brands have dealer prices, which fall back to an estimate) and by emphasizing that grams refers to exactly ONE bar. This adds decision-relevant meaning the enum-free brand 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 (buy back / pay), resource (one gold bar of a given brand and weight), and currency (rupiah), so an agent can tell it is about dealer buyback quotes rather than spot price or tax. It does not name or contrast with siblings like gold_price_sources, so differentiation is only inferable from content.

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?

Implies the context well: it is the tool to use when you need what Indonesian dealers pay today for a single bar, and it explains the two regimes (brands with dealer prices vs. brands that fall back to a world-price estimate). No explicit when-not-to-use or alternative-tool routing is 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?

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 and closed-world, so safety is covered. The description adds genuinely useful non-schema context: the source is BULI2, a supplier with a commercial relationship (FiLot's sister company), it has not been reviewed by a tax consultant, and the output is general information rather than tax advice. Those provenance and reliability caveats materially change how an agent should present the answer.

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?

A single dense sentence delivers the topic inventory, then appends source and disclaimer. It is front-loaded with the subject matter and every clause carries information. Slightly list-heavy, but no filler sentences.

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 read-only, closed-world knowledge tool with no output schema and no query parameter, the description covers the domain, the topics returned, and the trust caveats. The one residual ambiguity is whether the tool returns a fixed fact sheet or answers targeted questions, which an agent might want clarified given the absence of a question parameter.

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

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

Only one parameter (lang) exists and schema description coverage is 100%, with the enum values id/en already documented in the schema. The description adds nothing about language selection, so this sits at the baseline where the schema does all the 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 names a specific resource (Indonesian tax facts for physical gold bars) and enumerates the exact topics covered: PPN, PPh 22, individual buyers, selling back, the Rp 10 million limit, stamp duty, Antam buyback deduction. This clearly separates it from siblings like gold_buyback_prices and verify_gold_bar_record. It stops short of an explicit verb (e.g. 'returns' or 'answers questions about'), so it is clear rather than crisp.

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 topic list — an agent asking about Indonesian gold taxation would pick this tool, and the sibling domains (prices, sources, verification) are plainly disjoint. However, there is no explicit when-to-use statement, no guidance on whether it answers a specific question or dumps the full fact set, and no stated exclusions beyond 'not tax advice'.

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.