SimplyRETS MCP by usefulapi

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful context about what data comes back (vendor ids, sync times, endpoints), but does not explain auth prerequisites, side effects, or clarify the cryptic trailing 'OPTIONS /.'.

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

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

It is a single compact sentence that front-loads the core idea ('What these API credentials can reach') before enumerating items. The trailing 'OPTIONS /.' fragment is unexplained and slightly undermines the structure, preventing a 5.

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

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

With no output schema, the description must serve as the return-value spec, and it does list the significant fields and endpoint strings an agent would receive. It stops short of a complete contract (e.g. the meaning of 'OPTIONS /.' and response shape), so it is solid but not exhaustive.

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

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

Zero parameters, so the baseline is 4; there is no parameter surface for the description to explain. The description does not need to compensate for schema gaps, and it introduces no misleading parameter semantics.

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

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

The description concretely enumerates what the tool exposes (MLS vendor ids, last-sync times, usernames, available endpoints), which is a specific resource-level statement rather than a restatement of the title. It is clearly distinguishable from listing/analytics siblings, though the leading fragment doesn't use an explicit verb like 'Returns'.

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

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

Usage is only implied: 'needed as `vendor` on multi-MLS apps' hints at the downstream field it supplies, but there is no explicit when-to-call guidance or comparison against siblings like simplyrets_get_feed_metadata. The agent must infer that this is a credential-discovery call.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the underlying operation ('OPTIONS /properties') and, critically in the absence of an output schema, enumerating what the response contains. It still says nothing about auth/permissions or rate limits on a live MLS feed.

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

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

Two short fragments with no filler, and the core content (what values are available) is front-loaded. 'OPTIONS /properties' is a slightly implementation-flavored trailing detail but is compact and informative.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating the metadata categories plus the last sync time. The main omission is that it never signals the vendor argument matters on multi-MLS apps, though the schema covers that.

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

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

Schema description coverage is 100% and the single vendor parameter is fully documented there, including the multi-MLS requirement, so baseline 3 applies. The description makes no reference to the vendor parameter at all, adding no semantics beyond the schema.

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

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

The description names the specific resource (MLS feed metadata) and enumerates exactly what it contains — statuses, property types, cities, counties, neighborhoods, areas, features, and last sync time — which clearly separates it from siblings like simplyrets_search_listings or simplyrets_get_listing. It is a noun phrase rather than an explicit verb+resource, but the intent is unambiguous.

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

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

The phrase 'to build valid searches' implies the intended use — fetch allowable values before constructing a search — but it never states when-not to use this tool or names an alternative among the nine siblings. Usage is inferable rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that by enumerating the detail sections returned (address, geo, price, photos, agent, office, property, school, tax, remarks) and identifying the underlying endpoint, letting an agent judge whether a call is worth making.

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

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

Two tight sentences with the identifier disambiguation front-loaded before the payload inventory, and the endpoint appended as a compact anchor. Every clause carries information; nothing is restated from the name or title.

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

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

With no output schema, the description compensates by naming the returned data categories, and it correctly notes the include extras are conditional on feed availability. It does not address failure behavior for an unknown or foreign id, which is the one remaining gap for a lookup tool.

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

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

Schema description coverage is 100%, so the baseline is 3; the description exceeds it by clarifying that mlsId is the search-result number and explicitly NOT the public listingId, which prevents a plausible and costly misinvocation. It says nothing additional about vendor or include, which the schema already covers.

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

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

States a specific verb and resource (one listing by its SimplyRETS id) and immediately pins the exact identifier semantics, which is the real source of confusion in this domain. The trailing GET /properties/{mlsId} makes the retrieval contract unambiguous and clearly separates it from simplyrets_search_listings.

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

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

Gives clear context for use: fetch full detail for a single known listing, with the disambiguation that mlsId is the number in search results while listingId is the public MLS number. It never explicitly names simplyrets_search_listings as the way to obtain that mlsId, so routing is inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the REST path, which is not behavioral context – nothing about return shape, metric availability, rate limits, or whether analytics may be empty for some listings.

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

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

Two short sentences with the purpose front-loaded and no filler. The second sentence is largely redundant endpoint plumbing, which is the only thing keeping this from a 5.

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

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

