IP Geolocation MCP Server

Summarize IPs

ipinfo_summarize_ips

Read-onlyIdempotent

Aggregate IP addresses into grouped counts and percentages for log analysis, showing breakdowns by country, continent, ASN, or privacy status.

Instructions

Aggregate one or more IP lookups into counts and percentages.

Uses the same validation, deduplication, cache, and upstream batch lookup path as ipinfo_lookup_ips, but returns fixed-size summary buckets instead of per-IP records. This is the preferred tool for large log-analysis tasks such as "where did visitors come from?" when the caller does not need the underlying records. Percentages are based on mapped_ip_count; filtered and failed IPs are counted separately. Errors raise ToolError with a JSON-encoded envelope.

Input Schema

TableJSON Schema

Name	Required	Description
`ips`	Yes	IPv4/IPv6 addresses to aggregate. Invalid or special-use IPs are filtered.
`group_by`	No	Summary dimensions to include. Empty returns only mapped, skipped, and failed counts.
`top_n`	No	Maximum buckets to return per requested group. truncated_groups reports the true distinct count when capped.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`mapped_ip_count`	Yes
`skipped_count`	Yes
`failed_count`	Yes
`by_country`	No
`by_continent`	No
`by_asn`	No
`by_privacy`	No
`truncated_groups`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.7.0Jun 9, 2026

addedOutput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / properties / by_asn / anyOf

Previous value: -[
-  {
-    "items": {
-      "description": "A counted summary bucket for a group in ``SummaryResult``.",
-      "properties": {
-        "count": {
-          "type": "integer"
-        },
-        "key": {
-          "type": "string"
-        },
-        "percent": {
-          "type": "number"
-        }
-      },
-      "required": [
-        "key",
-        "count",
-        "percent"
-      ],
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "additionalProperties": false,
+      "description": "A counted summary bucket for a group in ``SummaryResult``.",
+      "properties": {
+        "count": {
+          "type": "integer"
+        },
+        "key": {
+          "type": "string"
+        },
+        "percent": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "key",
+        "count",
+        "percent"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / by_continent / anyOf

Previous value: -[
-  {
-    "items": {
-      "description": "A counted summary bucket for a group in ``SummaryResult``.",
-      "properties": {
-        "count": {
-          "type": "integer"
-        },
-        "key": {
-          "type": "string"
-        },
-        "percent": {
-          "type": "number"
-        }
-      },
-      "required": [
-        "key",
-        "count",
-        "percent"
-      ],
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "additionalProperties": false,
+      "description": "A counted summary bucket for a group in ``SummaryResult``.",
+      "properties": {
+        "count": {
+          "type": "integer"
+        },
+        "key": {
+          "type": "string"
+        },
+        "percent": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "key",
+        "count",
+        "percent"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / by_country / anyOf

Previous value: -[
-  {
-    "items": {
-      "description": "A counted summary bucket for a group in ``SummaryResult``.",
-      "properties": {
-        "count": {
-          "type": "integer"
-        },
-        "key": {
-          "type": "string"
-        },
-        "percent": {
-          "type": "number"
-        }
-      },
-      "required": [
-        "key",
-        "count",
-        "percent"
-      ],
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "additionalProperties": false,
+      "description": "A counted summary bucket for a group in ``SummaryResult``.",
+      "properties": {
+        "count": {
+          "type": "integer"
+        },
+        "key": {
+          "type": "string"
+        },
+        "percent": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "key",
+        "count",
+        "percent"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / by_privacy / anyOf

Previous value: -[
-  {
-    "items": {
-      "description": "A counted summary bucket for a group in ``SummaryResult``.",
-      "properties": {
-        "count": {
-          "type": "integer"
-        },
-        "key": {
-          "type": "string"
-        },
-        "percent": {
-          "type": "number"
-        }
-      },
-      "required": [
-        "key",
-        "count",
-        "percent"
-      ],
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "additionalProperties": false,
+      "description": "A counted summary bucket for a group in ``SummaryResult``.",
+      "properties": {
+        "count": {
+          "type": "integer"
+        },
+        "key": {
+          "type": "string"
+        },
+        "percent": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "key",
+        "count",
+        "percent"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

Addedv0.6.0Jun 3, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Beyond readOnly/ idempotent annotations, it details shared processing path with sibling, filtering/failed IP handling, and error format. Beneficial context that annotations alone don't provide.

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 concise paragraphs with front-loaded purpose. Every sentence adds value—no waste.

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?

Given 3 params and an output schema, description covers purpose, behavior, error handling, and relationships thoroughly. No gaps.

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 coverage is 100% with good descriptions and examples. Description adds no extra per-param details, so baseline 3 is appropriate.

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?

Clearly states it aggregates IP lookups into counts and percentages. Distinguishes from sibling ipinfo_lookup_ips by emphasizing summary output and large log-analysis use case.

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?

Explicitly says this is preferred for large log-analysis when underlying records are not needed, and clarifies percentage basis. Could be improved by stating when not to use it, but 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