EVS Meter Tools

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety and repeatability are covered structurally. The description adds that the value is 'current' (i.e. a live figure) and denominated in SGD, which is useful context beyond the annotations. It does not disclose freshness/latency or what happens when a meter has no prepaid account.

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 short sentence with the key qualifiers ('current', 'prepaid', 'SGD') front-loaded and no wasted wording. It is arguably terse to the point of omitting routing guidance.

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 only two fully documented required parameters, an output schema covering return values, and annotations carrying the safety profile, the description is nearly complete. The one real gap is disambiguation from the three sibling meter/top-up tools.

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%, with both meter_id (8-digit pattern) and system (enum of institutions) fully documented in the schema. The description adds no meaning beyond that, so the 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 ('Get'), a specific resource ('current prepaid credit balance of a meter') and adds the currency unit (SGD). An agent knows exactly what is retrieved, but the description does not distinguish this from siblings such as get_meter_usage or get_recent_topups.

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 name and by 'prepaid credit balance', so an agent can infer this is the balance-check call rather than a consumption or top-up call. However there is no explicit when-to-use guidance and no mention of the sibling tools or when to prefer them.

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 the safety profile (readOnly, idempotent, openWorld), yet the description still adds substantive behavior: a 7-day cap, SGD denomination, EVS-supplied dates with no time zone, possible missing recent days, and a meter-type restriction. Nothing contradicts the annotations; the only gap is no mention of pagination or error behavior for invalid meter IDs.

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 in the first clause, and each following sentence delivers distinct, non-redundant information: currency, date semantics with the missing-days caveat, then the meter-type exclusion. No filler or restatement of the name.

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 one-parameter read tool with an output schema, the definition covers scope, units, temporal semantics, data-quality caveats, and eligibility. It is nearly complete; only error/failure behavior for an unknown or unsupported meter is left unstated.

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 pattern-constrained parameter, so the schema carries the documentation load; baseline 3 applies. The description adds only a mild framing constraint (the meter is an NUS meter, not any 8-digit EVS ID) without extending the ID format or behavior.

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?

Names a specific verb and resource ('Get up to 7 days of usage for an NUS meter') and enumerates the return contents: spending analysis, month-to-date spending, balance longevity. It implicitly separates itself from get_meter_balance/get_recent_topups via the usage-vs-balance distinction, but never names a sibling 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?

Provides one hard exclusion, 'Not available for SUTD meters', and warns that recent days may be missing. It gives no positive routing guidance telling the agent when to reach for this tool versus get_meter_balance or get_recent_topups, so selection still requires 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 only cover read-only/idempotent/open-world, but the description adds substantial non-obvious behavior: a hard 10-result cap, the fact that older top-ups can share the same amount, and — most importantly — the timezone asymmetry where result dates are unlabeled Singapore time (UTC+8) while createdAt is ISO 8601. It also discloses eventual-consistency semantics: no match may mean 'not recorded yet' or 'failed', so the agent should retry later rather than double-pay.

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 in the first clause, and the following sentences are operational guidance rather than filler. The date-matching rule is stated twice in spirit ('check the date' after explaining older top-ups can share an amount), a mild redundancy, but overall it is dense and task-relevant.

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 two-parameter read tool with an output schema and read-only annotations, the description supplies everything needed: result cap, matching heuristic, date-format/timezone caveat, and fallback behavior on an empty result. Return-value shape is left to the output schema, which 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 100% and both parameters (meter_id with an 8-digit pattern, system with a two-value enum) are already documented. The description adds no parameter-level detail such as where to obtain meter_id or how 'system' affects results, so it is at the baseline.

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 with explicit scope: 'Get up to 10 recent top-ups for a meter.' The bounded result size is conveyed up front. It does not name the sibling tools (get_meter_balance, get_meter_usage, get_topup_link) to differentiate, though the 'top-up list' resource is naturally distinct from balance/usage/link-creation.

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?

"To confirm a payment..." gives a concrete situation for calling the tool and implicitly positions it downstream of a link creation ('its link'). No explicit when-not or named alternative is given, and it doesn't state prerequisites (e.g. needing a meter_id from a prior lookup).

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?

Beyond the readOnly/idempotent/openWorld annotations, the description discloses the critical financial behavior (creating the link charges nothing), the rejection rule for unknown meters, the degraded-mode signal (meterVerified false when EVS is unreachable) and the recommended follow-up. That is exactly the extra context 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?

Four short sentences, front-loaded with the action and the no-charge reassurance, with no filler. It is slightly telegraphic and uses the unexplained acronym 'EVS' without expanding it, which costs a point but not the overall efficiency.

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 explanation, and the description still covers the failure modes an agent must handle: rejected meters, unverifiable meters, and per-institution amount bounds. Nothing needed to call this 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 schema already documents all three parameters and the baseline would be 3. The description adds real semantic value by constraining amount_sgd per institution (NUS $6-$50, SUTD $10-$50), which is not encoded in the schema and prevents invalid calls.

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: 'Create a link to the secure top-up page,' and clarifies the delegation model ('for the user to open and pay by card themselves'). This is clearly distinct from the read-only siblings get_meter_balance, get_meter_usage, and get_recent_topups, so an agent can pick it without inspecting other 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?

It gives clear usage context: the link itself costs nothing, unrecognised meters are refused, and if EVS is unreachable the agent should ask the user to verify the meter on the page. It does not explicitly name alternatives or state a triggering condition such as 'use when the user wants to add credit,' but the surrounding siblings make the intent unambiguous.

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