thirdtrail

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

Annotations already declare read-only, idempotent, non-destructive, and non-open-world. The description adds value beyond them: the clear-sky modeling assumption, the ceiling interpretation, and the auth prerequisite ('Requires an API key on a paid Solar plan'). It does not describe output shape or rate limits, keeping it out of 5 territory.

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?

Three tight sentences: quantity/unit first, then purpose and caveat, then parameter behavior and auth. No filler, well 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?

For a single-metric read tool with no output schema, the description conveys the unit, per-day granularity, range semantics, assumptions, and auth requirement. Return-format detail is absent but the metric's shape is adequately implied.

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 baseline is 3, but the description adds default behavior the schema does not state: passing from/to together for a range, or neither for today. That is real semantic gain beyond the individual 'Requires to'/'Requires from' notes.

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 quantity with its unit ('Clear-sky Daily Light Integral in mol/m²/day') and scope ('for each day in a range'), which is distinctive against siblings like get_solar_position or get_prayer_times. It does not explicitly name a sibling, but the resource itself is unique enough that confusion is unlikely.

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 intent ('plan crop growth or supplemental greenhouse lighting') and an important interpretation caveat (cloudless skies, treat as the ceiling). It omits any when-not or explicit alternative tool, but the context is unambiguous for its niche.

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 non-annotation context: elevation correction of the computed times, the paid-plan auth requirement, and which parameters drive which outputs. It doesn't describe return format, but that is a minor omission.

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 returned values, then usage routing, then defaults and prerequisites. Every sentence carries distinct 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?

For a 7-parameter read-only computation with no output schema, the description covers what is produced, how to choose it over siblings, defaults, the required school parameter, and the auth requirement. Nothing an agent needs to invoke 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 100%, so the baseline is 3, but the description adds relational meaning the schema doesn't: school sets the fajr and isha rules, asr_method selects the shadow rule with shafi as default, and date defaults to today. This is more than restating the field list.

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 the exact resource (Fajr, sunrise, dhuhr, asr, maghrib, isha) and the scope (one date at a location, elevation-corrected). It explicitly contrasts itself with the sibling get_sun_moon_times, so an agent can route correctly 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?

States when to use it ('Islamic prayer schedules') and names the alternative for the non-Islamic case (get_sun_moon_times). It also surfaces prerequisites and defaults: school is required, asr_method defaults to shafi, date defaults to today, and an API key on a paid plan is needed.

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, and closed-world behavior. The description adds the return shape, default values, and an important access constraint: an API key on a paid Solar plan is required.

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 compact and front-loaded: output shape first, then use cases, alternative tool, defaults, and access requirement. Every sentence earns its place.

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?

Despite no output schema, the description summarizes the return value as a list of timestamped azimuth/altitude positions. Combined with full parameter schema coverage and annotations covering safety, 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?

Schema description coverage is 100%, so the schema already explains each parameter including bounds, defaults, and elevation rationale. The description reinforces date and interval defaults but adds no parameter syntax or constraints 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 output: the sun's azimuth and altitude through one UTC day, sampled at an interval, as timestamped positions. It also distinguishes the tool from get_solar_position by contrasting daily path versus single instant.

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 explicit use cases (shading studies, PV siting, panel-angle planning) and directly routes single-instant queries to get_solar_position. The defaults for date and interval further clarify expected usage.

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 non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: an API key on a paid Solar plan is required, and results are NREL SPA-equivalent on JPL DE421 with Bird clear-sky irradiance — provenance that affects trust in the numbers.

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 payload and the sibling routing, then defaults and provenance. Every clause carries information, though the run-on sentence packing the include/plan condition with the output list costs some readability.

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 enumerates the returned fields and their units, states the default for timestamp, and discloses the plan/auth prerequisite. An agent has everything needed to call it correctly and 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 coverage is 100%, so all six parameters including timestamp's 'defaults to now' and elevation's guidance are already documented. The description adds only the conditional gate that irradiance appears 'when include asks for it and the plan covers it', which is marginal beyond the enum in 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 verb+resource ('the sun's position at one instant') and enumerates the exact quantities returned (azimuth, altitude, zenith, declination, hour angle, equation of time, GHI/DNI/DHI). It further distinguishes itself from get_solar_path and get_sun_moon_times by scope, so an agent can route without opening a 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?

Explicit when-to-use ('where the sun is at a given moment') plus named alternatives for adjacent needs: get_solar_path for a full day's track and get_sun_moon_times for rise/set. Nothing is left 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, non-destructive, closed-world. The description adds behavior beyond them: it requires an API key and a paid Ephemerides plan, and discloses the default window (today, 7 days, or the plan's lower ceiling). It does not cover rate limits or output format, so it stops short of 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?

