slonce.info.pl

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered and the description correctly does not contradict it. The description adds only a summary of the payload shape, which is already captured by the existing output schema, and says nothing about timezone handling, historical accuracy, or edge-year behavior.

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 front-loaded sentence with no filler, and the default behavior is placed early. The phrasing 'the dates, which way and at what time' is slightly informal but still parses cleanly as a list of outputs.

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 safety and an output schema covering return values, the description only needs to establish purpose and scope, which it does well. The only residual gap is the unmentioned lang parameter, though the schema documents it adequately.

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%: lang is fully documented in the schema while year carries only min/max bounds. The description compensates partially by explaining that year defaults to the current year, but it never mentions the lang parameter or its pl default, leaving that entirely to 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 (clock changes) with a defined geographic scope (Poland) and enumerates exactly what is returned: dates, direction of change, time, and the next change from today. None of the sibling tools (sun_times, solstice, moon_phases, find_city) overlap with this domain, so an agent can route unambiguously.

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 parenthetical 'this year by default' tells the agent the default behavior when no year is supplied, which is useful invocation guidance. However, there is no explicit when-not guidance and no mention of any alternative tool, so usage is only implied.

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 genuinely useful behavior beyond that: prefix (not substring) matching, diacritic-insensitive matching, and the size and composition of the underlying dataset, plus which fields come back.

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?

It is a single compact sentence with no filler, but it is a verbless noun phrase with a nested parenthetical and a colon-list, so the reader must parse twice to extract the core action. A leading verb would have made it front-loaded.

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, and the description still characterizes the result scope and matching semantics. For a three-parameter read-only lookup, nothing an agent needs in order to call it 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 67%, and the undocumented parameter is the required one, `query`; the description compensates by explaining that it is a name prefix and that Polish and English spellings with or without diacritics are accepted. `lang` and `limit` are already documented in the schema, so nothing further is needed there.

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 identifies a specific resource and matching rule: places whose name starts with the given text, drawn from a bounded set of 258 Polish/foreign places, returning coordinates, time zone and page. That is far more specific than the title 'Find a place'. It lacks an explicit leading verb and never names a sibling, but the siblings are all astronomy/clock tools, so confusion is implausible.

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 about what happens with no match, and no mention that the query must be at least 2 characters. The only usage-adjacent hint is that names may be typed with or without Polish diacritics, which is about matching rather than about choosing this tool.

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 description's job is to add scope constraints — and it does, with the two-year maximum and the 60-day default window, neither of which appears in the annotations. It still omits error behavior on out-of-range input, which 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?

A single dense sentence front-loads the returned events, then attaches range and time-zone defaults as parentheticals. Every clause carries information, though the nested parentheses slightly hurt scanability.

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 shape needs no explanation, and all four parameters are documented at 100% coverage. What remains thin is failure behavior and whether lang affects returned event labels rather than just the time format.

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 earns a 4 by restating defaults in task terms (today + 60 days, Polish time) and by adding the two-year cap, a constraint that exists nowhere in the schema. Language selection and IANA time zone syntax are left entirely to 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?

The description names a specific resource (new moons, first/last quarters, full moons) with precision ('to the minute') and range semantics, so an agent knows exactly what is returned. It does not explicitly contrast itself with the sibling moon_times, but the event-list framing is distinctive enough to infer the difference.

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 defaults: from today for 60 days if dates are omitted, and a hard ceiling of two years. There is no explicit statement of when to prefer this over moon_times or sun_calendar, and no guidance on what happens if the range limit is exceeded.

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 the tool as read-only, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds useful scope details such as defaulting to today and including next new/full moon data, but it does not disclose any further behavioral traits like timezone handling or resolution behavior.

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 description is a single, front-loaded sentence that immediately names moonrise and moonset before listing additional outputs. It is efficient and contains no filler, though the list of outputs makes it slightly dense.

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?

The tool has a rich input schema, full parameter descriptions, an output schema, and clear annotations, so the description need not explain return formats or safety behavior. It is complete enough for an agent to understand the tool's scope, though it could mention how location inputs are selected (city vs. lat/lon/tz) if that were not already 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 every parameter, including city, lat/lon, tz, date, and lang. The description only restates the date default implicitly via 'today by default' and adds no new syntax or constraint details 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?

