Swellmeter Trending

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds one genuinely useful behavioral detail — that each country carries a 'last read time', signalling possible staleness — but says nothing about how the data is refreshed or ordered.

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 no filler, and the count (30) plus payload are front-loaded. It is lean, though so terse that it omits the verb that would make the intent unambiguous.

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 input parameters and no output schema, the description carries the burden of describing the return shape, and it does so concisely (codes, names, last read time). Nothing critical is missing for a simple enumeration endpoint, though ordering/pagination behavior 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. Schema coverage is 100% and the empty object matches the description's implication of an unfiltered full listing.

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 resource and its exact payload ('30 country codes, names and last read time'), which is enough to infer it lists supported countries. However, it is a bare noun phrase with no verb, so it never actually states that the tool returns/lists anything, and it does not distinguish itself from siblings like cross_country_trends or topic_history.

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 or when-not-to-use guidance, no mention of alternatives, and no statement of prerequisites. An agent must infer from the name alone that this is the reference list to consult before calling the trend 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 and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond them: 'right now' recency and the 'most countries first' result ordering, neither of which appears in the schema. It says nothing about auth, rate limits, or result size, so it lands at a solid 3 rather than higher.

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 front-loaded sentence with no filler. The scope constraint and the output ordering both earn their place, and there is nothing an agent must read past to get the core behavior.

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-only tool with no output schema and no nesting, the description covers the result ordering and the country threshold but omits what 'limit' controls and what the returned items look like (topic, count, country list?). Adequate but with visible gaps for an agent that must interpret the response.

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 0%, so the description must compensate. It clarifies the meaning of minCountries by stating the '2+ of the 30 countries' universe and implicitly explains the lower bound seen in the schema, but it never explains the 'limit' parameter or its units. Half the parameters are left to inference, which caps this at a mid score.

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 ('topics trending right now') and scope ('in 2+ of the 30 countries'), which distinguishes it from single-location siblings like trending_now or trending_day. It does not name those siblings explicitly, so an agent gets the gist but no direct routing hint.

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 cross-country framing plus the 'right now' recency, which suggests this is the multi-country real-time trending tool. There is no explicit when-to-use statement, no mention of when trending_now or trending_day is preferable, and no prerequisites.

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, so safety is covered. The description adds value by disclosing the return shape (countries, first seen, last day seen, peak traffic), which matters since there is no output schema.

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 sentence, front-loaded with the action and scope, then the payoff (returned fields). No filler, though the return-field list makes it slightly heavy for a single clause.

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?

Covers the return fields well given no output schema, and annotations cover behavior. But with 0% schema description coverage, geo and days semantics are missing, which is a meaningful gap an agent must infer.

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 0% and the description only loosely maps to the params: 'topic' for q, 'countries' hints at geo, and 'last 30 days' hints at days. It never explains that geo is a country filter or that days overrides the default window, leaving two of three params undocumented.

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?

Clear verb+resource: 'Search the last 30 days of trending searches for a topic.' The 30-day historical window distinguishes it from siblings like trending_now and trending_day, though no sibling is named 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 the temporal framing ('last 30 days'), which suggests a historical/lookup use case versus live tools, but there is no explicit when-to-use or when-to-prefer-a-sibling guidance.

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 establish readOnly/idempotent/non-destructive/openWorld semantics, so the burden is lighter. The description still adds genuine behavioral context the annotations don't: the 30-day lookback bound, the 1-5 country cap, ordering ('biggest first'), and the returned fields (first/last seen, peak traffic, news).

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, front-loaded sentence with a scope-first structure ('Every trending search seen on one UTC day...'). Nothing is wasted, though the trailing clause stack ('with first/last seen, peak traffic and news') makes it a bit run-on.

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 does so by enumerating the fields returned. Missing coverage of the limit and minTraffic parameters keeps it from being fully complete for a 4-parameter 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 only 25% (geo, limit, minTraffic are undocumented in the schema), so the description must compensate. It does add real meaning for geo ('1-5 countries') and date ('today or last 30 days', 'one UTC day'), but says nothing about limit or minTraffic, leaving half the parameters ambiguous — partial compensation, not full.

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 (trended), resource (trending searches), and precise scope (one UTC day, 1-5 countries). It is clear what the tool returns, though it never names a sibling like trending_now to make the day-vs-live distinction 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?

The description implies usage via the date window ('today or the last 30 days'), which tells the agent this tool covers historical days, unlike the live sibling trending_now. However, there is no explicit when-to-use/when-not or any routing to cross_country_trends or topic_history, so the agent must infer the choice.

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 value by enumerating the returned fields (query, traffic, start time, first-seen, other countries, news links), which is behavior an agent would otherwise have to guess at.

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 that front-loads the resource and scope, then lists outputs. No filler, no redundancy with the name or 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 no output schema, the description does the right thing by describing return fields, and annotations carry the safety profile. However, it omits the 'limit' parameter and any routing guidance relative to trending_day/cross_country_trends, leaving gaps for a multi-country trending tool with siblings.

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 50%: geo is documented in the schema and the description usefully reinforces the 1-5 country limit and ISO-2 format, but the 'limit' parameter (1-10) is undocumented in both schema and description. The description partially compensates but leaves one of two params unexplained.

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 — newest Google trending searches — and scopes it to 1-5 countries with ISO-2 codes. It does not, however, differentiate itself from siblings like trending_day or cross_country_trends, even though 'other countries where it trends' overlaps semantically with the latter.

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 explicit when-to-use guidance or mention of alternatives. The word 'Newest'/'now' implies a real-time counterpart to trending_day, but the agent must infer that routing decision rather than being told it.

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