The returned quantities are front-loaded in the first sentence, followed immediately by usage routing, an actionability hint about elevation, and defaults. Every clause carries information an agent needs to call the tool correctly; there is no padding.

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 does so exhaustively (all solar/lunar event types, one entry per day). Auth prerequisites and default time window are also stated, so an agent has everything needed 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. The description still adds meaning: it quantifies the days default ('7 days or the plan's limit if lower'), which the schema only leaves as 'plan-dependent', and it re-emphasizes that supplying elevation shifts sunrise/sunset at altitude.

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 verb+resource (sun and moon rise/set times for a location) and enumerates the exact quantities returned: sunrise, sunset, solar noon, the three twilights, golden and blue hour, moonrise/set and phase, one entry per day. It explicitly distinguishes itself from siblings by noting get_solar_position is for the sun's angle at a moment and get_tide_window for tides.

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 when-to-use condition ('any question about when the sun or moon rises, sets or gets dark') and names two alternatives with the exact conditions that select them (sun's angle at a moment -> get_solar_position; tides alongside the sun -> get_tide_window). Explicit exclusions plus routing leave nothing 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 cover the read-only/idempotent safety profile, and the description still adds critical context beyond them: heights are relative to MEAN SEA LEVEL not chart datum, an explicit 'never use for navigation' warning, an auth requirement (API key on a paid Tides plan), and default date-range behavior. This is rich behavioral disclosure.

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 purpose and return shape, then usage routing, then the datum caveat and auth/default facts. Dense but every sentence carries distinct, non-redundant information; 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?

No output schema exists, and the description compensates by describing the returned event list and height units. Combined with full schema coverage and annotations, an agent has everything needed to call and interpret the 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 the schema documents each parameter, but the description adds default values not in the schema (from today, 2 days or the plan's limit) for start_date/days. It does not add format or syntax detail for tz/lat/lon, so it is a modest improvement over the baseline 3.

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 (returns high/low water times and heights), names the data source (FES2022), and specifies the return shape (events with type, time, height_m). It explicitly differentiates from the two nearest siblings, get_tide_heights and get_tide_window.

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 an explicit when-to-use ("when high or low tide is") plus named alternatives with the condition that selects each: get_tide_heights for a continuous curve, get_tide_window for tides with sun/moon context. Nothing is left 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/non-destructive, so the safety profile is covered. The description adds meaningfully beyond that: the datum caveat ('metres relative to mean sea level, not chart datum'), the three default behaviors, the plan-dependent step floor (no finer than 10m), and the auth/plan requirement.

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?

Three sentences, each doing distinct work: shape, usage/alternative, constraints. Front-loaded with what is returned, with no filler or restated field names.

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 still characterizes the return as time/height pairs. Combined with 100% schema coverage and disclosed auth/plan and datum constraints, an agent has everything needed 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 coverage is 100%, so the baseline is 3, but the description supplies default values the schema omits for start_date, days, and step ('from today, 2 days, and the finest step the plan allows, but no finer than 10m'). It does not add units or format detail for tz/lat/lon beyond the schema, so it is not a full 5.

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 with the exact return shape ('a list of time and height_m pairs'), and explicitly contrasts itself with the sibling get_tide_extremes. An agent can distinguish it from get_tide_window and get_tide_extremes without opening any 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 concrete use cases ('plot a tide curve or read the height at a particular time') and an explicit routing rule: 'for just the highs and lows use get_tide_extremes'. It also names the access prerequisite (API key on a paid Tides plan), which is a selection constraint in practice.

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?

Goes well beyond the annotations (readOnly/idempotent) by disclosing an auth prerequisite (API key on a paid Tides plan), the default window behavior, the plan-dependent cap on days, and a subtle behavioral trait — elevation shifts sun/moon times by roughly three minutes but never tide heights.

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 what the call returns, then usage, then the elevation nuance, defaults, and key requirement — each sentence carries distinct information. Dense but no filler; slightly long for the payload.

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 enumerates the returned per-day data, and it covers defaults, plan limits, and auth. Nothing an agent needs to invoke 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 already 100%, so baseline is 3, but the description adds real meaning: it quantifies elevation's effect (~3 min) and clarifies that tide heights are observer-independent, which disambiguates the parameter's scope. It does not add syntax beyond the schema for tz/days/start_date.

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: per-day high/low waters plus sunrise, sunset, golden/blue hour, twilight and moon phase. It explicitly distinguishes itself from the sibling tools get_tide_extremes and get_sun_moon_times, 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?

Names the two alternatives it replaces (get_tide_extremes, get_sun_moon_times) and the reason to prefer it (single call). It also gives conditional guidance on when to pass elevation ('when you know it') and when to omit it.

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