Moltline TimeOps

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description's real contribution is the error contract (never raises a protocol error, returns {"error": ...} with a fix hint) and retry safety, which annotations cannot express. The restatement of "read-only and idempotent" is redundant with annotations and doesn't add value, keeping it out of the top band.

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 purpose and the two usage modes, then return shapes, then exclusions, then errors – a sensible ordering. It is somewhat longer than needed, and the "FREE." fragment and redundant re-statement of idempotency are 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?

Output schema exists, but the description still sketches both return shapes and fully specifies the error response behavior for a stateless calculator, which is everything an agent needs to call it and recover from bad input. No meaningful gap remains.

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 a 3 is the baseline, but the description adds genuine meaning by explaining the mode switch between add_days and end_date and supplying a concrete worked input/output pair. It stops short of discussing negative add_days or the holidays array in prose, which the schema already handles.

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 ("business-day math that skips weekends and your holiday list") and immediately enumerates its two modes, add vs. count. It also explicitly separates itself from the sibling deadline_planner, 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?

Gives an explicit when-to-use ("when the span must exclude weekends and named holidays") and two explicit when-not cases: plain calendar-day subtraction and backward scheduling from a deadline, the latter naming the alternative sibling deadline_planner. 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?

Beyond the annotations (which already cover readOnly/idempotent/destructive), it discloses two things the structured fields cannot: that the tool is gated behind a premium license, and that it never raises a protocol error but returns an {"error": ...} object. It also frames retry safety as actionable advice after correcting input, which is more than restating idempotentHint.

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 scoping sentence and exclusions are front-loaded, followed by the example and then the error contract. The sample output's "verdict": "..." is slightly vague, but no sentence is wasted and each block serves a distinct purpose.

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?

It goes past requirements by sketching the return shape (schedule, latest_safe_start, slack_business_days_from_today, verdict) even though an output schema exists, and it covers the error path. A minor gap: it does not explain what happens when more than 30 tasks are supplied, which the schema mentions but the description never confirms.

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 worked input example {"due_date": "2026-06-01", "tasks": [{"name": "Draft", "days": 3}]} concretely demonstrates the nested task shape and date format. It goes somewhat beyond the schema but does not explain buffer_days or holidays interaction with the computation.

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 - planning a task schedule backward from a hard deadline in business days - and contrasts it against the sibling tools business_days and sla_due by name. An agent can distinguish it from every sibling 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 positive condition ('Use when the end date is fixed and steps must be placed backward from it') plus two explicit exclusions routing to business_days and sla_due. Nothing about tool selection 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/destructive=false, and the description adds real behavioral context beyond them: it never raises protocol errors, returns a structured {"error": ...} with remediation, and is safe to retry after correction. It also discloses the no-shared-window verdict shape.

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?

Purpose is front-loaded and each sentence carries information (input example, return shape, exclusion, error contract). Slightly dense with multiple JSON snippets, but 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?

An output schema exists, yet the description still gives enough of the return shapes and the error contract that an agent can interpret results and recover from bad input. Nothing needed to invoke or handle 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 baseline is 3, and the description goes further with a concrete example ({"offsets_utc": [-8, 1, 5.5]}) that demonstrates one offset per participant and fractional offsets. Defaults for work_start/work_end are left to the schema, so it doesn't fully exhaust parameter guidance.

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 first sentence names a specific verb and resource ('find the shared meeting window') and scopes it ('across time zones inside working hours'). It is explicitly distinguishable from siblings like recurrence_expand and single-time conversion.

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 when to use ('people in different zones need one shared slot') and when not ('not for converting a single known time... not for expanding a recurring series (recurrence_expand)'), naming the alternative sibling directly.

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 restating those adds little; however the description contributes a genuinely new behavior contract, namely that malformed input never raises a protocol error but returns an {"error": ...} payload, which is not visible in the annotations or schema. The concrete error example makes recovery behavior predictable.

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 purpose, then mode selection, then a compact example, then routing and error contract — every block is useful. Minor waste from the 'FREE' tag and from restating read-only/idempotent already covered by annotations.

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 4-parameter, output-schema-backed tool this covers all an agent needs: when to use it, which mutually exclusive mode to pick, a concrete example of the call and result, sibling exclusions, and error/retry behavior. Nothing material 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% and already documents every_days vs weekly_on exclusivity and the count clamp, so the schema carries the baseline; the description adds a worked input/output example showing how start_date, every_days and count combine, which clarifies semantics beyond the field descriptions.

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 ('Expand a recurrence rule into a concrete list of ISO dates') and explicitly names what it is not for, distinguishing it from business_days and meeting_overlap. An agent can route to 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?

Gives both positive conditions ('use when a recurrence rule has to become concrete dates') and explicit exclusions with the correct alternatives named ('not for counting working days in a span (business_days)', 'not for finding a slot across zones (meeting_overlap)').

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=true, idempotentHint=true, and destructiveHint=false, but the description adds meaningful context beyond them: premium licensing, example return shapes, and detailed error behavior, including that malformed input returns an error object rather than raising a protocol error.

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 computation, followed by a compact example, usage guidance, exclusions, and error behavior. Every section is useful and there is 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?

Given the output schema, full parameter schema coverage, and annotations, the description provides everything needed: purpose, usage boundaries, example input/output, and error semantics. An agent can invoke and retry the tool correctly from this definition.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all six parameters thoroughly. The description adds value with a concrete example showing opened_at, sla_hours, and business_hours_only in context, plus the resulting mode output, though it does not need to compensate for schema gaps.

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 uses a specific verb and resource: it computes when a ticket's SLA falls due, including wall-clock versus business-hours modes. It also explicitly differentiates from deadline_planner, so an agent can distinguish it from siblings without inspecting 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?

It states exactly when to use the tool: when a response or resolution clock has started and one due moment is needed. It also states when not to use it, naming deadline_planner for multi-step project schedules.

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