MAD Synapse · World

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 behavioral context beyond that: data provenance (static dataset + World Bank), that there are no rate limits, that the tool is free, and that errors return isError with a message and are not charged. Return format is covered by the 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?

Front-loads the value proposition (the field list), then provenance, then price and error semantics. Dense but every clause carries information; only the 'Price: free' note is marginal given no pricing annotation exists to contradict it.

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 source data, freshness (latest World Bank figures), cost, and error behavior, while the output schema handles return values. For a single-parameter lookup tool this leaves nothing an agent needs 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?

One parameter at 100% schema coverage, and the description's 'name or ISO code' phrasing merely restates the schema's own description. No additional syntax examples (e.g. 'US' vs 'United States' vs 'USA') are provided, 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 resource and enumerates the exact fields returned (capital, population, GDP, currencies, languages, calling code, TLD, time zones, driving side, borders, flag), which clearly separates it from siblings like geocode, wiki, or fx_rates. An agent can identify this as the country-facts tool 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 context is implied by the field list and data provenance ('world-countries dataset plus latest World Bank figures'), but the description never says when to prefer this over geocode, wiki, or fx_rates, nor does it state any exclusions or prerequisites. Adequate but leaves routing to 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 already declare readOnly/idempotent/openWorld/non-destructive, so the safety bar is met. The description adds genuinely new behavior: USGS real-time feeds refreshed every minute, free pricing, and that invalid input or upstream failure returns isError without charge.

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-loaded with the core scope, then a compact trailing clause for source, price and error semantics. Every sentence earns its place; the single long sentence is dense but not padded.

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 an output schema present and 100% param coverage, the description need not explain return values, yet it flags the key returned fields and covers cost and error behavior. Complete for an agent to call it correctly; only pagination/ordering nuance ('largest first') lives solely in the schema.

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 the schema already documents all five parameters with ranges and defaults. The description only re-expresses the magnitude filter and radius condition ('only when a place is given') and maps the window to 'last hour to 30 days', adding marginal value over the schema.

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 and scope: worldwide earthquakes over a look-back window, filtered by magnitude and optional place radius, returning depth/tsunami/alert fields. It is easily separable from the nearest siblings (weather, geocode, sun_moon) even 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?

Clear context for when it applies: recent quakes, magnitude floor, and radius only when a place is given. No explicit when-not-use or named alternatives, but no sibling overlaps functionally, so the guidance is sufficient for routing.

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, non-destructive, open-world behavior, and the description adds substantial context beyond them: upstream source (Frankfurter/ECB reference rates), update cadence (~16:00 CET working days), coverage window (since 1999), cost (free), and error semantics (isError with message for invalid input or upstream failure, not charged). This is exactly the behavioral disclosure the 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?

Front-loads the core purpose, then source/cadence, then the sibling redirect, then cost and error behavior. Every clause carries information (coverage window, cadence, cost, error handling) with no filler or repetition.

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 an output schema present, return-value shape need not be explained. The description covers source, cadence, coverage window, modes, cost, error behavior, and the crypto alternative — everything an agent needs to invoke it correctly and interpret failures.

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; the description goes further by framing parameter combinations as modes (latest vs. any date since 1999 vs. amount conversion vs. time series), which clarifies how date/end_date/amount interact. It adds mode-level meaning but no per-parameter format detail beyond the schema.

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 the resource (official ECB reference exchange rates for 30 major currencies) and the concrete verbs/modes (latest, historical date since 1999, amount conversion, time series). It explicitly distinguishes itself from the crypto sibling by naming crypto_price, so an agent can select 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?

Gives one explicit exclusion and redirect: 'For crypto use crypto_price.' Provides data-source and freshness context (published each working day ~16:00 CET) that helps the agent decide relevance, but offers no guidance on the modes' relative use or when not to call it beyond the crypto case.

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 the safety profile (readOnly, idempotent, openWorld, non-destructive), while the description adds pricing ($0.001 per call, 10 free/day, payment-required result listing x402 options), error behavior (isError, not charged on failure), data provenance (OpenStreetMap via Photon), and returned OSM links. That is substantial context beyond the structured fields.

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 core purpose is front-loaded with arrow notation, then clearly labeled 'When to use', 'Price', and 'Errors' sections. Every clause carries information 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?

With an output schema present, return values need not be explained, yet the description still notes city/state/country/postcode fields and OSM links. Pricing, error handling, data source, and limits are all covered for this moderately simple two-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 100%, so both parameters are already documented, including the limit range and the 'address/place, or lat,lon for reverse' query format. The description largely restates these (limit → 'up to 10 candidates', reverse via lat,lon) rather than adding new syntactic or format detail, so 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?

The description states a specific verb (geocode/reverse geocode) and resource (place name or address → coordinates, or lat,lon → nearest address), and explicitly covers both directions of the operation. An agent can immediately tell what the tool produces 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?

