Meridian

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

Annotations already establish read-only, idempotent, non-destructive, but the description adds real behavioral substance: tz-database backing, DST edge cases at the spring-forward/fall-back boundaries, and an explicit warning on non-existent or ambiguous times. It also discloses the exact return shape including the optional 'warning' field, which no annotation or output schema covers here.

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 a 'Use when' clause, and every sentence carries information, including the return-shape contract. The single dense paragraph makes the return-structure sentence slow to parse, which is the one structural cost.

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 compensates by enumerating the response object's fields, including the conditional 'warning' and 'day_note'. For a four-parameter, read-only conversion tool this leaves nothing an agent needs unknown before calling.

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% and the schema already lists most accepted time formats, so the description's value is partly repetition. It does add genuine meaning: the 'no Z' constraint on ISO input and the clarification that the date default is 'today in the source zone' rather than UTC today.

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 ('convert a specific wall-clock time from one place to others') with an explicit scope qualifier ('for any date'). The contrast with meridian_now and meridian_meeting_slots is implicit but unmistakable, since this is the only tool framed around converting an arbitrary given wall-clock time.

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 leading 'Use when you need to convert a specific wall-clock time' gives clear triggering context, and 'for any date' rules out a now-only read. It never names an alternative or an exclusion, so an agent must infer when meridian_zone_info or meridian_meeting_slots would be the better pick.

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 the description adds substantial context beyond them: the 15-minute scan granularity, the ranking heuristic (maximize people in working hours, avoid night), DST-correct offsets per date, the return shape (up to 5 slots with local start and end per person), and the explicit no-feasible-time message. This is exactly the behavioral disclosure an agent needs.

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?

Four tight sentences, front-loaded with the usage trigger, then mechanics, then return behavior, then defaults. No sentence is redundant and no padding or hedging appears.

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 6-parameter read-only tool with no output schema, the description covers input defaults, ranking logic, return payload, and the empty-result case. Nothing an agent needs in order to call it correctly or interpret results 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 schema already documents every parameter and its default. The description restates the defaults (9–17 working hours, 60 minutes, date today in the first place) and the count of returned slots, but adds little meaning beyond what the schema fields already state, 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 verb and resource ('scheduling a call across several places') and immediately conveys the function as cross-time-zone slot finding, which is distinct from the sibling conversion tools (meridian_convert_time, meridian_now, meridian_zone_info). 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?

Opens with an explicit when-to-use trigger ('Use when you need to schedule a call across several places'), giving clear invocation context. It does not name alternatives or exclusion conditions (e.g., use meridian_convert_time when you only need a point-in-time conversion), so it stops short of 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 only declare it read-only and non-destructive; the description adds that the result is live data and enumerates the returned fields (offset, abbreviation, DST status). It does not say how unknown or ambiguous place strings are handled, which is the main behavioral risk for a lookup 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?

Three short sentences, front-loaded with the trigger and ending with the argument formats. The final sentence partly restates the schema's examples, which is the only redundancy, and nothing is bloated.

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?

One required parameter, no output schema — and the description compensates by naming the return fields explicitly. Combined with the never-guess warning, an agent has everything needed to call this correctly without additional context.

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 a format the schema does not mention — "UTC+5:30" fixed-offset strings — alongside cities, IANA zones and abbreviations. That extra accepted-input form has real selection value for an agent picking the right argument syntax.

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?

"Returns the real current time, date, UTC offset, abbreviation and daylight saving status for each place" states a specific resource (current time/date per place) and the exact output. The word "now" plus the multi-place framing clearly separates it from siblings like meridian_convert_time and meridian_zone_info.

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?

"Use when you need to know what time or date it is right now somewhere" plus "You have no clock of your own, so never guess" gives a clear trigger and a warning against the main failure mode. It does not explicitly name convert_time or zone_info as the alternatives when the question is not about the present moment, so routing guidance is implied rather than stated.

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 read-only, idempotent, non-destructive and closed-world behavior, so the description's job is to add return-shape context. It does that well: current offset, abbreviation, DST observance, all clock changes in the year with local before/after times, and the next change. The ambiguity note about IST/CST and disclosure of which zone was resolved is genuinely useful behavioral detail.

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 use case, then the return contents, then the ambiguity caveat — a logical order with no filler. The middle sentence is long but each clause maps to a distinct returned field.

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 explaining returns and does so field by field, and annotations cover the safety profile. It stops short of describing error behavior for unresolvable places or out-of-range years, which is the only meaningful gap for a two-parameter lookup 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 in the schema, and the description adds only a little: it implies `place` tolerates abbreviations and that `year` scopes the clock-change listing. It adds no format or edge-case detail (e.g. what happens with an ambiguous abbreviation or a year with no DST) 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 (zone offset/abbreviation/DST/clock changes) and enumerates exactly what is returned, including the next change. It is clear enough to separate from generic time tools, though it never names the sibling tools (meridian_now, meridian_convert_time) it should be distinguished from.

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 triggering questions ("what is the UTC offset of X", "does X observe daylight saving", "when do the clocks change"), which is strong when-to-use guidance. It lacks any when-not-to-use or named alternative, so an agent must infer the boundary against meridian_convert_time and meridian_now.

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