Almanack

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

With no annotations, the description carries full responsibility and delivers: fixed application order, exactness of days, policy behaviors for clamp/reject/spill, refusal for intercalary months, tick carrying, step isolation semantics, a 1000-answer cap, and the return shape. It is exceptionally transparent about edge cases.

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 long, but every sentence adds behavioral or policy context. The critical semantics—ordering, policy, steps, batching—are front-loaded, and there is 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?

Given 10 parameters, nested objects, and no output schema, the description is unusually complete: it states batching limits, return shape, ordering semantics, and failure modes. It falls slightly short only because calendar/time/on_error are not fully specified and sibling-tool routing is absent.

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 richly explains years, months, days, ticks, policy, and steps, but it never defines the required 'calendar' parameter, the 'time' parameter, or the 'on_error' parameter and its possible values. These are meaningful gaps for an agent trying to call the tool correctly.

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 opens with a specific verb and resource: 'Move a date by years, months, days and ticks.' It clearly identifies what the tool does and gives enough detail to distinguish it from calendar formatting, parsing, and interval tools in the sibling list.

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 explicit usage guidance: use 'steps' for multiple moves and prefer this over one call per item. It also advises using days instead of months for intercalary dates. It does not explicitly contrast add_to_date with sibling tools, but the within-tool routing and exclusions are strong.

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 full behavioral burden and does so richly: inclusive boundary behavior, the 1000-cap and 'truncated' warning, the requirement that collisions need multiple events, and the leap-day/nonexistent-date rule. These are non-obvious behaviors that an agent needs to know to interpret results correctly.

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 long but densely informative, with no filler. It front-loads the core purpose, then organizes behavior by query, event specification, and edge cases, so 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?

This is a complex 9-parameter tool with no annotations and no output schema, yet the description covers query semantics, boundary conditions, truncation, event formats, and missing-date behavior. It gives an agent enough to invoke the tool correctly and interpret the important parts of 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 0%, so the description must compensate, and it does. It explains the meaning of 'query', 'after', 'start', 'end', 'inclusive', 'limit', 'event', 'events', and the inline event structure, giving concrete shape examples. Only the 'calendar' parameter gets light treatment, but the description still notes that calendar-defined event names are resolved through it.

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 clearly states that the tool computes when recurring events fall and whether they collide, and then enumerates three specific query modes ('next', 'occurrences', 'collisions'). This is specific and immediately distinguishes calendar_events from sibling tools like calendar_periods or render_calendar_page, which serve different calendar-related purposes.

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 explicit guidance on when to use each query and when to pass 'event' vs 'events', including the note that 'collisions' requires multiple events. It also tells users to prefer the tool over reasoning out collision answers in prose. It does not name sibling tools as alternatives, so it stops short of full when-not-to-use guidance.

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 burden, and it discloses many behavioral traits: multi-cycle returns, empty-list semantics, ordering, a batching limit of 1000, and the {count, o, results} response shape. It does not cover error/on_error behavior, but otherwise is unusually transparent.

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 dense and front-loaded, with each sentence contributing either behavioral semantics or a usage tip. A couple of stylistic phrases (''early autumn' becomes a comparison rather than a guess') add color but are not essential.

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?

