Refine Glama tool descriptions

src/tools/abuse.ts

@@ -21,7 +21,7 @@ export function registerAbuseTools(server: McpServer) {
 
 Returns { ip, abuse } with route, country, name, organization, kind, address, emails, and phone_numbers for reporting abuse.
 
-fields/excludes use comma-separated abuse.* paths such as abuse.emails; ip is always returned. force_refresh bypasses cache and makes a fresh upstream request only when the user asks. Call once per IP target and post-process locally.`,
+fields/excludes use comma-separated abuse.* paths such as abuse.emails; ip is always returned. force_refresh bypasses cache only when the user asks. Call once per IP target and post-process locally.`,
       inputSchema: {
         ip: z
           .string()

src/tools/asn.ts

@@ -94,7 +94,7 @@ export function registerAsnTools(server: McpServer) {
       },
       description: `Read-only ASN enrichment via GET /v3/asn. Paid only. Cost: 1 credit. Query by asn or ip; asn takes priority over ip. Use for ASN relationships, route prefixes, allocation details, or WHOIS; use lookup_ip for basic ASN with geolocation.
 
-Returns { asn } with core fields plus optional peers, downstreams, upstreams, routes, and whois_response. include accepts peers, downstreams, upstreams, routes, and whois_response. fields/excludes can use full paths such as asn.upstreams.as_number or root-relative paths such as upstreams.as_number. force_refresh bypasses cache and makes a fresh upstream request only when the user asks.`,
+Returns { asn } core fields plus included peers, downstreams, upstreams, routes, or whois_response. include accepts those five values. fields/excludes accept full asn.* paths or root-relative paths such as upstreams.as_number. force_refresh bypasses cache only when the user asks.`,
       inputSchema: {
         asn: z
           .string()

src/tools/astronomy.ts

@@ -47,11 +47,11 @@ export function registerAstronomyTools(server: McpServer) {
       annotations: {
         readOnlyHint: true,
       },
-      description: `Read-only single-date astronomy lookup via GET /v3/astronomy. Works on free and paid plans. Cost: 1 credit. Use for one date and real-time sun/moon position; use get_astronomy_time_series for daily sunrise, moon, and twilight data across a date range.
+      description: `Read-only single-date astronomy lookup via GET /v3/astronomy. Works on free and paid plans. Cost: 1 credit. Use for one date or real-time sun/moon position; use get_astronomy_time_series for daily sunrise, moon, and twilight data across a date range.
 
-Returns { location, astronomy } plus ip for IP/caller lookups. astronomy includes date/current_time, sunrise/sunset, moonrise/moonset, morning/evening twilight blocks, day_length, sun and moon status, altitude, azimuth, distance, moon_phase, moon_illumination_percentage, and moon_angle.
+Returns { location, astronomy } plus ip for IP/caller lookups. astronomy includes date/current_time, sunrise/sunset, moonrise/moonset, twilight blocks, day_length, sun/moon position, distance, status, moon_phase, moon_illumination_percentage, and moon_angle.
 
-Select by lat/long, location, IP, or caller IP when no selector is provided. lat and long must be provided together; date must be YYYY-MM-DD; elevation must be 0-10000 meters. time_zone changes timestamp formatting to include full dates. lang only changes location fields; non-English lang is paid-only and returns 401 on free plans.`,
+Selector priority is lat/long, location, ip, then caller IP when no selector is provided. lat and long must be provided together; date must be YYYY-MM-DD; elevation must be 0-10000 meters. time_zone changes timestamp formatting to include full dates. lang only changes location fields; non-English lang is paid-only and returns 401 on free plans.`,
       inputSchema: {
         lat: z
           .string()
@@ -147,9 +147,9 @@ Select by lat/long, location, IP, or caller IP when no selector is provided. lat
       annotations: {
         readOnlyHint: true,
       },
-      description: `Read-only daily astronomy series via GET /v3/astronomy/timeSeries. Works on free and paid plans. Cost: 1 credit per request. Use for date ranges up to 90 days; use get_astronomy for one date or real-time sun/moon altitude and azimuth.
+      description: `Read-only daily astronomy series via GET /v3/astronomy/timeSeries. Works on free and paid plans. Cost: 1 credit per request. Use for date ranges up to 90 days; use get_astronomy for one date or real-time sun/moon position.
 
-Returns { location, astronomy: [...] } with one daily item per date containing sunrise/sunset, moonrise/moonset, twilight blocks, day_length, sun/moon status, and moon_phase. Select by lat/long, location, IP, or caller IP when no selector is provided.
+Returns { location, astronomy: [...] } with one daily item per date containing sunrise/sunset, moonrise/moonset, twilight blocks, day_length, sun/moon status, and moon_phase. Selector priority is lat/long, location, ip, then caller IP when no selector is provided.
 
 dateStart and dateEnd are required YYYY-MM-DD values with a maximum 90-day span. lat and long must be provided together; elevation must be 0-10000 meters. time_zone changes timestamp formatting to include full dates. lang only changes location fields; non-English lang is paid-only and returns 401 on free plans. force_refresh bypasses cache and makes a fresh upstream request only when the user asks.`,
       inputSchema: {

src/tools/geolocation.ts

@@ -216,7 +216,7 @@ export function registerGeolocationTools(server: McpServer) {
       },
       description: `Read-only unified IP lookup via GET /v3/ipgeo. Base lookup costs 1 credit; include=security adds 2 credits and include=abuse adds 1 credit. Use this first when one IP or domain needs multiple data domains: location, company/ASN, network, timezone, currency, security, abuse, user_agent, hostname, geo_accuracy, or dma_code.
 
-Returns root IP/domain data plus location, country_metadata, currency, asn, network, company, and time_zone objects. Paid include modules add security, abuse, user_agent, hostname, dma_code, or geo_accuracy. Free plans support core location, country_metadata, currency, time_zone, basic ASN, fields, and excludes; paid plans add domain lookup, company, network, extended ASN, non-English lang, and include modules.
+Returns root IP/domain data plus selected objects such as location, country_metadata, currency, asn, network, company, time_zone, security, abuse, user_agent, hostname, geo_accuracy, or dma_code. Free plans support core location, country_metadata, currency, time_zone, basic ASN, fields, and excludes; paid plans add domain lookup, company, network, extended ASN, non-English lang, and include modules.
 
 ip omitted means caller IP. fields/excludes use comma-separated dot paths; ip is always returned, unknown excludes do not error, and include wins over fields/excludes. This server auto-adds include modules referenced by fields. Use lookup_asn only for peers, upstreams, downstreams, routes, or WHOIS; use check_security or get_abuse_contact only for security-only or abuse-only requests.`,
       inputSchema: {
@@ -305,9 +305,9 @@ ip omitted means caller IP. fields/excludes use comma-separated dot paths; ip is
       annotations: {
         readOnlyHint: true,
       },
-      description: `Read-only bulk IP lookup via POST /v3/ipgeo-bulk. Paid only. Base geolocation costs 1 credit per valid IP, with security adding 2 and abuse adding 1 per valid IP. This MCP server accepts up to ${MAX_BULK_ITEMS.toLocaleString()} IPs per request.
+      description: `Read-only bulk IP lookup via POST /v3/ipgeo-bulk. Paid only. Base geolocation costs 1 credit per valid IP; security adds 2 and abuse adds 1 per valid IP. This MCP server accepts up to ${MAX_BULK_ITEMS.toLocaleString()} IPs per request.
 
-Use it when multiple IPs or domains need location data or mixed IP domains. Private, bogon, and malformed IPs are not billed by the upstream API. fields, excludes, lang, and include behave like lookup_ip for each item; this server also infers include modules from fields. For security-only batches, use bulk_security_check.`,
+Use when multiple IPs or domains need location data or mixed IP domains. Private, bogon, and malformed IPs are not billed. fields, excludes, lang, and include behave like lookup_ip for each item; this server also infers include modules from fields. For security-only batches, use bulk_security_check.`,
       inputSchema: {
         ips: z
           .array(z.string())
@@ -392,7 +392,7 @@ Use it when multiple IPs or domains need location data or mixed IP domains. Priv
         readOnlyHint: true,
       },
       description:
-        "Return the public IP address of the machine running this MCP server via GET /v3/getip. No input parameters, API key, account, or credits are required. Returns a plain IP address string, not geolocation data. Use this only when the user asks for the server or caller public IP; use lookup_ip for location, ASN, timezone, currency, security, or abuse data.",
+        "Return the public IP address of the machine running this MCP server via GET /v3/getip. Takes no input parameters and requires no API key, account, or credits. Returns a plain IP address string, not geolocation data. Use this only when the user asks for the server or caller public IP; use lookup_ip for location, ASN, timezone, currency, security, or abuse data.",
       inputSchema: {},
     },
     async () => {
@@ -416,7 +416,7 @@ Use it when multiple IPs or domains need location data or mixed IP domains. Priv
       },
       description: `Read-only ownership lookup via GET /v3/ipgeo. Paid only. Cost: 1 credit. Use only for company/ASN ownership; use lookup_ip once if the same IP request also needs location, security, abuse, network, timezone, or currency.
 
-Returns { company, asn }: company name/type/domain plus ASN as_number, organization, country, type, domain, date_allocated, and rir when available. ip omitted means caller IP. force_refresh bypasses cache and makes a fresh upstream request only when the user asks. Call once per IP target and post-process locally.`,
+Returns { company, asn }: company name/type/domain plus ASN allocation fields when available. ip omitted means caller IP. force_refresh bypasses cache only when the user asks. Call once per IP target and post-process locally.`,
       inputSchema: {
         ip: z
           .string()
@@ -463,7 +463,7 @@ Returns { company, asn }: company name/type/domain plus ASN as_number, organizat
       },
       description: `Read-only currency and country metadata lookup via GET /v3/ipgeo. Works on free and paid plans. Cost: 1 credit per successful lookup.
 
-Returns { currency, country_metadata }: currency code/name/symbol plus country calling_code, tld, and languages. ip selects the IP used to derive country and currency; omit it for caller IP. force_refresh bypasses cache and makes a fresh upstream request only when the user asks.
+Returns { currency, country_metadata }: currency code/name/symbol plus country calling_code, tld, and languages. ip selects the IP used to derive country and currency; omit it for caller IP. force_refresh bypasses cache only when the user asks.
 
 Use this tool for currency-only or country-metadata-only requests. If the request needs more IP data, prefer one lookup_ip call with targeted fields/excludes.`,
       inputSchema: {

src/tools/security.ts

@@ -50,7 +50,7 @@ export function registerSecurityTools(server: McpServer) {
 
 Returns { ip, security } with threat_score, VPN, proxy, residential proxy, Tor, relay, anonymity, bot, spam, known attacker, and cloud-provider fields; provider names, confidence scores, and last_seen dates appear when available.
 
-fields/excludes use comma-separated security.* dot paths; ip is always returned. force_refresh bypasses cache and makes a fresh upstream request only when the user asks. Call once per IP target and post-process locally.`,
+fields/excludes use comma-separated security.* dot paths; ip is always returned. force_refresh bypasses cache only when the user asks. Call once per IP target and post-process locally.`,
       inputSchema: {
         ip: z
           .string()
@@ -118,9 +118,9 @@ fields/excludes use comma-separated security.* dot paths; ip is always returned.
       annotations: {
         readOnlyHint: true,
       },
-      description: `Read-only bulk security lookup via POST /v3/security-bulk. Paid only. Cost: 2 credits per valid IP. This MCP server accepts up to ${MAX_BULK_ITEMS.toLocaleString()} IPs; private, bogon, and malformed IPs are not billed by the upstream API.
+      description: `Read-only bulk security lookup via POST /v3/security-bulk. Paid only. Cost: 2 credits per valid IP. This MCP server accepts up to ${MAX_BULK_ITEMS.toLocaleString()} IPs; private, bogon, and malformed IPs are not billed.
 
-Use only for security-only batches; use bulk_lookup_ip with include=security when each IP also needs geolocation or other IP domains. Returns one { ip, security } result per valid IP with the same security fields as check_security. fields/excludes use security.* dot paths per item. force_refresh bypasses cache and makes a fresh upstream request only when the user asks.`,
+Use for security-only batches; use bulk_lookup_ip with include=security when each IP also needs geolocation or other IP domains. Returns one { ip, security } result per valid IP. fields/excludes use security.* dot paths per item. force_refresh bypasses cache only when the user asks.`,
       inputSchema: {
         ips: z
           .array(z.string())

src/tools/timezone.ts

@@ -17,9 +17,9 @@ export function registerTimezoneTools(server: McpServer) {
       annotations: {
         readOnlyHint: true,
       },
-      description: `Read-only timezone lookup via GET /v3/timezone. Works on free and paid plans. Cost: 1 credit. Use when the user asks for one place, IP, airport, UN/LOCODE, or IANA timezone's current local time or timezone metadata; use convert_timezone for source-to-destination conversion.
+      description: `Read-only timezone lookup via GET /v3/timezone. Works on free and paid plans. Cost: 1 credit. Use when the user asks for one place, IP, airport, UN/LOCODE, or IANA timezone current local time or metadata; use convert_timezone for source-to-destination conversion.
 
-Returns { time_zone } plus location, airport, city, or ip context depending on selector. time_zone includes name, offset, offset_with_dst, current_time, current_time_unix, date/time variants, time_24, time_12, timezone abbreviations, is_dst, dst_savings, dst_exists, and dst_start/dst_end when available.
+Returns { time_zone } plus selector context such as location, airport, city, or ip. time_zone includes the zone name, current time, UTC offsets, date/time variants, abbreviations, and DST status/transition fields when available.
 
 Selector priority is tz, lat/long, location, ip, iata_code, icao_code, then lo_code. lat and long must be provided together. lang only changes location fields; non-English lang is paid-only and returns 401 on free plans.`,
       inputSchema: {

src/tools/useragent.ts

@@ -24,12 +24,13 @@ export function registerUserAgentTools(server: McpServer) {
       annotations: {
         readOnlyHint: true,
       },
-      description: `Read-only custom user-agent parsing via POST /v3/user-agent. Paid only for POST payload parsing. Cost: 1 credit per successful string. This tool parses only the explicit uaString value; it cannot read caller headers or transport metadata.
+      description: `Read-only custom user-agent parsing via POST /v3/user-agent. Paid only for POST payload parsing. Cost: 1 credit per successful string. Parses only the explicit uaString value; it cannot read caller headers or transport metadata.
 
-Returns { user_agent_string, name, version, version_major, device, engine, operating_system }; device.type and operating_system.type can include Desktop, Mobile, Robot, Hacker, Anonymized, or Unknown. uaString must be the exact non-empty user-agent string to parse. force_refresh bypasses cache and makes a fresh upstream request only when the user asks. Use bulk_parse_user_agent for multiple strings.`,
+Returns { user_agent_string, name, type, version, version_major, device, engine, operating_system }. Type fields can identify desktop/mobile clients, robots, malformed or scripted strings, anonymized strings, or unknown values. uaString must be the exact non-empty user-agent string; empty/null strings return upstream 400. force_refresh bypasses cache only when the user asks. Use bulk_parse_user_agent for multiple strings.`,
       inputSchema: {
         uaString: z
           .string()
+          .min(1)
           .describe(
             "The user-agent string to parse (e.g. Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36)."
           ),
@@ -73,10 +74,10 @@ Returns { user_agent_string, name, version, version_major, device, engine, opera
       },
       description: `Read-only bulk user-agent parsing via POST /v3/user-agent-bulk. Paid only. Cost: 1 credit per successful string. This MCP server accepts up to ${MAX_BULK_ITEMS.toLocaleString()} explicit user-agent strings.
 
-Returns one parsed object per string with user_agent_string, name, version, version_major, device, engine, and operating_system fields. uaStrings must be a non-empty array of exact user-agent strings; use parse_user_agent for one string. force_refresh bypasses cache and makes a fresh upstream request only when the user asks.`,
+Returns one parsed object per string with user_agent_string, name, type, version, version_major, device, engine, and operating_system. uaStrings must be a non-empty array of exact user-agent strings; empty/null strings return upstream 400. Use parse_user_agent for one string. force_refresh bypasses cache only when the user asks.`,
       inputSchema: {
         uaStrings: z
-          .array(z.string())
+          .array(z.string().min(1))
           .min(1)
           .max(MAX_BULK_ITEMS)
           .describe(