Switchje open data

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

With no annotations, the description carries the full burden. It usefully discloses return shape (five cheapest per day) and the edge case that a missing day had no valid run, but is silent on read-only nature, permissions, rate limits, and ordering/pagination of results.

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 with the core resource and scope front-loaded; the parenthetical for the date semantics is efficient. 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?

For a 3-param, no-annotation, no-output-schema tool, the description covers dates and the missing-day case but leaves the profile parameter and any result-ordering semantics unaddressed, so it is only adequate.

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%, so the description must compensate. It clarifies that dates are ISO and inclusive and both optional, which adds real value, but it never explains the profile parameter — it says 'standard profile' while the schema exposes a configurable profile defaulting to 'median', which is mildly confusing.

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/resource: the five cheapest offers per day for a profile over a date range. It implicitly distinguishes itself from the sibling cheapest_today (history vs. today), though it never names that sibling or the other tools.

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?

Says both date bounds are optional and what a missing day means, which implies a default-range usage, but it gives no explicit guidance on when to pick this over cheapest_today or market_summary.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the shape of the result — five offers, coarse cost split, fetch time — but says nothing about read-only status, permissions, error behavior, or freshness guarantees. This is moderate transparency for a read-oriented query, but incomplete without annotations.

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 definition is two sentences and front-loads what the tool returns before explaining the profile parameter. Every included detail — cost split, fetch time, profile source — earns its place, with 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 one optional parameter, no output schema, and no annotations, the description is reasonably complete: it explains the result shape and how to supply a valid profile. It could still clarify default behavior and whether the profile list is exhaustive, but an agent has enough to invoke it correctly.

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 input schema has 0% description coverage for the single profile parameter, so the description must compensate. It does so by explaining that profile must come from methodology()’s standard profiles and by giving examples such as 'median', 'solar', 'heatpump', and 'ev'. It does not state the default, but the added meaning is substantial.

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 and scope: the five cheapest energy offers in the Netherlands for a standard household profile on the most recent day with data. It also lists the returned cost split and fetch time, so an agent can distinguish it from the historical sibling cheapest_history without opening either 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?

The description gives no explicit when-to-use guidance or alternatives. It only points to methodology() as the source for valid profile values, which is parameter guidance rather than usage guidance. There is no mention of when to choose this over cheapest_history or market_summary.

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?

With no annotations, the description carries the whole behavioral burden. It usefully discloses the default-date fallback and the full set of aggregate metrics returned, but says nothing about permissions, rate limits, or whether profile changes the aggregation basis. That is real disclosure, but thin for an unannotated tool.

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 scope (one day, plus profile) before the metric list. Nothing is wasted, though the middle clause mixing the profile mention with the return-field list is slightly hard to parse.

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?

No output schema exists, and the description compensates by enumerating the aggregate fields returned. The remaining gap is the unexplained `profile` parameter, which is significant given there are no annotations to fill in behavior.

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 does so well for `date` (ISO format, defaults to most recent) but leaves `profile` essentially unexplained — only the word 'profile' appears, with no indication of valid values or default 'median' or how it alters results.

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 (market aggregates) and scopes it precisely to one day plus a profile, then enumerates the exact metrics returned (offers per contract type, median yearly cost, spread, cashback count, adds/withdrawals). It does not distinguish itself from siblings such as cheapest_today, which also reports same-day market figures, so it stops short of 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?

The description implies when the tool applies (defaults to the most recent day, ISO date override) but gives no explicit when-to-use or when-not-to-use guidance against cheapest_today or cheapest_history. The default-date behavior is the only routing signal an agent gets.

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?

With no annotations, the description carries the full behavioral burden, yet it does not say whether this returns static text, requires auth, has side effects, or is safe to call freely. It implies read-only reference content but never commits to it.

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 compact sentence with no padding, and the topics are front-loaded. The phrasing 'the licence and how to attribute' is slightly awkward but costs little.

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 reference tool the description covers the subject areas adequately, but it omits what a caller actually receives (return format, whether content is static) and when consulting it matters. No output schema exists to fill that gap.

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. Baseline 4 applies; no parameter-related gaps exist.

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 lists the content covered (ranking, standard profiles, licence/attribution) but never states a verb or that it returns reference documentation. An agent can infer it is an informational tool distinct from the data-oriented siblings, but the framing is vague and noun-phrase only.

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, no statement that this is reference material to consult before interpreting offers from cheapest_today or cheapest_history, and no mention of alternatives or exclusions. The agent must guess the intent from the name alone.

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?

No annotations exist, so the description carries the full burden. It usefully discloses the sentinel semantics ('empty = still on sale'), which an agent could not infer otherwise, but says nothing about it being a read-only query, result ordering, or any limits.

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 sentence that front-loads the returned data and tucks the filtering detail into a trailing clause. Slightly convoluted parenthetical, but no wasted 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?

With no output schema, the description must explain the return. It conveys the two key fields and the empty-value convention, but leaves the result shape (one row per offer per supplier? per date?) and ordering unspecified.

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% – the lone 'supplier' parameter has no description – so the description must compensate. It does: it identifies the parameter as a supplier code, gives a concrete example ('eneco'), and notes it is an optional filter.

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 – offer lifecycle, i.e. first-seen-on-sale and withdrawal dates – which is clearly distinct from siblings like cheapest_history or market_summary. The verb is implicit (it returns/queries rather than acting), but the content of the result is unmistakable.

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 states the default scope ('across every supplier we track') and that filtering is optional, which is mild usage context. There is no guidance on when to pick this over cheapest_history or market_summary, and no exclusions or prerequisites.

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