Cron Translator

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

The description discloses important behavioral traits beyond the readOnlyHint annotation: it is rule-based rather than a language model, it deliberately refuses out-of-grammar phrases because wrong schedules are dangerous, and it warns about leftover words that may indicate misreading. It also enumerates the returned fields, including warnings and next run times.

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 yet information-dense. The first sentence states the core purpose, and the following sentences each add necessary operational detail: when to use it, how refusal behaves, how to recover, and what the response contains. 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?

Even without an output schema, the description fully prepares an agent to call the tool: input format, timezone semantics, failure behavior, retry guidance, and a complete list of returned fields. It also warns about the subtle risk of unparsed words, which is exactly the kind of context an agent needs.

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 input schema already covers both parameters well with examples, so the baseline is 3. The description adds extra value by explaining why timezone matters — cron expressions carry no timezone, so it decides when the schedule actually fires — and by framing phrase as the English schedule to be interpreted.

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: converting an English schedule description into a standard five-field cron expression, then explaining and validating it. This clearly distinguishes build_cron from siblings like explain_cron and next_cron_runs, which handle different directions of cron-related work.

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 explicitly states when to use the tool: 'Use this when a user describes a schedule in words and needs the expression.' It also gives recovery guidance for rejected phrases. However, it does not explicitly name the sibling alternatives or state when not to use them, so exclusions are 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 only mark it as read-only, so the description carries the behavioral burden and handles it well. It discloses non-obvious cron pitfalls the tool checks for, such as OR semantics between day-of-month and day-of-week, skipped dates, and daylight-saving effects, and it details what the response contains.

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 front-loaded with the core purpose, followed by usage guidance, behavioral caveats, and return details. Each sentence adds value and no content is redundant with the schema; it is appropriately detailed for a tool with no output schema.

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 is complete for the tool's complexity: it explains what the tool does, when to use it, which hidden cron rules it checks, and exactly what the response includes. With no output schema, this level of return-value detail is necessary and well supplied.

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%, with each parameter already documented with types, defaults, ranges, examples, and special cases. The description adds general context about normalization and return values but does not meaningfully extend the parameter semantics beyond what the schema already provides.

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 the verb and resource: it translates a cron expression into English, lists upcoming run times, and reports gotchas. It does not explicitly differentiate itself from sibling tools like next_cron_runs, though the broader 'read, verified, or explained' framing helps distinguish intent.

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 an explicit when-to-use directive: 'Use this whenever a cron expression needs to be read, verified, or explained' and even recommends it over direct reasoning. It does not name alternatives or spell out when a sibling would be more appropriate, but the 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?

Beyond the readOnlyHint annotation, the description discloses the exact return shape (UTC ISO 8601 instant plus local wall-clock rendering), confirms timezone semantics, and states that Quartz-only syntax is refused rather than guessed. This gives the agent useful behavioral expectations without relying solely on annotations.

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 efficiently organized: a one-line summary, a usage rationale, a caution against manual computation, and then the return format and constraint. Every sentence adds necessary information, and the key purpose is 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?

With no output schema, the description adequately explains the return format. It covers the timezone behavior, unsupported syntax handling, and usage motivation, while the input schema handles parameter details. Nothing essential for correct invocation seems 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?

The input schema already provides 100% parameter coverage, so the baseline is satisfied. The description adds extra meaning by clarifying the expression behavior — specifically that unsupported Quartz syntax (L, W, #, ?) is rejected — and by reinforcing that the timezone determines when the schedule fires.

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: 'List the next run times for a cron expression in a specific timezone.' This clearly distinguishes the tool from its siblings build_cron and explain_cron, which presumably create or explain schedules rather than compute upcoming runs.

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 explicitly states when to use this tool: when the only question is 'when does this next fire', with concrete examples like checking deadlines or showing schedules. It also warns against manual date computation. It does not name sibling tools or give explicit when-not-to-use conditions, but the context is clear enough.

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