crow-central-agency 0.26.7 → 0.26.9

package/README.md

@@ -107,6 +107,9 @@ See `.env.example` for the full list, including:
 - `FEED_TEXT_GENERATION_*` — optional OpenAI-compatible endpoint used by the feed manager to summarize feed items into a consistent length for better agent consumption.
 - `FEED_MAX_SUMMARIZATION_ITEMS` — cap on items summarized per refresh (default: `50`). Items left unsummarized become retry candidates on the next refresh; when the retry backlog exceeds the cap, retries are skipped so a feed isn't permanently blocked by hundreds or thousands of stuck unsummarized items.
 - `AUDIO_GENERATION_*` — optional Gemini TTS configuration that powers the play-message button on the agent console. See [Audio generation](#audio-generation) below.
+- `PLACES_DEFAULT_SOURCE` — default provider for the Places tools when a lookup doesn't request one explicitly: `OSM` (default, no key needed) or `GOOGLE`. `GOOGLE` requires `GOOGLE_PLACES_API_KEY`; without it, lookups fall back to OSM. See [Places](#places) below.
+- `GOOGLE_PLACES_API_KEY` — Google API key that registers the Google Places adapter alongside the default OSM source. See [Places](#places) below.
+- `PHOTON_API_URL` / `OVERPASS_INTERPRETER_URL` — override the geocoding / nearby-search endpoints the OSM places source calls (default to the public Photon and Overpass instances).
 - `GOOGLE_CONNECTOR_CLIENT_ID` / `GOOGLE_CONNECTOR_CLIENT_SECRET` / `CONNECTOR_CALLBACK_URL` — OAuth credentials for the Google connector. Required if you want agents to access Gmail / Calendar / Contacts. See [Connectors](#connectors) below.
 - `OAUTH_PENDING_STATE_TTL_MS` — how long an unfinished OAuth flow stays valid before being swept (default: `600_000`, i.e. 10 minutes).
 - `OTEL_*` — optional OpenTelemetry export.
@@ -139,6 +142,73 @@ The `AUDIO_GENERATION_API_KEY` must be a Google API key with access to the
 You can use the same key as `TEXT_GENERATION_API_KEY` if that is also a
 Gemini-backed configuration, but the two are read independently.
 
+## Places
+
+The **Places** MCP server gives agents location tools — `geocode_place`,
+`search_nearby_places`, and `get_place_details`. It is enabled per-agent from
+the **MCP Servers** section of the agent editor.
+
+Two providers back these tools:
+
+- **OSM** (default) — uses the public OpenStreetMap-based services (Photon for
+  geocoding, Overpass for nearby search). No API key required, so the Places
+  tools work out of the box.
+- **GOOGLE** — uses the Google Places API (New) and Geocoding API for richer
+  results. Opt in by setting `GOOGLE_PLACES_API_KEY`.
+
+`PLACES_DEFAULT_SOURCE` selects which provider serves lookups that don't name a
+source explicitly (`OSM` or `GOOGLE`, defaulting to `OSM`). When
+`GOOGLE_PLACES_API_KEY` is set, the Google adapter is registered alongside OSM;
+if `PLACES_DEFAULT_SOURCE=GOOGLE` is set without a key, lookups fall back to OSM.
+
+### Configuration
+
+```bash
+PLACES_DEFAULT_SOURCE=GOOGLE
+GOOGLE_PLACES_API_KEY=<your Google API key>
+```
+
+### Getting a Google Places API key
+
+The key is a plain Google API key (not an OAuth client — unrelated to the
+Google connector setup below).
+
+**1. Sign in to Google Cloud Console.**
+
+Go to [console.cloud.google.com](https://console.cloud.google.com/) and select
+(or create) a project. Unlike the OAuth connector, the Places and Geocoding
+APIs are **paid** and require a billing account on the project. Google provides
+a recurring monthly free allotment, but you must still enable billing to use
+the key.
+
+**2. Enable the required APIs.**
+
+Open **APIs & Services → Library** and enable both:
+
+- **Places API (New)** — powers `search_nearby_places` and `get_place_details`.
+- **Geocoding API** — powers reverse geocoding for `geocode_place`.
+
+Click each result, then click **Enable**.
+
+**3. Create the API key.**
+
+Open **APIs & Services → Credentials → Create Credentials → API key**. Copy the
+generated key.
+
+> [!NOTE]
+> Restrict the key to just the **Places API (New)** and **Geocoding API** under
+> the key's **API restrictions** so a leaked key can't be used against other
+> Google services.
+
+**4. Add the key to your `.env` and restart Crow.**
+
+```bash
+GOOGLE_PLACES_API_KEY=<paste the API key>
+PLACES_DEFAULT_SOURCE=GOOGLE
+```
+
+Restart the server so it picks up the new env vars.
+
 ## Connectors
 
 Connectors are a framework-level capability - they are not tools agents call

package/dist/_shared/schemas/agent.schema.js

@@ -317,7 +317,8 @@ export const UpdateAgentInputSchema = z.object({
     workspace: z.string().optional(),
     persona: z.string().optional(),
     model: z.string().optional(),
-    effort: ReasoningEffortSchema.optional(),
+    // null explicitly clears the effort (back to provider default); undefined leaves it unchanged.
+    effort: ReasoningEffortSchema.nullish(),
     permissionMode: PermissionModeSchema.optional(),
     settingSources: z.array(SettingSourceSchema).optional(),
     settingSourceConfig: SettingSourceConfigInputSchema.optional(),

package/dist/config/env.js

@@ -2,6 +2,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { expandPath } from "../utils/fs-utils.js";
+import { PLACES_SOURCE } from "../services/places/places-manager.types.js";
 const CONFIG_DIR = path.dirname(fileURLToPath(import.meta.url));
 const DIST_DIR = path.resolve(CONFIG_DIR, "..");
 const DEFAULT_STATIC_DIR = path.join(DIST_DIR, "public");
@@ -15,6 +16,9 @@ function getBoolean(key) {
     const value = process.env[key]?.trim().toLowerCase();
     return value === "true" || value === "1";
 }
+function resolvePlacesSource(key) {
+    return process.env[key]?.trim().toUpperCase() === PLACES_SOURCE.GOOGLE ? PLACES_SOURCE.GOOGLE : PLACES_SOURCE.OSM;
+}
 function readRequired(key) {
     const value = process.env[key]?.trim();
     if (!value) {
@@ -74,6 +78,8 @@ export const env = {
     GMAIL_CHECK_INTERVAL_IN_MINUTES: getOptionalNumber("GMAIL_CHECK_INTERVAL_IN_MINUTES"),
     PHOTON_API_URL: getOptional("PHOTON_API_URL") ?? "https://photon.komoot.io",
     OVERPASS_INTERPRETER_URL: getOptional("OVERPASS_INTERPRETER_URL") ?? "https://overpass-api.de/api/interpreter",
+    PLACES_DEFAULT_SOURCE: resolvePlacesSource("PLACES_DEFAULT_SOURCE"),
+    GOOGLE_PLACES_API_KEY: getOptional("GOOGLE_PLACES_API_KEY"),
 };
 /**
  * Eagerly validate all required environment variables. Call once during boot

package/dist/mcp/agents/search-workspace.js

@@ -21,16 +21,16 @@ export function getSearchWorkspaceToolConfig(agentId, documentSearchService, tas
             .number()
             .optional()
             .describe(`Maximum number of hits to return per page. Default ${DEFAULT_SEARCH_LIMIT}.`),
-        skip: z.number().optional().describe("Number of hits to skip for pagination."),
+        offset: z.number().optional().describe("Number of hits to skip before the page starts (0-based offset)."),
     };
-    const handler = async ({ query, sources, limit, skip }) => {
+    const handler = async ({ query, sources, limit, offset }) => {
         try {
             const filter = buildAccessFilter(agentId, taskManager, circleManager, sources);
             const hits = documentSearchService.search(query, { filter, limit: MAX_SEARCH_LIMIT });
             if (hits.length === 0) {
                 return textToolResult([`No matches found for query "${query}".`]);
             }
-            const pagination = applyPagination(hits, limit || DEFAULT_SEARCH_LIMIT, skip);
+            const pagination = applyPagination(hits, limit || DEFAULT_SEARCH_LIMIT, offset);
             const header = formatPaginationHeader(`Workspace search for query "${query}"`, pagination);
             return textToolResult(header.concat("", renderHits(pagination.items)));
         }

package/dist/mcp/artifacts/list-artifacts.js

@@ -16,9 +16,9 @@ export function getListArtifactsToolConfig(agentId, artifactManager, registry, c
             .optional()
             .describe("Filter by tags. Only artifacts that have every specified tag are returned."),
         limit: z.number().optional().describe("Number of artifacts to return per page."),
-        skip: z.number().optional().describe("Number of artifacts to skip for pagination."),
+        offset: z.number().optional().describe("Number of artifacts to skip before the page starts (0-based offset)."),
     };
-    const handler = async ({ agent_id, type, tags, limit, skip }) => {
+    const handler = async ({ agent_id, type, tags, limit, offset }) => {
         const targetId = agent_id ?? agentId;
         if (agent_id) {
             try {
@@ -47,7 +47,7 @@ export function getListArtifactsToolConfig(agentId, artifactManager, registry, c
                 const suffix = filterParts.length ? ` matching ${filterParts.join(" and ")}` : "";
                 return textToolResult([`No artifacts found for agent ${targetId}${suffix}.`]);
             }
-            const pagination = applyPagination(artifacts, limit || DEFAULT_ARTIFACTS_LIMIT, skip);
+            const pagination = applyPagination(artifacts, limit || DEFAULT_ARTIFACTS_LIMIT, offset);
             const lines = pagination.items.map((artifact) => `- ${artifact.filename} (owner: ${artifact.entityId}, type: ${artifact.type}, modified: ${formatLocalDateTime(new Date(artifact.updatedTimestamp), userTimezone)})`);
             const header = formatPaginationHeader(`Artifacts for agent ${targetId}`, pagination);
             return textToolResult(header.concat("", lines));

package/dist/mcp/artifacts/list-circle-artifacts.js

@@ -16,9 +16,9 @@ export function getListCircleArtifactsToolConfig(agentId, artifactManager, senso
             .optional()
             .describe("Filter by tags. Only artifacts that have every specified tag are returned."),
         limit: z.number().optional().describe("Number of artifacts to return per page."),
-        skip: z.number().optional().describe("Number of artifacts to skip for pagination."),
+        offset: z.number().optional().describe("Number of artifacts to skip before the page starts (0-based offset)."),
     };
-    const handler = async ({ circle_id, type, tags, limit, skip }) => {
+    const handler = async ({ circle_id, type, tags, limit, offset }) => {
         if (!artifactManager.isDirectCircleMember(circle_id, agentId)) {
             return textToolResult(["You are not a direct member of this circle."], true);
         }
@@ -38,7 +38,7 @@ export function getListCircleArtifactsToolConfig(agentId, artifactManager, senso
                 const suffix = filterParts.length ? ` matching ${filterParts.join(" and ")}` : "";
                 return textToolResult([`No artifacts found for circle ${circle_id}${suffix}.`]);
             }
-            const pagination = applyPagination(artifacts, limit || DEFAULT_CIRCLE_ARTIFACTS_LIMIT, skip);
+            const pagination = applyPagination(artifacts, limit || DEFAULT_CIRCLE_ARTIFACTS_LIMIT, offset);
             const lines = pagination.items.map((artifact) => `- ${artifact.filename} (type: ${artifact.type}, modified: ${formatLocalDateTime(new Date(artifact.updatedTimestamp), userTimezone)})`);
             const header = formatPaginationHeader(`Artifacts for circle ${circle_id}`, pagination);
             return textToolResult(header.concat("", lines));

package/dist/mcp/claude-mcp-adapter.js

@@ -1,13 +1,41 @@
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { MCP_CONFIG_TYPE } from "../_shared/index.js";
-/** Wrap a server's registered tools into an in-process Claude SDK MCP server. */
+import { buildStrictToolSchema } from "./tool-utils.js";
+const hasRegisteredTools = (instance) => {
+    if (!("_registeredTools" in instance)) {
+        return false;
+    }
+    const registeredTools = instance._registeredTools;
+    return typeof registeredTools === "object" && registeredTools !== null;
+};
+/**
+ * Swap each registered tool's input schema for a strict variant so unknown parameters are rejected instead of
+ * silently dropped. The raw shape is passed to tool() first so the SDK caches per-field descriptions; the strict
+ * object reuses the same field instances, so those descriptions survive the swap (a strict object passed directly
+ * to tool() would lose them). Guarded so an SDK internals change degrades to the default lenient
+ * behavior rather than throwing.
+ */
+function applyStrictToolSchemas(instance, tools) {
+    if (!hasRegisteredTools(instance)) {
+        return;
+    }
+    for (const registeredTool of tools) {
+        const entry = instance._registeredTools[registeredTool.name];
+        if (entry) {
+            entry.inputSchema = buildStrictToolSchema(registeredTool.inputSchema);
+        }
+    }
+}
+/** Wrap a server's registered tools into an in-process Claude SDK MCP server with strict parameter validation. */
 export function toClaudeServer(name, tools) {
-    return createSdkMcpServer({
+    const server = createSdkMcpServer({
         name,
         tools: tools.map((registeredTool) => tool(registeredTool.name, registeredTool.description, registeredTool.inputSchema, registeredTool.handler, {
             annotations: registeredTool.annotations,
         })),
     });
+    applyStrictToolSchemas(server.instance, tools);
+    return server;
 }
 /** Map a Crow MCP transport to the Claude SDK's stdio/http/sse server config. */
 export function toClaudeTransport(transport) {

package/dist/mcp/copilot-mcp-adapter.js

@@ -1,16 +1,24 @@
 import { convertMcpCallToolResult } from "@github/copilot-sdk";
 import { z } from "zod";
 import { MCP_CONFIG_TYPE } from "../_shared/index.js";
+import { buildStrictToolSchema, getValidationErrorToolResult } from "./tool-utils.js";
 /** Flatten an internal server's tools into Copilot in-process tools, prefixed to keep `mcp__server__tool` names. */
 export function toCopilotTools(server) {
     return server.tools.map((registeredTool) => toCopilotTool(registeredTool, server));
 }
 function toCopilotTool(registeredTool, server) {
+    const inputSchema = buildStrictToolSchema(registeredTool.inputSchema);
     return {
         name: `${server.mcpToolPrefix}${registeredTool.name}`,
         description: registeredTool.description,
-        parameters: z.toJSONSchema(z.object(registeredTool.inputSchema)),
-        handler: async (args, invocation) => toCopilotToolResult(await registeredTool.handler(args, invocation)),
+        parameters: z.toJSONSchema(inputSchema),
+        handler: async (args, invocation) => {
+            const parsed = inputSchema.safeParse(args);
+            if (!parsed.success) {
+                return toCopilotToolResult(getValidationErrorToolResult(registeredTool.name, parsed.error));
+            }
+            return toCopilotToolResult(await registeredTool.handler(parsed.data, invocation));
+        },
         skipPermission: server.isAutoApproved,
     };
 }

package/dist/mcp/feed/get-feed-items.js

@@ -8,9 +8,9 @@ export function getFeedItemsToolConfig(agentId, registry, feedManager, sensorMan
     const inputSchema = {
         feedId: z.string().describe("The news/RSS feed ID from which to get items."),
         limit: z.number().optional().describe(`Number of items to return per page.`),
-        skip: z.number().optional().describe("Number of items to skip for pagination."),
+        offset: z.number().optional().describe("Number of items to skip before the page starts (0-based offset)."),
     };
-    const handler = async ({ feedId, limit, skip }) => {
+    const handler = async ({ feedId, limit, offset }) => {
         try {
             const visibleFeedIds = await resolveVisibleFeedIds(agentId, registry, systemSettingsManager);
             if (!visibleFeedIds.has(feedId)) {
@@ -22,7 +22,7 @@ export function getFeedItemsToolConfig(agentId, registry, feedManager, sensorMan
             }
             const timezone = await sensorManager.getUserTimezone();
             const allItems = await feedManager.getItemsFromFeed(feedId);
-            const pagination = applyPagination(allItems, limit || DEFAULT_FEED_ITEMS_LIMIT, skip);
+            const pagination = applyPagination(allItems, limit || DEFAULT_FEED_ITEMS_LIMIT, offset);
             const formattedItems = pagination.items.map((item) => formatFeedItemSummary(item, feed.title, timezone));
             const header = formatPaginationHeader(`Items from feed [${feed.title}]`, pagination, "Items show summary only — use get_feed_item_content with an item ID for full content");
             return textToolResult(header.concat("", formattedItems.flatMap((item) => [item, "---"])));

package/dist/mcp/feed/get-recent-feed-items.js

@@ -13,9 +13,9 @@ export function getRecentFeedItemsToolConfig(agentId, registry, feedManager, sen
             .optional()
             .describe(`Number of minutes to look back from now for recent items (default: ${DEFAULT_RECENCY_IN_MINUTES}).`),
         limit: z.number().optional().describe(`Number of items to return per page.`),
-        skip: z.number().optional().describe("Number of items to skip for pagination."),
+        offset: z.number().optional().describe("Number of items to skip before the page starts (0-based offset)."),
     };
-    const handler = async ({ recencyInMinutes, limit, skip }) => {
+    const handler = async ({ recencyInMinutes, limit, offset }) => {
         try {
             const timezone = await sensorManager.getUserTimezone();
             const visibleFeedIdSet = await resolveVisibleFeedIds(agentId, registry, systemSettingsManager);
@@ -27,7 +27,7 @@ export function getRecentFeedItemsToolConfig(agentId, registry, feedManager, sen
             if (!allItems.length) {
                 return textToolResult([`No items found in the last ${effectiveRecency} minutes. Try increase the minutes.`]);
             }
-            const pagination = applyPagination(allItems, limit || DEFAULT_FEED_ITEMS_LIMIT, skip);
+            const pagination = applyPagination(allItems, limit || DEFAULT_FEED_ITEMS_LIMIT, offset);
             const formattedItems = pagination.items.map((item) => formatFeedItemSummary(item, feedsMap.get(item.feedId), timezone));
             const header = formatPaginationHeader(`Recent items from all feeds (last ${effectiveRecency} minutes)`, pagination, "Items show summary only — use get_feed_item_content with an item ID for full content");
             return textToolResult(header.concat("", formattedItems.flatMap((item) => [item, "---"])));

package/dist/mcp/feed/list-feeds.js

@@ -7,14 +7,14 @@ export const LIST_FEEDS_TOOL_NAME = "list_feeds";
 export function getListFeedsToolConfig(agentId, registry, feedManager, sensorManager, systemSettingsManager) {
     const inputSchema = {
         limit: z.number().optional().describe(`Number of feeds to return per page.`),
-        skip: z.number().optional().describe("Number of feeds to skip for pagination."),
+        offset: z.number().optional().describe("Number of feeds to skip before the page starts (0-based offset)."),
     };
-    const handler = async ({ limit, skip }) => {
+    const handler = async ({ limit, offset }) => {
         try {
             const timezone = await sensorManager.getUserTimezone();
             const visibleFeedIdSet = await resolveVisibleFeedIds(agentId, registry, systemSettingsManager);
             const feeds = await feedManager.getFeeds(Array.from(visibleFeedIdSet));
-            const pagination = applyPagination(feeds, limit || DEFAULT_FEEDS_LIMIT, skip);
+            const pagination = applyPagination(feeds, limit || DEFAULT_FEEDS_LIMIT, offset);
             const formattedFeeds = pagination.items.map((feed) => formatFeed(feed, timezone));
             const header = formatPaginationHeader("Available feeds", pagination);
             return textToolResult(header.concat("", formattedFeeds));

package/dist/mcp/feed/search-feed-items.js

@@ -9,9 +9,9 @@ export function getSearchFeedItemsToolConfig(agentId, registry, feedManager, sen
         query: z.string().describe("Natural-language phrase or topic to match against feed items."),
         feedId: z.string().optional().describe("Optional feed ID to filter search results to a specific feed."),
         limit: z.number().optional().describe(`Number of items to return per page.`),
-        skip: z.number().optional().describe("Number of items to skip for pagination."),
+        offset: z.number().optional().describe("Number of items to skip before the page starts (0-based offset)."),
     };
-    const handler = async ({ query, feedId, limit, skip }) => {
+    const handler = async ({ query, feedId, limit, offset }) => {
         try {
             const timezone = await sensorManager.getUserTimezone();
             const visibleFeedIdSet = await resolveVisibleFeedIds(agentId, registry, systemSettingsManager);
@@ -25,7 +25,7 @@ export function getSearchFeedItemsToolConfig(agentId, registry, feedManager, sen
             if (!allItems.length) {
                 return textToolResult([`No items found matching "${query}".`]);
             }
-            const pagination = applyPagination(allItems, limit || DEFAULT_FEED_ITEMS_LIMIT, skip);
+            const pagination = applyPagination(allItems, limit || DEFAULT_FEED_ITEMS_LIMIT, offset);
             const formattedItems = pagination.items.map((item) => formatFeedItemSummary(item, feedsMap.get(item.feedId), timezone));
             const header = formatPaginationHeader(`Items matching "${query}"`, pagination, "Items show summary only — use get_feed_item_content with an item ID for full content");
             return textToolResult(header.concat("", formattedItems.flatMap((item) => [item, "---"])));

package/dist/mcp/places/geocode-place.js

@@ -1,20 +1,43 @@
 import { z } from "zod";
+import { PLACES_SOURCE } from "../../services/places/places-manager.types.js";
 import { getErrorToolResult, textToolResult } from "../tool-utils.js";
 import { formatPlaceSummary } from "./places-format-utils.js";
+import { resolveRoutingOrigin, routingDescriptionLine, routingOriginInputSchema } from "./places-routing-input.js";
 const DEFAULT_GEOCODE_LIMIT = 10;
 const MAX_GEOCODE_LIMIT = 25;
 export const GEOCODE_PLACE_TOOL_NAME = "geocode_place";
+const NEUTRAL_DESCRIPTION = "Resolve a free-text query - a place name, full address, or landmark - to matching places. " +
+    "Use get_place_details on a returned id for opening hours, contact info, and other attributes.";
+const NEUTRAL_RESULT_GUIDANCE = "Refine with a more specific name, address, or the city/country disambiguators if needed.";
+const DESCRIPTION_BY_SOURCE = {
+    [PLACES_SOURCE.GOOGLE]: "Resolve a free-text query to matching places. Accepts a place name, a full address, a landmark, or a " +
+        "natural-language / descriptive POI search (e.g. 'rooftop bars in Shibuya'). " +
+        "Use get_place_details on a returned id for opening hours, contact info, and other attributes.",
+    [PLACES_SOURCE.OSM]: "Resolve a free-text query to matching places. Best results come from a precise name or full address; " +
+        "descriptive or category-style queries degrade - for category discovery use search_nearby_places. " +
+        "Use get_place_details on a returned id for opening hours, contact info, and other attributes.",
+};
+const RESULT_GUIDANCE_BY_SOURCE = {
+    [PLACES_SOURCE.GOOGLE]: "Phrase queries in natural language (names, full addresses, or descriptive POI searches) for stronger matches.",
+    [PLACES_SOURCE.OSM]: "Use a precise name or full address; descriptive or category queries return weak matches.",
+};
+function selectForSource(map, source, fallback) {
+    return map[source] ?? fallback;
+}
 export function getGeocodePlaceToolConfig(placesManager) {
+    const defaultSource = placesManager.getDefaultSource();
+    const baseDescription = selectForSource(DESCRIPTION_BY_SOURCE, defaultSource, NEUTRAL_DESCRIPTION);
+    const routingLine = routingDescriptionLine(defaultSource);
+    const description = routingLine ? `${baseDescription} ${routingLine}` : baseDescription;
+    const resultGuidance = selectForSource(RESULT_GUIDANCE_BY_SOURCE, defaultSource, NEUTRAL_RESULT_GUIDANCE);
     const inputSchema = {
-        name: z.string().min(1).optional().describe("Proper-noun name of a specific place or business."),
-        street: z.string().min(1).optional().describe("Street address, including house number when known."),
-        city: z.string().min(1).optional().describe("City, town, or locality. Example: 'London', 'Paris'."),
-        postcode: z.string().min(1).optional().describe("Postal / ZIP code."),
+        query: z.string().min(1).describe("A place name, a full address, or a landmark (e.g. 'Eiffel Tower')."),
+        city: z.string().min(1).optional().describe("City, town, or locality to disambiguate the query."),
         country: z
             .string()
             .min(1)
             .optional()
-            .describe("Country name or ISO 3166-1 alpha-2 code (e.g. 'France' or 'FR'). Use to disambiguate same-named places across countries."),
+            .describe("Country name or ISO 3166-1 alpha-2 code (e.g. 'France' or 'FR') to disambiguate same-named places."),
         nearLatitude: z
             .number()
             .min(-90)
@@ -22,6 +45,7 @@ export function getGeocodePlaceToolConfig(placesManager) {
             .optional()
             .describe("Optional latitude for ranking bias - prefers candidates near this point."),
         nearLongitude: z.number().min(-180).max(180).optional().describe("Optional longitude paired with nearLatitude."),
+        ...routingOriginInputSchema,
         limit: z
             .number()
             .int()
@@ -31,14 +55,18 @@ export function getGeocodePlaceToolConfig(placesManager) {
             .describe(`Max results to return (default ${DEFAULT_GEOCODE_LIMIT}, max ${MAX_GEOCODE_LIMIT}).`),
     };
     const handler = async (args) => {
-        const queryParts = [args.name, args.street, args.city, args.postcode, args.country]
+        if ((args.nearLatitude === undefined) !== (args.nearLongitude === undefined)) {
+            return textToolResult(["nearLatitude and nearLongitude must both be provided or both omitted."], true);
+        }
+        const routing = resolveRoutingOrigin(args);
+        if ("error" in routing) {
+            return textToolResult([routing.error], true);
+        }
+        const queryParts = [args.query, args.city, args.country]
             .map((part) => part?.trim())
             .filter((part) => part !== undefined && part.length > 0);
         if (queryParts.length === 0) {
-            return textToolResult(["At least one of name, street, city, postcode, or country must be provided."], true);
-        }
-        if ((args.nearLatitude === undefined) !== (args.nearLongitude === undefined)) {
-            return textToolResult(["nearLatitude and nearLongitude must both be provided or both omitted."], true);
+            return textToolResult(["query must contain non-whitespace text."], true);
         }
         const queryText = queryParts.join(", ");
         try {
@@ -48,14 +76,15 @@ export function getGeocodePlaceToolConfig(placesManager) {
             const places = await placesManager.geocode({
                 text: queryText,
                 near,
+                routingOrigin: routing.routingOrigin,
                 limit: args.limit ?? DEFAULT_GEOCODE_LIMIT,
             });
             if (places.length === 0) {
-                return textToolResult([`No places found matching "${queryText}".`]);
+                return textToolResult([`No places found matching "${queryText}".`, resultGuidance]);
             }
             const header = `[Geocode results: ${places.length} for "${queryText}"]`;
             const body = places.map(formatPlaceSummary).join("\n");
-            return textToolResult([header, body]);
+            return textToolResult([header, body, resultGuidance]);
         }
         catch (error) {
             return getErrorToolResult(error, "Failed to geocode place.");
@@ -63,12 +92,7 @@ export function getGeocodePlaceToolConfig(placesManager) {
     };
     const config = {
         name: GEOCODE_PLACE_TOOL_NAME,
-        description: [
-            "Resolve a known place to coordinates: a named landmark, business, or specific street address. ",
-            "Provide whichever structured fields you have - the more you fill, the more precise the match. ",
-            "Not a discovery tool: for 'cafes near me', 'good restaurants', or any category / subjective query, use search_nearby_places instead. ",
-            "Use get_place_details on a returned id for opening hours, contact info, and other attributes.",
-        ].join(""),
+        description,
         inputSchema,
         handler,
     };

package/dist/mcp/places/places-format-utils.js

@@ -1,4 +1,4 @@
-import { WEEKDAY, } from "../../services/places/places-manager.types.js";
+import { BUSINESS_STATUS, WEEKDAY, } from "../../services/places/places-manager.types.js";
 const WEEKDAY_LABEL = {
     [WEEKDAY.MONDAY]: "Monday",
     [WEEKDAY.TUESDAY]: "Tuesday",
@@ -19,8 +19,38 @@ export function formatPlaceSummary(place) {
     if (place.address !== undefined && place.address.length > 0) {
         lines.push(`    - Address: ${place.address}`);
     }
+    if (place.businessStatus !== undefined && place.businessStatus !== BUSINESS_STATUS.OPERATIONAL) {
+        lines.push(`    - Business status: ${place.businessStatus}`);
+    }
+    if (place.mapsUrl !== undefined && place.mapsUrl.length > 0) {
+        lines.push(`    - Map: ${place.mapsUrl}`);
+    }
+    if (place.routing !== undefined) {
+        const { durationSeconds, distanceMeters, travelMode, directionsUrl } = place.routing;
+        lines.push(`    - Travel: ${humanizeDuration(durationSeconds)} · ${humanizeDistance(distanceMeters)} (${travelMode})`);
+        if (directionsUrl !== undefined && directionsUrl.length > 0) {
+            lines.push(`    - Directions: ${directionsUrl}`);
+        }
+    }
     return lines.join("\n");
 }
+/** "8 min" under an hour, "1 h 12 min" (or "2 h" on the hour) above. */
+function humanizeDuration(totalSeconds) {
+    const totalMinutes = Math.round(totalSeconds / 60);
+    if (totalMinutes < 60) {
+        return `${totalMinutes} min`;
+    }
+    const hours = Math.floor(totalMinutes / 60);
+    const minutes = totalMinutes % 60;
+    return minutes === 0 ? `${hours} h` : `${hours} h ${minutes} min`;
+}
+/** "850 m" under a kilometre, "3.2 km" (one decimal) above. */
+function humanizeDistance(meters) {
+    if (meters < 1000) {
+        return `${Math.round(meters)} m`;
+    }
+    return `${(meters / 1000).toFixed(1)} km`;
+}
 /** Full-detail block returned by `places_get_details`. Layers attributes on top of the summary. */
 export function formatPlaceDetails(details) {
     const lines = [formatPlaceSummary(details)];
@@ -48,6 +78,12 @@ export function formatPlaceDetails(details) {
     if (details.wheelchairAccess !== undefined) {
         lines.push(`    - Wheelchair access: ${details.wheelchairAccess}`);
     }
+    if (details.transit !== undefined && details.transit.lines.length > 0) {
+        lines.push("    - Transit lines:");
+        for (const line of details.transit.lines) {
+            lines.push(`        ${formatTransitLine(line)}`);
+        }
+    }
     if (details.description !== undefined && details.description.length > 0) {
         lines.push("    - Description:");
         for (const descriptionLine of details.description.split(/\r?\n/)) {
@@ -56,6 +92,16 @@ export function formatPlaceDetails(details) {
     }
     return lines.join("\n");
 }
+function formatTransitLine(line) {
+    let formatted = `${line.vehicleType}  ${line.shortName ?? line.name}`;
+    if (line.shortName !== undefined && line.shortName !== line.name) {
+        formatted += ` (${line.name})`;
+    }
+    if (line.operator !== undefined) {
+        formatted += ` — ${line.operator}`;
+    }
+    return formatted;
+}
 function formatOpeningHoursLines(hours) {
     if (hours.alwaysOpen) {
         return ["Open 24/7"];

package/dist/mcp/places/places-routing-input.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { PLACES_SOURCE, TRAVEL_MODE, } from "../../services/places/places-manager.types.js";
+const TRAVEL_MODE_VALUES = Object.values(TRAVEL_MODE);
+/** Optional routing-origin inputs shared by the place search and geocode tools. */
+export const routingOriginInputSchema = {
+    originLatitude: z
+        .number()
+        .min(-90)
+        .max(90)
+        .optional()
+        .describe("Latitude of the travel origin; pair with originLongitude to attach travel time and distance."),
+    originLongitude: z
+        .number()
+        .min(-180)
+        .max(180)
+        .optional()
+        .describe("Longitude of the travel origin; must be paired with originLatitude."),
+    travelMode: z
+        .enum(TRAVEL_MODE_VALUES)
+        .optional()
+        .describe("Travel mode for the origin (default DRIVE). Ignored unless an origin is provided."),
+};
+/**
+ * Validate the both-or-neither origin pair and build a `RoutingOrigin`. A
+ * `travelMode` without an origin is a no-op rather than an error.
+ */
+export function resolveRoutingOrigin(args) {
+    const { originLatitude, originLongitude, travelMode } = args;
+    if ((originLatitude === undefined) !== (originLongitude === undefined)) {
+        return { error: "originLatitude and originLongitude must both be provided or both omitted." };
+    }
+    if (originLatitude === undefined || originLongitude === undefined) {
+        return { routingOrigin: undefined };
+    }
+    const routingOrigin = { point: { latitude: originLatitude, longitude: originLongitude } };
+    if (travelMode) {
+        routingOrigin.travelMode = travelMode;
+    }
+    return { routingOrigin };
+}
+const ROUTING_DESCRIPTION_BY_SOURCE = {
+    [PLACES_SOURCE.GOOGLE]: "Provide originLatitude/originLongitude to attach travel time and distance to each result.",
+    [PLACES_SOURCE.OSM]: "Travel time and distance to results are not available on this source.",
+};
+/** One-line, source-aware note about routing support for a tool description. */
+export function routingDescriptionLine(source) {
+    return ROUTING_DESCRIPTION_BY_SOURCE[source];
+}
+//# sourceMappingURL=places-routing-input.js.map

package/dist/mcp/places/search-nearby-places.js

@@ -2,12 +2,17 @@ import { z } from "zod";
 import { PLACE_CATEGORY } from "../../services/places/places-manager.types.js";
 import { getErrorToolResult, textToolResult } from "../tool-utils.js";
 import { formatPlaceSummary } from "./places-format-utils.js";
+import { resolveRoutingOrigin, routingDescriptionLine, routingOriginInputSchema } from "./places-routing-input.js";
 const DEFAULT_SEARCH_NEARBY_LIMIT = 20;
 const MAX_SEARCH_NEARBY_LIMIT = 50;
 const MAX_SEARCH_NEARBY_RADIUS_METERS = 50_000;
 const CATEGORY_VALUES = Object.values(PLACE_CATEGORY);
 export const SEARCH_NEARBY_PLACES_TOOL_NAME = "search_nearby_places";
+const BASE_DESCRIPTION = "Find places of a given category within a radius around a point. Use get_place_details with a returned id " +
+    "for opening hours, contact info, and other attributes.";
 export function getSearchNearbyPlacesToolConfig(placesManager) {
+    const routingLine = routingDescriptionLine(placesManager.getDefaultSource());
+    const description = routingLine ? `${BASE_DESCRIPTION} ${routingLine}` : BASE_DESCRIPTION;
     const inputSchema = {
         latitude: z.number().min(-90).max(90).describe("Latitude of the search center."),
         longitude: z.number().min(-180).max(180).describe("Longitude of the search center."),
@@ -20,6 +25,7 @@ export function getSearchNearbyPlacesToolConfig(placesManager) {
         category: z
             .enum(CATEGORY_VALUES)
             .describe("Curated place category to filter by. Use OTHER only as a last resort - prefer a more specific value."),
+        ...routingOriginInputSchema,
         limit: z
             .number()
             .int()
@@ -29,6 +35,10 @@ export function getSearchNearbyPlacesToolConfig(placesManager) {
             .describe(`Max results to return (default ${DEFAULT_SEARCH_NEARBY_LIMIT}, max ${MAX_SEARCH_NEARBY_LIMIT}).`),
     };
     const handler = async (args) => {
+        const routing = resolveRoutingOrigin(args);
+        if ("error" in routing) {
+            return textToolResult([routing.error], true);
+        }
         try {
             const places = await placesManager.searchPlaces({
                 area: {
@@ -37,6 +47,7 @@ export function getSearchNearbyPlacesToolConfig(placesManager) {
                     radiusMeters: args.radiusMeters,
                 },
                 category: args.category,
+                routingOrigin: routing.routingOrigin,
                 limit: args.limit ?? DEFAULT_SEARCH_NEARBY_LIMIT,
             });
             const areaLabel = `within ${args.radiusMeters}m of ${args.latitude.toFixed(6)}, ${args.longitude.toFixed(6)}`;
@@ -53,7 +64,7 @@ export function getSearchNearbyPlacesToolConfig(placesManager) {
     };
     const config = {
         name: SEARCH_NEARBY_PLACES_TOOL_NAME,
-        description: "Find places of a given category within a radius around a point. Use get_place_details with a returned id for opening hours, contact info, and other attributes.",
+        description,
         inputSchema,
         handler,
     };