Skip to main content
Glama
temporal-mcp-server

temporal-mcp-server

time_between

Calculate the exact elapsed time between two ISO-8601 timestamps, broken into days, hours, minutes, and seconds with a human-readable summary and past/future direction.

Instructions

Exact elapsed time between two ISO-8601 timestamps, broken into days/hours/minutes/seconds plus a human-readable summary. All components share one sign, so they sum correctly; direction is 'past', 'future', or 'same'.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "from": "<from>",
      "to": "<to>"
    },
    "name": "time_between"
  }
}

Input Schema

NameRequiredDescriptionDefault
toYesEnd of the interval, as an ISO-8601 timestamp.
fromYesStart of the interval, as an ISO-8601 timestamp.
timezoneNoIANA timezone used to interpret timestamps that carry no 'Z' or offset. Defaults to UTC.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.3.0
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • removedInput schema / additionalProperties
      Removed value: -false
  2. Changed1 schema field changedv0.2.2
    • addedInput schema / properties / timezone
      Added value: +{
      +  "description": "IANA timezone used to interpret timestamps that carry no 'Z' or offset. Defaults to UTC.",
      +  "type": "string"
      +}
  3. First observedv0.1.0

TDQS

A3.8/5.0
Behavior4/5

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

With no annotations, the description carries the full behavioral burden and does meaningful work: it discloses the return decomposition (days/hours/minutes/seconds plus a human-readable summary), the sign-consistency guarantee so components sum correctly, and the three possible `direction` values. It does not cover behavior for malformed timestamps, mixed offsets, or reversed ranges beyond the direction field.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: the operation and its return shape come first, followed by the non-obvious sign/direction guarantee. Every clause adds information an agent could not get from the schema, and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must describe return values and it does so concretely (component breakdown, summary string, direction enum). For a three-parameter calculation tool this is sufficient to call correctly, though edge-case behavior (invalid timestamps, DST/timezone ambiguity when offsets are absent) is left out.

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

Parameters3/5

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

Schema description coverage is 100%, so `from`, `to`, and `timezone` are already documented with types and defaults, and the description adds no per-parameter semantics beyond confirming ISO-8601 input. The mention of sign and `direction` clarifies output semantics rather than input meaning, so it lands at the baseline for a fully documented schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific operation and resource: 'Exact elapsed time between two ISO-8601 timestamps,' which an agent can immediately distinguish from add_duration or convert_timezone by intent. It stops short of explicitly naming a sibling or stating the boundary condition (e.g., 'use add_duration to shift a timestamp'), so it is clear but not fully differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: the phrasing 'elapsed time between two timestamps' tells an agent when the tool applies, but there is no explicit when-to-use/when-not and no named alternative among the siblings. The agent must infer that add_duration is for offsetting a single timestamp rather than measuring a gap.

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