temporal-mcp-server

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

With zero annotations the description carries the full burden and does real work: it discloses that date units are calendar-aware (DST boundary keeps wall-clock time, P1M clamps on Jan 31) while time units are exact elapsed time, and that '-' subtracts. It does not cover error behavior for malformed durations or the return format, which keeps it from a 5.

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 tight sentences, front-loaded with the core action, followed by the two semantic distinctions an agent would otherwise get wrong. Every clause carries information; nothing is padding.

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?

Complete on the dimension that matters most for a 3-param arithmetic tool: how the units interact with timezones. Gaps remain around failure modes (invalid duration strings) and the shape of the returned value, which matters somewhat since there is no output schema.

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 genuine interpretive meaning: the Y/M/D vs H/M/S distinction changes how the duration string is applied, and the '-' prefix note reinforces the subtraction syntax. The timezone explanation largely overlaps with the schema's own text, limiting the upside.

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 ('Add an ISO-8601 duration to a timestamp') plus the scoping dimension ('in a timezone'). This is clearly distinct from siblings like convert_timezone and time_between, which either shift zones or compute differences rather than shifting a timestamp by a duration.

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 functional context that implies when to use it (shifting a timestamp by a duration, with subtraction via a '-' prefix), and the calendar-vs-time semantics help an agent decide whether this is the right tool. It never explicitly names alternatives or exclusion conditions, so it falls 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?

No annotations are provided, so the description carries the full burden, yet it says nothing about DST transitions, ambiguous or nonexistent wall-clock times, whether the operation is pure/side-effect-free, or what errors look like. 'Render as wall-clock time' is the only behavioral signal.

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?

A single well-formed sentence with zero filler and the action front-loaded. It is appropriately sized, though it is arguably too terse given the missing behavioral detail.

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 simple three-parameter pure transformation with a fully documented schema, the core is covered. However, with no output schema, the description never indicates the return shape (presumably a formatted string), leaving a real gap.

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 all three parameters including sourceTimezone and its 'ignored when offset present' rule are already documented. The description restates isoTimestamp and targetTimezone but adds no semantics beyond the schema, making baseline 3 appropriate.

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 ('Render') and resource ('ISO-8601 timestamp') with the transformation target ('wall-clock time in a target timezone'). It is clearly distinguishable from siblings like add_duration and time_between, though it never names 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?

Usage is only implied by the purpose statement — no explicit when-to-use, when-not-to-use, or pointer to alternatives such as get_current_time for the current moment. An agent can infer the case but gets no routing 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 and no output schema, the description carries the burden and does disclose the concrete return shape (epoch, UTC ISO-8601, wall-clock in a timezone). It omits anything about the fallback behavior for an invalid timezone identifier, which is the main remaining behavioral unknown.

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?

A single front-loaded sentence with no filler; every clause (three output formats, timezone scoping) contributes information an agent needs.

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 one-optional-parameter read tool with no annotations, the description plus schema cover what is needed: the operation, the input default, and the return values. Only the invalid-timezone behavior is left unaddressed.

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 documents the IANA identifier and the UTC default. The phrase 'in a given timezone' only echoes that parameter, adding no format or error-handling detail 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?

States a specific verb and resource ('Return the current time') and immediately names the three output representations, which distinguishes it sharply from siblings like convert_timezone, add_duration, and time_between that manipulate rather than read 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?

Usage is strongly implied by the name and the sibling set (use this for 'what time is it now', use convert_timezone to shift an existing timestamp), but the description never explicitly states when to prefer an alternative. For a trivial read tool this is adequate, not exemplary.

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 carries the full behavioral burden. It does disclose the exact contents of the response (name, version, build commit, runtime, capability counts), which effectively serves as the return-value contract in the absence of an output schema, and 'Returns' makes the read-only, side-effect-free nature clear without stating it explicitly.

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?

A single, front-loaded sentence with no filler. Every listed field (version, build commit, runtime, capability counts) earns its place by telling the agent exactly what it will receive.

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 parameters, no annotations, and no output schema, the description needs to define the return surface — and it does so by enumerating the returned fields. Minor gaps remain (no indication of whether build commit may be null in dev builds, or whether output format is text or structured), but the tool is simple enough that this is close to sufficient.

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 tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline for a no-parameter tool applies, and nothing here misleads about inputs.

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 ('Returns') with a well-defined resource ('identity and build information for this server') and enumerates the concrete fields returned (name, version, build commit, runtime, capability counts). The contrast with the time-related siblings is obvious from subject matter, though the description never explicitly distinguishes itself from 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?

There is no statement of when to call this tool or when not to — no mention of diagnostics, version checking, or compatibility verification. An agent can infer it is an informational/diagnostic call from the field list, but that is left entirely implicit.

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 disclosure burden and does so well for the output contract: it explains that components share one sign so they sum correctly and that a `direction` field of 'past'/'future'/'same' is returned. It does not address behavior on invalid or unparsable timestamps, which is the main remaining gap for a pure computation 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?

Two tight sentences, zero filler, with the core operation front-loaded and the output/sign semantics following immediately. Every clause carries information an agent cannot get from the name alone.

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?

There is no output schema, so the description must describe the return value — it does, covering the component breakdown, the human-readable summary, and the direction field. Only edge-case behavior (invalid timestamps, whether the result is absolute or signed per direction) is left unstated.

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 of `from`, `to`, and `timezone` documented in-schema including the default-to-UTC rule. The description adds no parameter-level detail beyond restating that inputs are ISO-8601 timestamps, 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?

The description states a specific verb+resource: computing exact elapsed time between two ISO-8601 timestamps, and it names the output shape (days/hours/minutes/seconds plus a summary). It is clearly distinct from siblings like add_duration and get_current_time, though it never explicitly contrasts itself with 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?

There is no statement of when to use this tool versus add_duration (which also deals with durations) or convert_timezone. Usage is only inferable from the stated purpose; no prerequisites, exclusions, or alternatives are mentioned.

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