Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.footstep.ai/llms.txt

Use this file to discover all available pages before exploring further.

Every Footstep MCP tool returns a result in the same envelope. This page describes the wire shape so your client can read responses without per-tool conditionals.

​
Result envelope

Tool results are delivered via the MCP structuredContent field. The value is a parsed JSON object — your client reads it directly, no JSON.parse step required. 
{
  "structuredContent": {
    "destination": { "name": "London Bridge", "coordinates": { "lat": 51.508, "lng": -0.087 } },
    "route": { "distance_meters": 4312, "duration_seconds": 723, "narrative": "..." },
    "render": [
      { "kind": "linestring", "label": "Route", "data": { ... }, "bbox": [...] }
    ]
  }
}
Use any MCP client that supports structuredContent (e.g. @modelcontextprotocol/sdk ≥ 1.0).

​
Errors

Hard failures (the tool ran but couldn’t compute a result) are returned with MCP’s isError: true flag and a structured error object in structuredContent: 
{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": "no_route_found",
      "message": "No route found between the supplied points.",
      "details": { "origin": [-0.124, 51.532], "destination": [-3.187, 55.953] }
    }
  }
}
Soft cases (the tool ran and produced a valid empty answer — for example, geocode with a query that matches no places) are not errors. They return a normal success response with empty arrays: 
{
  "structuredContent": {
    "results": []
  }
}
This separation lets clients pattern-match on error.code for branching UX — “ask the user to clarify” vs “retry with backoff” vs “suggest an alternative travel mode” — without parsing free-text messages.

​
Error codes

CodeMeaningRecommended client action
invalid_inputSchema validation failedFix the request, retry
out_of_boundsCoordinate outside service areaSurface region limit to user
unroutable_pointOrigin or destination not on routable networkSuggest nearest road or alternative point
no_route_foundEndpoints valid but no path computableSuggest alternative travel mode or different endpoints
geocode_ambiguousMultiple high-confidence matchesAsk user to clarify; details.candidates carries options
prediction_no_signalget_prediction ran but produced a degenerate resultSurface “insufficient data” to user
prediction_unsupportedget_prediction lacks required inputsFix request, retry
upstream_timeoutUnderlying service didn’t respond in timeRetry with backoff (idempotent calls only)
upstream_errorGeneric upstream failureRetry with backoff
rate_limitedQuota exceededBack off; details.retry_after_seconds indicates wait
The error.details field is optional and carries code-specific structured information (candidate matches for geocode_ambiguous, retry timing for rate_limited, the offending field for invalid_input, etc.).

​
What’s in structuredContent

The keys you’ll see depend on the tool. Most renderer-aware tools share three groups:
  • Summary fields — distance_meters, duration_seconds, narrative, terrain, bounds-equivalent inside render[].bbox, etc. Always present unless the response is an error.
  • Raw geometry — legs[].shape (polylines), contours[].geometry (polygons), top_results (hex rows), etc. Controlled by response defaults.
  • render envelope — framework-agnostic layer descriptors ready to drop into a map library. Controlled by include_render (default true). Detailed in the render envelopes reference.
See per-tool reference pages for the exact keys each tool returns.