Skip to main content
Glama
chrischall

onehome-mcp

by chrischall
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Search listings inside a OneHome group / saved share

onehome_search_properties
Read-onlyIdempotent

Search and fetch OneHome consumer-share listings by saved search or group ID; falls back to curated saved-search results when direct browsing is restricted.

Instructions

Fetch listings inside a OneHome consumer-share. Two modes:

  • With saved_search_id: fetch the agent-curated collection (the standard 'Homes at ' view). The MCP first resolves the saved search's listingIds and then inflates them via listingsBySavedSearchId — this is the only mode that works for non-agent consumer accounts.

  • With just group_id and no saved_search_id: try the raw listings(groupId, browseParameter) endpoint. If page 0 comes back empty with no reported results (the access-restricted shape consumer-shares hit) AND the session context has a savedSearchId for that same group, the tool falls back to the saved-search path and marks the response fell_back_to_saved_search: true. If there's no fallback target it raises a clear error rather than silently returning empty. An empty later page (paging past the end) is returned as an empty page, never swapped for the saved-search collection.

Both args default from the MCP's bootstrapped session context (the magic-link checkToken response) when neither is passed explicitly. Sort is MajorChangeTimestamp DESC ('Newest') unless overridden. include_dislikes: false by default — flip it on to include listings you've thumbs-downed in OneHome.

Listings here are returned via the GraphQL listing-card projection, which does NOT include PublicRemarks — so there is no description field on search results and no include_description flag to opt into one. Each listing carries the structured extracted_features object instead. Use onehome_get_property(listing_id) per row when you need the full description for a specific listing.

Input Schema

NameRequiredDescriptionDefault
group_idNo
page_numNo
page_sizeNo
sort_fieldNoGraphQL dotted-path, e.g. property.MajorChangeTimestamp or property.ListPrice
sort_orderNo
saved_search_idNo
include_dislikesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.0.0
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  2. First observedv0.13.1

TDQS

A4.8/5.0
Behavior5/5

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

Annotations cover the safety profile (readOnly, idempotent, openWorld), and the description adds substantial behavior beyond them: the empty-page fallback trigger, the `fell_back_to_saved_search` marker, the deliberate error instead of silent empty, the rule that paging past the end is never swapped, defaults bootstrapped from session context, default sort, and default include_dislikes.

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

Conciseness4/5

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

Front-loaded with mode selection before the fallback mechanics, and every sentence carries operative detail (fallback, error shape, projection limits). It is dense and long, but the length is buying real behavioral information rather than restating the name.

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?

No output schema exists, and the description compensates by describing the GraphQL listing-card projection, the absence of PublicRemarks/description, the presence of extracted_features, and the pointer to onehome_get_property for full text. An agent has everything needed to call and interpret results.

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 only 14% with 7 params, so the description must compensate and largely does: it explains session-context defaults for group_id/saved_search_id, the include_dislikes default and semantics, the sort default and override, and empty-page behavior tied to page_num. It does not explicitly bound page_size or fully characterize sort_order, leaving minor gaps.

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?

States a specific verb and resource ('Fetch listings inside a OneHome consumer-share') and immediately distinguishes the two operating modes by argument shape. An agent can tell this apart from onehome_get_saved_search_with_listings and onehome_get_property without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when each mode applies (saved_search_id vs group_id alone), which mode works for non-agent consumer accounts, and routes the agent to onehome_get_property(listing_id) per row when a full description is needed. Exclusions and fallback conditions are spelled out.

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

Deploy Server

Other Tools