Because there is no output schema, the description appropriately explains the return shape and item contents. However, the lack of coverage for the required 'calendar' parameter and the error/on_error behavior means the definition is not fully sufficient on its own.

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%, and the description only directly addresses the 'dates' parameter ('Pass 'dates' for more than one') and implicitly mentions the calendar spec. The required 'calendar' parameter and 'on_error' parameter are not sufficiently explained, leaving real gaps for a low-coverage 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 immediately states the operation: identifies which named periods of the year a date falls in — seasons, tides, terms. It also distinguishes itself from likely siblings by emphasizing it returns a list rather than a single value and handles multiple period cycles.

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 clear batching guidance ('Prefer this over one call per item') and points to validate_calendar_spec for gap/overlap analysis. It does not explicitly exclude other sibling tools, but the domain is clear.

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 provided, the description carries the full burden and does so thoroughly. It discloses exactness, the intercalary-day null return and week-resumption behavior, failure when the calendar defines no week, the 1000-item limit, ordering preservation, and the response envelope {count, ok, 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?

Every sentence earns its place: purpose, edge-case behavior, failure mode, batching, limits, ordering, and output shape are all packed in without fluff. The description is front-loaded with the core meaning and only then adds behavioral details.

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 focused weekday-lookup tool with no annotations and no output schema, the description is unusually complete. It covers return value semantics, edge cases, error behavior, batch capacity, ordering, response shape, and a usage preference. No critical gap remains for an agent to invoke the tool 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 0%, so the description must compensate. It adds real meaning for date vs dates and the batch limit, and hints at calendar behavior by describing week definition failure. However, it leaves the calendar parameter's structure and the on_error parameter's semantics unexplained, so compensation is only partial.

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 immediately states what the tool does: determine which weekday a date falls on, returning a 0-based index and name. It adds precise behavioral distinctions such as exactness, intercalary-day null handling, and failure rather than inventing a week, making it clearly distinguishable from sibling date 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?

The description gives explicit batching guidance: pass dates instead of date for multiple items, and prefer a single batched call over one call per item. It does not explicitly name sibling alternatives or exclusion cases, but the intended usage context is clear.

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 must fully disclose behavior, and it does: it states exact arithmetic, refusal of nonexistent dates instead of rounding, the response shape {count, ok, results}, order preservation, and the calendar-spec cost model. This is far beyond minimal and gives the agent a reliable mental model of side effects, limits, and error 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 core purpose is front-loaded and the content is organized into input, batching, response, exactness, and error handling. Some redundancy exists — the calendar-spec cost point is made twice — and the all-caps plural instruction adds emphasis but also length. Overall, it is well-structured for a tool with this complexity.

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 tool with no output schema, no annotations, nested objects, and 9 parameters, the description covers the essentials: accepted input combinations, batching, limits, return envelope, exactness, and failure behavior. The main gaps are the undocumented 'time' and 'on_error' parameters and the lack of a detailed result-schema breakdown, but the description is still strong enough for correct invocation in most cases.

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 explains the singular/plural input constraint, which parameter groups are mutually exclusive, the role of calendar, batching semantics, and general output behavior. However, it does not clarify the 'time' or 'on_error' parameters, which remain underspecified even though they are 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?

The description opens with a specific action, 'Convert between a calendar date, its day number, and its Gregorian date,' clearly identifying both the operation and the resource. It further distinguishes the tool by stating that all three forms are returned together, along with leap-year, year-length, and named-period information. This is enough to separate it from siblings like parse_calendar_date or format_calendar_date.

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 concrete usage guidance: provide exactly one of date, day_number, gregorian, or their plurals, and use plurals when handling multiple dates. It also explains batching preferences and the 1000-item limit. It does not explicitly name sibling tools or state when to prefer an alternative, 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?

With no annotations present, the description carries the full disclosure burden, and it delivers: signed distances, negative counts when end precedes start, the clamp policy, refusal when only one time parameter is supplied, a note that 0 can be passed intentionally, and a guarantee of exact integer arithmetic. Said behavior goes well beyond basic tool documentation and prevents common misinferences.

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 dense but appropriately so, since there is no output schema and no annotations to lean on. It is front-loaded with the core definition and then systematically adds edge cases, return-field semantics, and the exactness guarantee. The middle long sentence bundling 'ticks', 'time', and the pair rule is somewhat harder to parse, so it loses one point for structure.

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 tool with five parameters, zero schema coverage, and no output schema, the description covers the essential operational surface: input semantics, time-pair constraints, output fields, edge-case behavior, and the relationship to add_to_date. Its main remaining weakness is that the concrete structure of the 'calendar', 'start', and 'end' objects is not spelled out, leaving some ambiguity for an agent constructing arguments from scratch.

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 schema provides no textual documentation for the parameters—only empty objects and null defaults—so the description must compensate. It supplies meaning for start and end as dates, explains start_time and end_time semantics including the 'pass 0' rule, and connects the calendar parameter to the breakdown policy and clamp behavior. It does not fully specify the internal shape of the calendar or date objects, which is a gap, but the semantic guidance is strong.

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 opens with a precise definition—the distance between two dates—and then explicitly separates the two meanings: exact signed 'days' versus a 'calendar' breakdown of years, months, and days. This level of specificity, plus naming add_to_date as the inverse operation, makes the tool's role unmistakable among many calendar sibling 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?

The description sets clear context: use this tool when you need the exact distance between two dates, with integer arithmetic and a calendar-aware breakdown. It also gives operational rules such as 'Give both or neither: one alone is refused' and points to add_to_date for the inverse direction. It does not, however, enumerate explicit exclusion scenarios versus each alternative sibling, so it stops short of a perfect routing guide.

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 burden and is highly transparent: it discloses the pattern language, optional zero-pad widths, literal brace escaping, the exact reversibility property, the response contract {count, ok, results}, that results preserve input order, and a maximum call of 1000 items. This is far beyond what the schema or annotations offer.

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 dense yet efficiently organized: purpose first, then token grammar, then batch behavior and recommendation. Every sentence adds necessary information—examples, limits, response shape, and a pairing note—without filler or redundancy.

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 having no output schema and no annotations, the description covers the core behavior, pattern syntax, batching, response shape, and the relationship to parse_calendar_date. Minor gaps remain: the shape of the 'calendar' object and the semantics of 'on_error' are not described, but they are partially inferrable from sibling tools and the parameter defaults.

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 the most complex parameter, pattern, and also explains the date vs dates distinction and the times companion. However, it says nothing about the required 'calendar' parameter or the 'on_error' parameter, which remain undocumented.

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 opens with a specific verb and resource: 'Write a date out to a pattern.' It then details the pattern token grammar (day, month, year, era, intercalary, period, zero-padding), the plural 'dates' form, and the response shape, distinguishing it clearly from parse_calendar_date for the reverse operation. Even without referencing other siblings, the tool's purpose 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?

Explicitly tells the agent to use parse_calendar_date with the same pattern because the output is exactly reversible, and strongly recommends the batch form ('Prefer this over one call per item') with a 1000-item cap. It does not contrast with other siblings like convert_date or add_to_date, but the pairing and batch guidance provide a clear usage context.

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 provided, the description carries the full behavioral burden, and it delivers: it discloses the closed-form computation model, the non-astronomical nature, the start-of-day measurement assumption, and how to adjust the observation point. This is rich, non-obvious behavioral context beyond the bare 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?

The description is dense but every sentence earns its place: it explains the output semantics, the computation model, the timing convention, and the input choice in a compact paragraph. Nothing is filler, and the most important phrase appears first.

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 tool with no output schema, the description does a good job defining returned values, and it covers the tricky day_fraction/time behavior. But it leaves meaningful gaps: the structure and semantics of the required 'calendar' and 'date' nested objects are not explained, and it does not specify what happens if both day_fraction and time are supplied despite 'Give one or the other.'

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 explains day_fraction and time well, including default behavior and mutual exclusivity, and it defines the meaning of the returned fields. However, it gives almost no guidance on the required 'date' and 'calendar' object parameters, which are nested and opaque 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?

The opening line, 'Every moon's phase on a date,' states a specific computation and resource, and the rest of the description defines the output fields (fraction, phase, illumination) in enough detail to distinguish it from the sun/calendar siblings. It is a clear, non-tautological statement of what the tool does.

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 explicit conditional guidance on when to pass 'day_fraction 0.5' versus 'time', and instructs 'Give one or the other.' It also draws a boundary around the model ('not simulated and not astronomical'), which prevents misuse. However, it does not explicitly name sibling tools such as sun_daylight or state when to choose them instead.

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 provided, the description carries the full burden of behavioral disclosure. It explicitly states that n is 1-based or negative, that failure occurs when the month lacks such a day, that the call reports how many such days exist, and that it never returns the nearest match. The 'Exact; never estimates' statement adds further clarity about deterministic 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 appropriately short and front-loads the core concept with examples. Every sentence contributes useful information, though the phrase 'Only days the week counts are considered' is awkward and may confuse rather than clarify the counting rule.

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 pure date calculation, the core algorithm and failure behavior are well covered. However, with no output schema and a nested calendar parameter, the description does not explain the expected return value or how to construct/interpret the calendar object, leaving the tool incompletely specified for an agent.

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 description thoroughly explains the n parameter (1-based from start, negative from end) and gives examples for weekday. However, schema description coverage is 0%, and the calendar, year, month, and weekday encoding are left undefined. The nested calendar object in particular receives no explanation, leaving a significant semantic gap.

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 clearly states that the tool computes the nth occurrence of a given weekday in a month, with concrete examples ('the 3rd Tuesday, the last Friday'). It differentiates itself from sibling calendar tools by specifying exact weekday-ordinal semantics, though it lacks an explicit verb like 'returns' or 'computes'.

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 explains the calculation semantics but provides no guidance on when to use this tool versus alternatives such as calendar_weekday, date_interval, or convert_date. There are no exclusions or contextual conditions, so an agent must infer usage from the tool name.

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 full responsibility for behavioral disclosure. It thoroughly explains strict character-by-character matching, calendar-defined name restrictions, weekday/period consistency checks, error behavior that names what did not fit, and the absence of fuzzy guessing.

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 dense but every sentence earns its place: purpose, strict mode, error behavior, pattern reuse, and time handling are all covered without redundancy. It is front-loaded with the core action and then layers constraints and usage guidance.

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 no-output-schema tool with three parameters and a nested calendar object, the description covers the essential behavior, inputs, and error outcomes well. It leaves some details implicit, such as exact pattern syntax and calendar-object structure, but these appear to be shared context with formatting tools. Overall it is sufficient for selection and mostly sufficient 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 description coverage is 0%, so the description must add meaning beyond the input schema. It does: text is the written date, pattern is the pattern that created the string, and calendar provides the defined names. It does not provide concrete examples of pattern syntax, but it compensates reasonably for the missing schema documentation.

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 and resource: it 'Read[s] a written date back into a date' and clarifies it is the inverse of formatting. The strictness and pattern-reuse language distinguish it from siblings like convert_date and format_calendar_date without needing to open their schemas.

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 clear usage context: use the same pattern that wrote the string, and a time-of-day pattern yields the time back. It does not explicitly spell out when not to use this tool versus alternatives, but the inverse relationship to formatting is strongly 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?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly: SVG output, variable column counts from the calendar's week, intercalary-day strip treatment, dashed strips, moon phase glyphs, event filtering, 500-event and 3-per-day limits, and color assignment before filtering are all detailed. No annotation contradiction exists.

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 dense but mostly earns its length: the core purpose is front-loaded, followed by behavioral constraints and then the whole-year mode. Some repetition exists around the year-sheet option, and the single unbroken block makes it harder to scan, but every major behavioral rule has a 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?

Given the output schema exists, the description does not need to explain return values, and it already covers many edge cases (intercalary days, week lengths, moons, event limits, color stability). The main gap is the undocumented 'theme' parameter and possibly the once unknown fifth parameter, which prevents a 5 for full contextual completeness.

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 adds strong meaning for 'month' (omit to draw year), 'events' (filtering, limits, color behavior), and 'calendar' (week structure, intercalary days, moons). However, 'theme' is never mentioned or tied to the described color behavior, and there is a fifth parameter not covered by any described semantics.

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 opens with a specific verb and resource: 'Draw one month of a calendar as an SVG grid, or a whole year on one sheet, and return the SVG itself.' This clearly distinguishes the tool from siblings like render_timeline and calendar_periods, and the month-or-year modal behavior is unique and explicit.

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 clear usage context: it explains when to choose the whole-year mode ('for seeing at once whether festivals are evenly spread') and contrasts it with 'nine separate month pages do not show.' It also references render_timeline for event shape, though it does not fully spell out when to prefer one sibling over another.

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 provided, the description carries the full burden, and it is exceptionally transparent. It discloses determinism, the 500-event refusal behavior, label overlap/truncation with <title> fallback, era-boundary handling, color validation, and that output is static SVG with no script or style.

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 dense but every sentence adds necessary behavioral or schema-related detail. The purpose is front-loaded, and the extensive constraints are presented in a logical progression from output semantics to event shapes to limits to determinism.

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 description covers return type, determinism, error behavior, label collision handling, theme restrictions, and event modeling. The main gap is that start, end, and calendar remain opaque objects in the schema and are only partially explained via the phrase 'date range' and references to calendar eras; an agent may still need additional context for those values.

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, and it does substantively for events and theme: exact marker/bar shapes, optional lane and color_key, theme presets, required theme object keys, and color syntax. It leaves the exact nested shape of calendar, start, and end date objects somewhat implicit, which prevents a 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?

The description opens with a specific action and deliverable: 'Draw a date range as a horizontal SVG timeline and return the SVG itself.' This clearly distinguishes it from siblings such as scatter_dates or render_calendar_page, even without naming them.

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 purpose statement gives clear context for when to use the tool: anytime an agent needs a horizontal SVG timeline of a date range. It does not explicitly name alternatives or state when not to use it, so it falls just 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?

With no annotations provided, the description carries the full burden and does so well: it discloses determinism across machines, the required seed, repeat/unique behavior, the failure condition when count exceeds available days, and that results are sorted. This is substantial behavioral context beyond the bare 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?

Three sentences deliver the core purpose, determinism guarantee, uniqueness semantics, failure mode, and sort order. Every sentence earns its place, and the most important behavioral constraints are 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?

The tool has six parameters, three nested open objects, no output schema, and no annotations. The description explains determinism, uniqueness, failure, and sorted results, but it omits how 'calendar', 'start', and 'end' should be represented or constructed, and it does not describe the format of the returned dates beyond being sorted.

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 for undocumented parameters. It adds useful meaning for 'seed' (required, deterministic) and 'unique' (default true, no repeats, failure condition), but it does not clarify the structure or semantics of 'calendar', 'start', and 'end', which are open objects with no schema documentation.

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 opens with a specific verb ('scatter'), a clear resource ('a number of dates across a span'), and an intended use ('for generating events'). It is clear about what the tool does, though it does not explicitly name or contrast sibling tools, so it stops short of full sibling differentiation.

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 generating events' provides a clear contextual trigger for when to use this tool. It does not explicitly state when not to use it or point to alternatives, but the intended use case is unambiguous enough for selection among the listed date-related siblings.

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 provided, the description carries the full burden and delivers extensively: curve shapes are 'DECLARED BY THE SPEC, NEVER INFERRED'; rise/set are 'null when a sun is up all day or not at all'; lit is 'the UNION of every sun's span, not the sum'; stretches are 'half-open'; non-year suns get period/epoch/noon_period/cycle semantics; return shape '{count, ok, results}' and failure mode are stated. This is exemplary disclosure for a complex 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?

The core purpose is front-loaded, and every sentence does carry real information, but the body is one unbroken wall of text with ALL-CAPS emphasis and a long rhetorical analogy ('a sinusoid and a straight line honour all three and disagree everywhere else, by nearly a whole bell at the quarter points'). The prose is convoluted in places ('closes at one whole day, not at nought') and would be considerably clearer broken into segmented guidance.

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 tool with zero annotations, zero schema coverage, no output schema, and nested-object parameters, the description covers purpose, return format, error behavior, batching limits, and a large set of edge-case semantics (wraps, always_up/never_up, half-open lit stretches, period/epoch/cycle). Residual gaps: the concrete calendar object structure is only described conceptually, and on_error semantics are not explained. Very complete, with minor omissions an agent would have to infer.

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, and it does for the dominant parameters: it explains what the calendar must declare (shape names, day block, suns), distinguishes date vs dates ('Pass dates for more than one'), and sets the batch ceiling ('Answers up to 1000 in one call, in the order given'). However, the on_error parameter is left entirely unexplained beyond the schema default, and the calendar's exact field names are only alluded to conceptually.

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 opening sentence, 'How long each sun is up on a date, and between which times of day,' states a concrete verb+resource+scope. It further differentiates the tool by declaring 'It is NOT astronomy: no latitude, no axial tilt, no orbit,' and by aligning its promise with sibling 'moon_phases' — so an agent can tell what this tool is and is not.

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 explicit operating conditions: 'Pass dates for more than one,' 'Answers up to 1000 in one call,' 'Prefer this over one call per item,' and failure conditions ('Fails rather than guessing if the calendar declares no suns, or no day block'). It does not, however, name a specific sibling to route to under a specific alternative scenario — the moon_phases reference is an analogy, not a conditional exclusion.

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 provided, the description carries the full behavioral burden and does so thoroughly. It states the tool "never throws and never partially accepts a spec," defines the error/warning distinction, and discloses that missing keys are reported alongside the fields a block does have. This gives the agent a clear mental model of the tool's behavior before calling 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?

Every sentence earns its place: action, result semantics, usage timing, exclusivity, and error-based field discovery are each covered in dense but readable sentences. The core purpose is front-loaded, and the parenthetical examples are concrete without bloating the description.

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 the simple one-parameter schema, no annotations, and no output schema, the description supplies all essential operational detail: what the tool checks, what it returns, how to interpret errors and warnings, when to use it, and how to extract schema knowledge from error messages. The absence of an explicit output schema is mitigated by the promise of "structured errors and warnings" and the field-naming 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?

The schema only defines a single `calendar` object with `additionalProperties: true`, so the description must compensate for the 0% schema coverage. It does this by identifying the input as the spec to validate and explaining how errors reveal the valid fields. It stops short of enumerating the block types or field names, but it explicitly tells the agent the tool itself will provide that information when needed.

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 opens with a specific action and resource: "Check a calendar spec and list everything wrong with it." It clearly separates this tool from the sibling date/calendar operations by noting it is "the only tool that accepts a malformed spec," so an agent can identify its unique role as a validator.

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 a direct rule: "Use this before any other tool when you have written or edited a spec yourself." It also explains that this is the only tool that accepts malformed specs, which tells the agent when no other tool can substitute. The distinction between errors and warnings further clarifies how to interpret results when deciding next steps.

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