Homesage.ai MCP

by ai.homesage.api

Overview Discussions Admin

Get Solar & Roof Analysis

get_solar_analysis

Read-only

What it returns

Two coupled analyses in one call:

Solar Potential — 20-year cost projection, payback timeline, energy coverage percentage, federal/state incentive estimate.
Roof Condition — AI roof condition score (0-10), condition category, material identification, damage indicators, and risk assessment, from AI analysis of aerial imagery.

When to use it

Pre-screen properties for solar installation viability.
Underwrite roof replacement cost for an investor offer.
Add a solar-readiness flag to a property report.

Performance

This is an expensive, slow endpoint — use a 90-second client timeout and cache responses.

Response shape

The response shape varies with the optional query parameters:

detailed=true — adds the raw solar_potential.data blob and includes both roof_image_url and roof_image_base64 in roof_condition.imagery.
agent=false — sets roof_condition.analysis to null (skips the AI roof analysis).

If the roof image fails to upload to storage, roof_condition.imagery contains roof_image_base64 (raw base64 PNG) instead of roof_image_url. Individual entries in solar_layers may be missing if a particular data layer was unavailable for the address.

FAQ

Why is `agent=true` the default?

Without it, the roof condition section is skipped (you get solar potential only). The AI roof analysis is the expensive part but it's what makes the endpoint useful — leave it on unless you specifically need solar-only.

What if the building isn't covered?

Returns a clear error indicating imagery unavailable. Charges 0 credits in that case.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "address": "<address>"
    },
    "name": "get_solar_analysis"
  }
}

Input Schema

Name	Required	Description
`agent`	No	Run the AI roof analysis. Default `true`. Set `false` to skip it (sets `roof_condition.analysis` to null).
`address`	Yes	Full property address.
`detailed`	No	Include the raw solar data blob + base64 roof image alongside the storage URL. Default `false`.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 3, 2026

TDQS

A4.2/5.0

Behavior5/5

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses that the endpoint is expensive and slow, recommends a 90-second timeout and caching, and explains credit charging (0 credits when imagery is unavailable). It also documents degraded modes: a base64 fallback when image upload fails and possible missing entries in solar_layers.

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

Conciseness3/5

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

The markdown headers make it scannable and the return-value content is front-loaded, but the FAQ section repeats information already given in 'Response shape' and the schema, notably the agent=true default explained twice. That redundancy makes a long description longer without adding decision-relevant 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 three-parameter, one-required-address lookup with an output schema, the description covers cost/timing warnings, degraded response modes, credit behavior, and failure handling ('imagery unavailable' error with zero credits). Nothing an agent needs in order to invoke it safely or interpret the result is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by tying each optional flag to a concrete response-shape consequence (detailed adds the raw data blob and base64 image, agent=false nulls out roof_condition.analysis). The address parameter itself gets no added semantics beyond the schema example.

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

Purpose4/5

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

The description states a specific resource and enumerates exactly what comes back: a 20-year solar cost projection plus an AI roof condition score with material and damage indicators. It stops short of naming a sibling to distinguish from, so an agent must infer on its own how this differs from get_property_condition or get_renovation_cost.

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?

A dedicated 'When to use it' block gives three concrete scenarios (pre-screening solar viability, underwriting roof replacement, adding a solar-readiness flag), and the FAQ clarifies that agent should stay on unless solar-only output is needed. There are no explicit exclusions or named alternative tools, so the routing guidance is clear but incomplete.

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

All Homesage.ai MCP tools Inspect

Try in Browser