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

Fetch property listings from a OneHome consumer-share. Use a saved search ID for agent-curated homes, or a group ID for direct browsing, with pagination and sorting.

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 that returns 0 (the access-restricted shape consumer-shares hit) AND the session context has a savedSearchId, the tool transparently falls back to the saved-search path. If there's no fallback target it raises a clear error rather than silently returning empty.

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

TableJSON 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.6/5.0
Behavior5/5

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

Goes far beyond the readOnly/idempotent annotations by disclosing fallback behavior, the exact fallback condition, error-raising when no fallback exists, session-context defaults, sort defaults, include_dislikes default, and the GraphQL projection limitation with no PublicRemarks/description field. This is rich behavioral context an agent needs.

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

Conciseness5/5

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

The description is long but densely informative with no filler. The mode breakdown is front-loaded, followed by defaults, fallback behavior, and output limitations. Every sentence earns its place given the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 7 parameters, no output schema, and complex fallback logic, the description covers the essential invocation semantics, result projection, and limitations, and routes to onehome_get_property for full descriptions. It doesn't detail pagination behavior or the exact response envelope, but the missing pieces are comparatively minor and partially inferable from the schema.

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?

With schema coverage at only 14%, the description compensates well by explaining group_id vs saved_search_id semantics, session-context defaults, include_dislikes default, and sort defaults tied to sort_field/sort_order. However, page_num, page_size, and sort_order behavior are not explicitly described, so it doesn't fully cover all parameters.

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 action ('Fetch listings') on a specific resource ('a OneHome consumer-share') and immediately distinguishes its two operating modes. It differentiates from sibling tools by clarifying the consumer-share context and explicitly directing the agent to onehome_get_property when full descriptions are needed.

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?

Provides strong mode-selection guidance: saved_search_id mode is called 'the only mode that works for non-agent consumer accounts', and the fallback condition for the raw endpoint is described precisely. It also tells the agent when to use onehome_get_property instead. It doesn't explicitly contrast with nearby sibling search tools like onehome_get_saved_search_with_listings, but the operational guidance is clear.

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