KeepUp

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new context — that results are denominated in USD and that it draws on 'Public data', implying no auth or user scoping — but says nothing about coverage gaps, caching, or behavior for unsupported country codes.

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?

Two sentences: the first front-loads what is returned and in what units, the second supplies usage triggers. No filler, no repetition of the title.

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 a single parameter, no output schema, and annotations covering safety, the main burden is describing the return shape — and the description does enumerate the percentile cutoffs. A minor gap is what happens for countries without data, though the sibling list_supported_countries partly covers discovery.

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 the ISO 3166-1 alpha-2 format and the 'WORLD' sentinel fully documented in the schema itself. The description only adds that the country selects which national distribution is returned, which is close to restating the schema — 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 and resource ('Return the household net worth thresholds') and enumerates exactly which cutoffs come back (median, top 25%, 10%, 5%, 1%) for a given country. It implicitly separates itself from siblings like net_worth_percentile by taking a country rather than a net worth value, but never names an alternative 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?

Gives a concrete trigger example ('what net worth is top 1% in the UK') and a second use case (building a wealth-distribution table), which is clear context for when to call it. It stops short of exclusions or naming which sibling to use when the question is the inverse (net worth → percentile).

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 declare readOnly, idempotent, closed-world and non-destructive, so the description's added value here is real: it discloses rounding, a minimum group size of five, that results are never individual, and that the population is self-selected rather than a national census. That is meaningful disclosure beyond structured fields, though it says nothing about rate limits, caching, or how sparse cells are represented.

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?

Two tight sentences, front-loaded with what is measured and followed immediately by the scope filters and the important population caveat. No sentence could be removed 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?

There is no output schema and no annotations gap to cover, and the description does describe the return content (percentiles plus a leading asset class). The phrase 'the asset class most of them are led by' is slightly garbled, leaving mild ambiguity about whether the asset class is modal or tied to a specific percentile, which is the only real omission.

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?

With 100% schema description coverage, the schema already documents the ISO code/'WORLD' convention and the age-band enum. The description only reinforces the defaults ('Omit for WORLD', 'optionally') without adding format or behavioral detail beyond the schema, 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?

The description names a concrete resource and its shape: net worth at the 25th/50th/75th/90th percentiles plus a dominant asset class, scoped by country and optional age band. That is specific enough to distinguish it from a plain percentile tool, but it never names the nearest siblings (net_worth_percentile, net_worth_by_age, country_net_worth_thresholds), so differentiation is left implicit.

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 'worldwide or in one country, optionally within an age band', which tells an agent which filters are combinable. There is no explicit when-to-use/when-not or pointer to the alternative tools, so an agent must infer that net_worth_by_age or net_worth_percentile may be the better pick for narrower asks.

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 the safety profile is covered. The description adds value beyond them by disclosing the shape of each result entry and explaining the breakpoint flag's meaning ("higher precision at the tails") — the only real gap is what to do if a country is absent.

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?

Two sentences, zero filler, with the resource and payload front-loaded and the call-to-action second. Nothing would be lost by trimming and nothing is missing that belongs here.

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 zero-parameter discovery tool with no output schema, the description supplies what the agent actually needs: the resource, that a per-country precision flag comes back, and that the output feeds country-code arguments elsewhere. Its only undischarged burden is the exact return format, which is low-risk for a simple enumeration.

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 no parameters, so there is nothing for the description to disambiguate and the baseline applies. Nothing in the text adds or obscures parameter meaning.

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 ("List every country KeepUp has wealth-distribution data for") plus the per-entry payload ("whether it has full survey breakpoints"). It reads clearly as the discovery/enumeration tool in contrast to the net-worth query siblings, though no sibling is named to make the boundary explicit.

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?

"Call this to discover valid country codes" gives a concrete triggering condition tied to the sibling tools that need a country code. There is no explicit when-not guidance or named alternative, but for a zero-param lookup the positive case is unambiguous.

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, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: US medians come from the Federal Reserve while other countries are labeled estimates, which matters for how an agent should present confidence in the numbers. It does not describe pagination or result shape, but neither appears to apply.

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 output content is front-loaded in the first sentence, then age semantics, then usage examples, then provenance — a sensible ordering with no filler. It is dense but every clause carries information an agent needs; only the long comma-separated first sentence is slightly heavy.

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 describing returns, and it does so by naming the three statistics returned per age group. The only residual gap is that it does not indicate which countries are supported, though list_supported_countries exists as a sibling for that.

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 to the age parameter: it spells out the group bins (under 35, 35 to 44 … 75 or older) and explains that passing an age singles out the group it falls into. That resolves the ambiguity of how a continuous age maps to a bucketed result, which the schema only gestures at.

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 and scope: household net worth by age of household head, returning median plus top 10% and top 1% cutoffs per age band. It also enumerates the age bands, so an agent knows exactly what the returned rows represent. It stops short of naming sibling tools like country_net_worth_thresholds or net_worth_percentile to distinguish the dimensions, which keeps it from a 5.

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 three concrete natural-language query examples ('average net worth at 30', 'top 1% net worth at 40 in the US', 'median net worth by age in Germany'), which effectively tells the agent when this tool is the right pick. It does not state exclusions or point to the sibling tools for threshold- or percentile-shaped queries, so the routing guidance is implicit 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 declare read-only, idempotent and closed-world, so the safety profile is covered. The description adds useful context that the data is public aggregate with no personal or account information, and it describes the returned values (percentile and top X%) in the absence of an output schema. It does not cover edge behavior such as out-of-range or unsupported country inputs.

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-loads the core operation in the first sentence, then supports it with examples and a privacy note. The three examples are slightly redundant but each illustrates a distinct case (country, single-amount, age-qualified).

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 three-parameter read-only lookup with no output schema, the description supplies the return values and the data provenance, which is the main missing piece in structured fields. Only edge-case behavior and sibling routing are left out.

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 net_worth_usd, country (ISO alpha-2 or 'WORLD') and the optional age. The description's example 'is $200k good at 30 in the US' adds intuition about how age is used but no syntax or constraints beyond the schema. 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?

Opens with a specific verb and resource: given a net worth and country, return the wealth percentile and 'top X%'. The example queries make the direction of the lookup unambiguous, though it never names the sibling country_net_worth_thresholds, which appears to be the inverse operation.

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?

Three concrete example questions ('what percentile is $500k in Germany', 'is $1M a lot in Japan', 'is $200k good at 30 in the US') give clear situational guidance and implicitly show the age variant. There is no explicit when-not-to-use clause, and the agent must infer that threshold-style questions belong to a sibling.

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