With no output schema, the description carries the burden of describing what comes back, and it offers only a single example metric ('price per square foot'). Adequate to identify the tool, but thin for an analytics endpoint whose full metric set is unknown.

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

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

Schema description coverage is 100%: mlsId and vendor are both documented in the schema, including the multi-MLS requirement for vendor. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a clear resource and scope: analytics for a single listing, with 'price per square foot' as a concrete example metric. It implicitly contrasts with simplyrets_get_market_analytics via 'one listing', but never names that sibling, so an agent must infer the distinction.

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

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

No when-to-use guidance, no prerequisites, and no routing to alternatives. The agent is not told when this beats simplyrets_get_listing or simplyrets_get_market_analytics, nor what conditions must hold to call it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing the non-obvious fact that results are a search-driven aggregate (not a listing-level read) and by enumerating the computed statistics, which matters since no output schema exists.

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

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

Two front-loaded sentences that carry the purpose, the output contents and the filtering model, with no repetition. The trailing API path 'GET /properties/analytics' is near-redundant affordance information rather than agent-relevant guidance, keeping it just short of a 5.

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

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

For a 33-parameter, zero-required aggregate tool with full schema coverage but no output schema, the description supplies the two things the structured data cannot: the aggregate nature of the response and the equivalence to search_listings filters. It omits only minor operational detail such as defaults for status/type and whether filters actually narrow the aggregate.

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

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

Schema description coverage is 100% across 33 parameters, so the schema documents filter syntax, enums and defaults fully; the baseline is 3. The description's only semantic contribution is the equivalence claim ('same filters as simplyrets_search_listings'), which helps an agent transfer known filter semantics but adds no per-parameter detail.

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

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

States a specific verb+resource (aggregate statistics over listings matched by a search) and enumerates exactly what is returned: total count, average price, bedrooms, baths, living area, lot size, year built, and counts per area. It also distinguishes itself from the sibling simplyrets_search_listings by positioning itself as the aggregate counterpart.

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

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

Gives clear when-to-use guidance ('Use it for market summaries of a city, zip or price band') and ties filtering semantics to simplyrets_search_listings ('same filters as'), which tells the agent how to build input. It does not, however, contrast itself with the similarly named sibling simplyrets_get_listing_analytics, leaving some selection ambiguity.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds only the endpoint path and key provenance, which are useful but not behavioral context beyond the annotations.

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

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

Two compact sentences with zero waste, front-loading what the tool returns and the key source before the endpoint detail.

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

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

For a simple read-only single-record getter with full schema coverage and safety annotations, the description is sufficiently complete. It does not describe the returned open house object, but the purpose is clear enough for correct invocation.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including openHouseKey's source. The description does not add syntax, format, or meaning beyond what the schema provides.

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

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

States a specific verb+resource ('One open house by its key') and identifies the exact identifier, immediately distinguishing it from the sibling list_open_houses. The endpoint reference reinforces the single-record retrieval scope.

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

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

Explicitly tells the agent that the key comes from a list result, which establishes the intended fetch-after-list workflow. It does not name alternatives or explicit when-not conditions, but context is clear for a single-record getter.

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

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

Annotations already declare read-only, open-world, and non-destructive behavior. The description adds important operational context beyond them: the tool requires the Agents API add-on, demo credentials return an empty list, and it maps to GET /agents. This is meaningful, though it does not cover pagination behavior or response format.

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

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

Two sentences that are front-loaded with what the tool returns, followed by a prerequisite and endpoint. The content is efficient, though the trailing 'GET /agents' is slightly redundant and could be trimmed.

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

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

For a read-only listing tool with no output schema and six optional parameters fully documented in the schema, the description supplies crucial setup context (add-on requirement, demo behavior) and enumerates return fields. It is nearly complete, but could mention pagination hints or filtering behavior.

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

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

Schema description coverage is 100%, and the description does not discuss any of the six parameters (q, name, limit, state, offset, vendor). With the schema fully documenting each parameter, the baseline of 3 applies; the description adds no parameter-level meaning.

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

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

The description clearly identifies the resource as the MLS agent roster and enumerates the returned fields (id, name, address, contact, office), making its purpose immediately clear. However, it does not explicitly differentiate from sibling tools like simplyrets_list_offices or explain when to prefer this over other listing endpoints, so it stops short of a 5.

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

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

