IPGeolocation MCP Server

Timezone Conversion

convert_timezone

Read-only

Read-only time conversion via GET /v3/timezone/convert. Works on free and paid plans. Cost: 1 credit. The conversion requires one source selector and one destination selector; get_timezone provides a single place's current time and…

Instructions

Source/destination selectors are tz_from/tz_to, location_from/location_to, iata_from/iata_to, icao_from/icao_to, locode_from/locode_to, or lat_from+long_from and lat_to+long_to. time is optional and must be yyyy-MM-dd HH:mm or yyyy-MM-dd HH:mm:ss. Returns original time, converted time, diff_hour, and diff_min.

Input Schema

Name	Required	Description
`time`	No	Time to convert in yyyy-MM-dd HH:mm or yyyy-MM-dd HH:mm:ss format. Defaults to current time.
`tz_to`	No	Destination IANA timezone name (e.g. Asia/Tokyo).
`lat_to`	No	Destination latitude. Use with long_to.
`iata_to`	No	Destination 3-letter IATA airport code.
`icao_to`	No	Destination 4-letter ICAO airport code.
`long_to`	No	Destination longitude. Use with lat_to.
`tz_from`	No	Source IANA timezone name (e.g. America/New_York).
`lat_from`	No	Source latitude. Use with long_from.
`iata_from`	No	Source 3-letter IATA airport code.
`icao_from`	No	Source 4-letter ICAO airport code.
`locode_to`	No	Destination 5-character UN/LOCODE.
`long_from`	No	Source longitude. Use with lat_from.
`location_to`	No	Destination city or address string.
`locode_from`	No	Source 5-character UN/LOCODE.
`location_from`	No	Source city or address string.

Output Schema

Name	Required	Description
`data`	No	Present on success: API result after field selection, redaction, and transport limits.
`page`	No
`error`	No	Present on failure, with isError: true.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv2.0.3Oct 28, 2026

removedOutput schema / properties / data / additionalProperties / anyOf

Removed value: -[
-  {
-    "type": "null"
-  },
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "number"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "array"
-  },
-  {
-    "type": "object"
-  }
-]

addedOutput schema / properties / data / additionalProperties / type

Added value: +[
+  "null",
+  "boolean",
+  "number",
+  "string",
+  "array",
+  "object"
+]

Addedv2.0.1Oct 13, 2026
Removedv2.0.0Jul 25, 2026
First observedv1.0.10Mar 16, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations only declare readOnlyHint and openWorldHint; the description adds plan availability (free and paid), a concrete billing cost of 1 credit, the selector-pairing constraint, the accepted time formats and default, and the returned fields. That is substantive context an agent cannot get from the annotations.

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

Conciseness4/5

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

Front-loaded with endpoint, cost, and the core selector rule — the right ordering. Slightly padded by enumerating every selector name, which the schema already lists, but each sentence still carries operational information.

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

Completeness5/5

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

For a 15-parameter, zero-required tool this is complete: the pairing rule resolves the apparent ambiguity of all-optional params, cost/plan are disclosed, and an output schema exists so return values need no further explanation.

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

Parameters5/5

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

Schema coverage is 100%, but the schema is a flat bag of 15 all-optional properties with no oneOf or required constraint. The description supplies the missing semantics: which parameters form interchangeable selector families (tz_*, location_*, iata_*, icao_*, locode_*, lat+long) and that exactly one from each side must be chosen. This is meaning beyond the schema, not repetition.

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

Purpose5/5

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

The opening states a specific verb (convert), resource (time/timezone), and the underlying endpoint GET /v3/timezone/convert, so it is immediately distinguishable from get_timezone, which is explicitly named as the single-place alternative.

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

Usage Guidelines4/5

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

It sets a hard structural rule for use: one source selector plus one destination selector are required. It also names get_timezone as the sibling for a single location's current time. It stops short of full when-not-to-use guidance (e.g. when to prefer a coordinate lookup over a city name), but the routing context is clear.

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

Deploy Server