Includes an explicit 'When to use' clause ('To turn names into coordinates') and points out that weather and sun_moon accept place names directly, routing the agent away from unnecessary calls. It does not state an explicit when-not condition, keeping it just short of the top mark.

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 readOnly/openWorld/idempotent/non-destructive, so the safety profile is known. The description adds genuinely non-derivable facts: pricing is free, and errors surface as isError with a message that is not charged. It doesn't discuss rate limits or data freshness, so not a 5.

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-loaded with the core capability, then data source, use cases, price, and error behavior in a tight sequence. Every sentence carries distinct information with no repetition.

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 not be explained. The description covers purpose, data source, usage contexts, pricing, and error semantics, leaving nothing an agent needs in order 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?

Schema description coverage is 100%, with both country and year (including the 1975-2075 range) documented in the schema. The description mentions 'any year' and 'regional (state) holidays' but adds no format or syntax 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?

States a specific resource (public holidays) with clear scope: 100+ countries, any year, today's status, and upcoming ones, plus regional/state coverage. An agent can immediately tell this apart from siblings like country_info or sun_moon 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?

Gives explicit use cases ('scheduling, market-closure awareness or delivery estimates'), which helps route the agent toward the right context. It does not name alternatives or state when not to use it, keeping it below a 5.

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 readOnly, openWorld, idempotent, and non-destructive, so the bar is lower. The description adds genuinely useful context beyond them: the calculation engine (SunCalc), the free/not-charged-on-error pricing model, and explicit error behavior (returns isError for invalid input or upstream failure). It does not describe pagination or output shape, but the output schema covers that.

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-loaded with the core deliverable, followed by engine, timezone note, pricing, and error semantics. Dense and mostly waste-free, though the pricing/error tail is slightly list-like; every clause still carries information.

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 an output schema present, return values need not be explained, and the description covers engine, timezone handling, and failure semantics. Minor gaps around the required 'place' format are handled by the schema, so an agent has what it needs to call 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?

Schema description coverage is 100%, so both tz and date are already documented ('IANA zone for local times', date pattern with default). The description's 'Pass tz for local times' restates the schema rather than adding new meaning, so the baseline 3 is correct.

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 computational resource (sunrise/sunset/golden hour/twilight/day length/solar noon plus moon phase, illumination, moonrise/moonset) for any place and date. This is clearly distinguishable from siblings like weather, time_convert, or geocode, and no schema needs to be opened to know what it returns.

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 data the tool produces ('for any place and date') and the tz hint, but there is no explicit when-to-use guidance and no named alternative (e.g., weather for conditions vs this for astronomical times). Adequate but leaves routing to 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?

Beyond the readOnly/idempotent annotations, it discloses that computation happens locally against the IANA database, that there are no rate limits, that results are exact, that the tool is free, and that failures surface as isError with a message and no charge. That is genuinely useful operational context; only the mild tension between 'computed locally' and openWorldHint=true keeps it from a 5.

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 paragraph, front-loaded with the three capability groups before operational details. Price and error notes are compact, though the trailing cost/failure sentence is slightly less essential than the leading capability enumeration.

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 not be described, and the description covers the multi-mode nature, zone format, and error behavior for a 5-param, zero-required tool. The one residual gap is what a bare call with no arguments returns, which is only loosely implied by 'Current time in any time zones'.

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 every parameter including defaults, maxItems, and the 'naive times are read in from_tz' rule. The description adds the IANA zone-name convention and examples, but no deeper interaction semantics (e.g., how add combines with until). Baseline 3 applies when the schema does the heavy lifting.

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 specific verbs and resources across all modes: current time in zones, zone-to-zone conversion (DST-correct), and date arithmetic (add/subtract durations, days between, weekday, ISO week, Unix time). It is clearly distinguishable from the similarly-named sibling unit_convert because it is scoped to time zones and calendar math.

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 enumerates the capabilities, which implies when the tool is applicable, but never states when NOT to use it or names an alternative (e.g., unit_convert for non-time unit conversion, sun_moon for celestial events). Usage is inferable rather than prescribed, which fits a 3.

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, but the description goes well beyond them: it discloses the upstream source (MET Norway/yr.no), the geocoder (OSM), the pricing model ($0.001/call, 10 free/day), the payment-required result with x402 options, and the error contract (isError on invalid input or upstream failure, not charged). This is exactly the kind of behavioral context annotations cannot carry.

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, followed by data fields, source, time handling, price, and errors — every sentence carries distinct information. It is one dense block rather than grouped sections, but there is little waste.

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 annotations covering the safety profile and an output schema covering return shape, the description fills the remaining gaps an agent needs: input formats, source model, time semantics, billing, and failure behavior. Nothing material is missing for correct invocation.

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 value beyond the schema: it clarifies that place names are geocoded with OpenStreetMap, that lat,lon is accepted, gives an IANA example (Australia/Sydney), and reiterates the 9-day cap. The detail is mostly reinforcing rather than net-new, keeping it at 4.

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 ('Current weather and hourly/daily forecast') with scope ('for any place name or lat,lon'), the exact data fields returned, and the horizon ('up to 9 days'). An agent can immediately tell this apart from adjacent siblings like sun_moon or time_convert.

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 clear context: worldwide coverage, place-name geocoding, lat/lon input, and tz handling for local times. However, it never states when NOT to use it or names an alternative sibling (e.g. geocode for pure geocoding), so it stops short of explicit routing guidance.

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