The description states a specific resource and scope: moonrise/moonset at a place on a day, plus phase and related lunar events. It is clear what the tool returns, but it does not explicitly distinguish itself from the sibling moon_phases tool, which likely overlaps on phase data.

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 description: use it for moonrise/moonset and lunar phase information for a place and day, with today as the default. There is no explicit when-to-use guidance, no mention of alternatives like moon_phases, and no exclusion conditions.

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 a read-only, idempotent, non-destructive, closed-world lookup, so the safety profile is covered. Beyond that, the description adds meaningful defaults: the current year when none is given and Polish time as the baseline zone, plus the fact that extra outputs only appear when a place is provided. It stops short of noting precedence when both city and lat/lon are supplied.

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, front-loaded with the primary output (the solstices) and then the conditional extension. There is no filler, and the semicolon cleanly separates the default case from the place-specific case.

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?

The output schema covers return values and the annotations cover the safety profile, so the description only needs to handle defaults and routing. It handles the year and time-zone defaults but leaves open how city interacts with lat/lon/tz and never states why this tool should be chosen over sun_calendar, which is the main remaining gap for a six-parameter optional-input 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 description coverage is 83%, above the high-coverage threshold, so the schema already explains tz, lat, lon, city, lang and year. The description reinforces the year default and the 'place' grouping of the location parameters but adds no format or precedence detail beyond that, making the baseline 3 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 resource and result: December and June solstices to the minute, plus shortest/longest day, earliest sunset and latest sunrise when a place is supplied. It is clear what the tool computes, but it never distinguishes itself from the similarly named siblings sun_calendar and sun_times, so an agent must infer the boundary.

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 only implied through the conditional phrase 'with a place, also its shortest and longest day', which tells the agent that omitting place data yields the plain solstice answer. There is no explicit when-to-use/when-not-to-use guidance and no sibling tool is named as an alternative, so the agent has to construct the routing rule itself.

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 carries little weight here. The description adds real context about output content — the day-to-day change in day length and a link that opens the same calendar on one printable A4 page — but says nothing about defaults, missing-place behavior, or error conditions.

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 that puts the core resource and scope first. The trailing 'with the change of the day length from day to day' clause is slightly clunky and the print-link aside is tacked on, but no sentence is wasted.

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, and parameters are fully covered by the schema. The main remaining gap is routing relative to the six sibling tools, especially sun_times and find_city, which the description never mentions.

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 all six parameters (including the pl/en enum and the YYYY-MM month format) are already documented in the schema. The description only adds the vague phrase 'at a place' and contributes no additional meaning about how tz/lat/lon/city interact or which combinations are valid.

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 concrete resource and scope: sunrise, sunset and day length for every day of a month at a place. This implicitly separates it from the single-day sibling sun_times, but no sibling is named, so the differentiation is inferred rather than stated.

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 phrase 'for every day of a month' implies when this is preferable to a per-day tool, but there is no explicit when-to-use, when-not, or alternative named (e.g. sun_times for a single day, find_city for resolving place names). Usage must be inferred.

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, closed-world, so safety is covered; the description adds genuinely new behavioral context: results are in local clock time to the minute, day-length deltas vs the previous day are included, and three twilight bands plus golden/blue hours are reported. Gaps: no mention of behavior at polar latitudes where sunrise/sunset may not occur.

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-loads the primary outputs and appends secondary ones, with zero filler. Slightly list-heavy, but every clause maps to a real capability the agent would want to know about.

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 needn't be explained, yet the description's enumeration of outputs usefully signals what the tool can be selected for. Combined with 100% schema coverage and clear annotations, the definition is sufficient to call correctly; only polar-edge behavior is unaddressed.

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 parameters are already fully documented and the baseline is 3. The description reinforces the defaults (today, local clock time) but adds no syntax or constraint meaning beyond what the schema and enum already state.

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 resource (sunrise, sunset, solar noon, day length) plus the secondary outputs (twilight phases, golden/blue hours) and the scoping ('at a place on a day, today by default'). An agent immediately knows this is the solar-timing tool, distinct from moon_times or solstice which cover different bodies/events.

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 phrase 'at a place on a day (today by default)', which hints at the common no-args case, but there is no explicit when-to-use vs sun_calendar (a sibling covering many days) or guidance on choosing city vs lat/lon/tz. The agent must infer the alternative selection from the schema.

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