The only guidance is a prerequisite ('Needs the Agents API add-on') and an environmental caveat about demo credentials. There is no statement of when to use this tool versus alternatives, nor any exclusion criteria, so an agent has to infer its use from the name and context alone.

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

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

Annotations already declare read-only, non-destructive, open-world. The description adds genuine context beyond them: the add-on requirement/authorization constraint and the newest-modification-first ordering. It adds value while annotations carry the safety profile, though it omits pagination/response behavior.

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

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

Three short sentences, front-loaded with the resource and ordering, then the prerequisite, then the parameter tip and endpoint. Every sentence carries information and nothing is wasted.

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

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

For a read-only list tool with full schema coverage and no output schema, the description covers purpose, ordering, the key access prerequisite, and the endpoint. Nothing critical is missing, though pagination behavior could be noted.

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

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

Schema coverage is 100%, so the schema already documents all 8 parameters thoroughly. The description's only parameter mention ('pass count=true for the total') repeats what the schema's count description already states, adding no new semantics. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('brokerage office roster of the MLS feed') and adds the sort order, which is concrete and unambiguous. It does not explicitly differentiate from the related list_agents/list_open_houses siblings, but the resource named is distinct enough to route correctly.

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

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

Provides an important prerequisite (Offices API add-on required, demo credentials cannot use it), which is real usage guidance. However, it gives no when-to-use vs alternative, and no guidance on pagination strategy or when count=true matters.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds useful behavioral detail by naming the pagination mechanism (next.offset or next.lastId) and disclosing the underlying GET /openhouses endpoint, though it does not discuss auth or vendor requirements.

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

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

The definition is compact and front-loaded: the first clause establishes scope, the filter list follows immediately, and pagination plus endpoint are appended without filler. Every sentence contributes useful information.

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

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

With 17 parameters, no output schema, and full schema descriptions, the description gives enough context to call the tool: it identifies the resource, return association (open houses with listings), filters, and pagination. Minor gaps like sort behavior and vendor handling are adequately covered by the schema.

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

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

Schema description coverage is 100%, so every parameter is already documented in the input schema. The description groups the filters into a readable list and mentions pagination, but adds no new parameter semantics beyond what the schema provides, making baseline 3 appropriate.

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

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

The description states a specific verb and resource: list upcoming open houses together with their parent listings. This clearly distinguishes the collection operation from the sibling get_open_house tool, which retrieves a single open house.

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

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

The description lists the available filters and explains pagination, which implies it is a search/listing tool. However, it never explicitly says when to use this instead of get_open_house or search_listings, so the usage guidance remains implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it specifies the return fields ('address, price, status, photos, agent, office, property details and remarks, without empty fields'), notes that count=true returns total matches (and may be slower on big feeds), and explains pagination via next.offset or next.lastId. This goes beyond the annotations and schema.

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

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

The description is a single, tightly written paragraph that front-loads the core purpose, then enumerates filters, return values, and pagination without any redundant or filler sentences. Every clause adds useful information for an agent.

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

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

Given the tool's complexity (47 parameters, no output schema), the description does a good job covering the essential context: it describes what can be filtered, what is returned, and how to paginate and count. It omits some details like default status (Active) or default type (residential and rental), but those are clearly stated in the schema descriptions, so the overall completeness is strong.

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

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

Schema description coverage is 100%, so the schema already documents all 47 parameters in detail. The description provides a high-level list of filter categories (keyword, status, type, price, beds, baths, area, year, city, zip, neighborhood, agent, broker, features, map polygon) and mentions count and pagination, but it does not add meaning or syntax beyond what the schema provides. With full schema coverage, a baseline of 3 is appropriate.

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

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

The description explicitly states the verb 'search' and the resource 'MLS listings', and lists filtered attributes (keyword, status, type, price, etc.) that distinguish it from sibling tools like simplyrets_get_listing or simplyrets_list_open_houses. An agent can immediately understand that this is a broad listing search endpoint.

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

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

Usage is implied by the description ('Search MLS listings ... by keyword, status ...'), but there is no explicit guidance on when to choose this tool over alternatives, nor any exclusions. The note 'Pass count=true to get the total' and pagination hints provide some operational context, but a clearer statement such as 'use this instead of get_listing when you need to find multiple listings' is missing.

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