Property listings in Portugal: search, market stats, comparables, neighbourhoods.
Given one listing, find comparable ones: same operation and area, similar typology, floor area and price. Use this when the user likes a property but wants alternatives — 'find me something similar', 'the same but cheaper', 'what else is there in this area'. Pass maxPrice for the cheaper case; without it, comparables are drawn from a band around the reference price. Comparability is by location, typology, area and price, not by text similarity: it answers 'is this well priced for what it is', which a keyword search cannot.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Slug of the reference listing, as returned by search_properties or get_property_detail. | |
| limit | No | Maximum number of comparables (default 6, max 20). | |
| maxPrice | No | Optional budget ceiling, in the market currency. Use it for 'similar but cheaper'; it overrides the default band around the reference price. |
| Name | Required | Description |
|---|---|---|
| total | Yes | Comparables returned. |
| market | Yes | |
| currency | No | |
| reference | Yes | The listing the comparables are measured against, echoed back for the comparison. |
| properties | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent, and non-destructive behaviour. The description adds meaningful behavioural context: comparables are drawn from a band around the reference price unless maxPrice overrides it, and the tool answers a pricing-adequacy question rather than a textual-match question. No annotation contradiction 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?
The description is three sentences with no filler: it states the core function first, then usage examples, then the crucial distinction from text search. Every sentence adds information needed to invoke the tool correctly.
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 tool with three parameters, full schema coverage, and an output schema, the description covers the key decisions an agent must make: when to call it, what makes properties comparable, and how maxPrice changes behaviour. The output schema handles return-value documentation, so nothing essential is missing.
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% and each parameter is well described in the schema. The description adds extra semantics for maxPrice ('overrides the default band', 'similar but cheaper') and clarifies slug as the reference listing. This is above baseline but not dramatically richer than the schema already 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?
The description uses a specific verb and resource: 'Given one listing, find comparable ones' and defines comparability dimensions (operation, area, typology, floor area, price). It also explicitly distinguishes itself from text-similarity search, so an agent can tell it apart from search_properties_by_description.
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?
It states exactly when to use the tool with user-intent examples like 'find me something similar' and 'the same but cheaper'. It also explains the maxPrice behaviour for the cheaper case and explicitly contrasts with keyword search, which is a clear when-to-use versus alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get price statistics for a slice of the Portugal property market: how many listings match, the median price, the p25–p75 range, the median price per m² and a breakdown by typology. Use this when the user asks what something costs, whether an asking price is fair, or how two areas compare — instead of listing individual properties. Takes the same filters as search_properties and describes exactly the set that tool would return, so the two never disagree. Reports medians and quartiles rather than averages, because property prices have a long right tail and a single luxury listing moves an average. Call once per area to compare areas.
| Name | Required | Description | Default |
|---|---|---|---|
| minArea | No | Minimum floor area in m². Matches either the gross or the useful area, whichever the source published. Only matches listings that published an area. | |
| location | No | Location: district, municipality, neighbourhood, town or postal-code prefix (e.g. Lisbon, Cascais, Chiado, 2750). Not a free-text keyword search — words that are not places (e.g. 'sea view') will not match. | |
| priceMax | No | Maximum price, in the market currency. Note: listings advertised 'price on request' have no price and are excluded by either price bound. | |
| priceMin | No | Minimum price, in the market currency. | |
| typology | No | Normalised typology code (T0, T1, T2, T3…), where the number is the count of bedrooms. Used in every market, including the German and Polish ones. Matched exactly; pass an array to match several. The buckets `T0–T1` and `T4+` are also accepted. | |
| condition | No | State of repair, or an array of states. Only matches listings whose source published it. | |
| operation | No | buy = for sale, rent = to let. Defaults to buy; a listing is one or the other, so call twice to cover both. | |
| energyClass | No | Energy certificate class. Selects the whole band the class belongs to: A+/A, B/B-, C, or D-and-below. Only matches listings that carry a certificate. | |
| minBathrooms | No | Minimum number of bathrooms. Only matches listings whose source published a bathroom count. | |
| propertyType | No | Property type, or an array of types. Omit to search all types. `farm` covers rural estates (quintas); `building` is a whole apartment block. |
| Name | Required | Description |
|---|---|---|
| count | Yes | Listings matching the filters, with or without a published price. |
| price | No | Price distribution, in percentiles. null when no matching listing publishes a price. There is deliberately no min or max: listings come from third-party sources and the extremes are set by data errors, not by the market. |
| market | Yes | |
| priced | Yes | Subset with a published price — the base of every figure below. A large gap to `count` means many listings in this slice are 'price on request'. |
| currency | Yes | |
| operation | Yes | |
| byTypology | Yes | Up to 6 most represented typologies, each with its own median. |
| pricePerM2Median | No | Median price per m² among listings that published both a price and an area. Best figure for comparing areas. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only, idempotent, and non-destructive, so the description carries a modest burden. It still adds valuable behavioral context: medians and quartiles are used instead of averages because of the long right tail, and the tool reports exactly the set search_properties would return so the two never disagree. These are meaningful choices an agent needs to interpret results correctly.
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 compact and every sentence earns its place: one for output definition, one for when to use it, one for filter agreement, one for statistical rationale, and one for comparing areas. The core purpose is front-loaded and no redundant phrasing appears.
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 aggregate tool with 100% schema coverage, an output schema, and strong annotations, the description covers the remaining context: when to call it, how to compare areas, why medians are reported, and how its result set relates to search_properties. Nothing essential is missing 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 the schema already documents all 10 parameters in detail. The description adds the useful high-level statement that it 'takes the same filters as search_properties,' but it does not contribute individual parameter semantics beyond the schema. 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?
The description opens with a specific verb and resource: 'Get price statistics for a slice of the Portugal property market' and enumerates the exact outputs (count, median price, p25–p75, median per m², typology breakdown). It also distinguishes itself from listing tools by saying it is used 'instead of listing individual properties,' so an agent can separate it from siblings like search_properties.
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 conditions are explicit: use it when the user asks 'what something costs, whether an asking price is fair, or how two areas compare.' It also gives a concrete alternative ('instead of listing individual properties'), references search_properties for filter compatibility, and instructs agents to call once per area. This fully routes the decision.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the complete record of one listing in Portugal by its slug. Use this after search_properties when the user asks about a specific property: full description, features, photos, energy rating, condition, floor, year built, seller and the original source URL to cite.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Unique listing slug, as returned by search_properties. |
| Name | Required | Description |
|---|---|---|
| url | Yes | Canonical listing page on this market's domain. |
| slug | Yes | Stable identifier; use it in get_property_detail. |
| floor | No | |
| phone | No | Advertiser phone when published at the source. |
| price | No | null means the source does not publish a price (on request). |
| title | Yes | |
| photos | No | Up to 5 image URLs. |
| source | No | Portal or agency site the listing came from; null when published directly with us. |
| bedrooms | No | |
| currency | No | ISO 4217 code of this market. |
| district | No | District or region. |
| elevator | No | |
| features | No | Amenities as published by the source (Portuguese labels). |
| landArea | No | Plot area in m²; relevant for houses, land and farms. |
| lastSeen | Yes | ISO 8601 date we last confirmed the listing at the source. |
| typology | No | T-notation typology (T0…T6+); empty when unknown. |
| verified | No | Advertiser identity verified by us. |
| bathrooms | No | |
| condition | No | |
| firstSeen | Yes | ISO 8601 date the listing was first published. |
| houseArea | No | Gross floor area in m². |
| operation | Yes | comprar = for sale, arrendar = to let. |
| sourceUrl | Yes | Original listing URL at the source. Cite this alongside url. |
| updatedAt | No | ISO 8601 date the record last changed on our side. |
| yearBuilt | No | |
| priceLabel | No | Formatted price for display; empty when price is null. |
| pricePerM2 | No | |
| sellerName | No | |
| usefulArea | No | Net/usable floor area in m². |
| description | No | |
| energyClass | No | |
| orientation | No | |
| municipality | No | Municipality (LAU) name. |
| propertyType | No | Property type; the same token accepted by the propertyType filter. |
| neighbourhood | No | Neighbourhood, when the source located the listing precisely enough. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety/repeatability is covered. The description adds useful context about what the record contains (photos, energy rating, seller, source URL) but doesn't disclose any additional behavioral traits such as error cases or rate limits. No contradiction with 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 sentences, front-loaded with purpose and followed by a useful usage condition. The field list is compact and earns its place by telling the agent what to expect in the returned record.
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 single-parameter read-only tool with a full output schema and annotations, the description covers what remains important: when to call it, what it returns, and how it relates to search_properties. No critical missing context 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 coverage is 100% and the single parameter is already described as 'Unique listing slug, as returned by search_properties.' The description reinforces that the slug comes from search_properties but adds no new semantic detail 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?
States a clear verb ('Get') and a precise resource: the complete record of one listing in Portugal by slug. The description also distinguishes this from search-oriented siblings by naming search_properties as the prerequisite and clarifying this is for a specific property.
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 explicit guidance: use after search_properties when the user asks about a specific property. It doesn't enumerate when-not-to-use alternatives like find_similar_properties or search_properties_by_description, but the stated condition is clear enough for an agent to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search editorial articles about the property market in Portugal: buying and renting guides, market analysis and practical advice. Use this when the user asks how something works — mortgages, contracts, taxes, the buying process — rather than asking for listings.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (default 5, max 10). |
| Name | Required | Description |
|---|---|---|
| articles | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds useful behavioral context by specifying the kind of content returned (editorial, educational articles) and the intent-driven use case, going beyond what the annotations alone convey.
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 dense sentences with no filler. The core subject and scope are front-loaded, and the usage guidance follows immediately. Every clause earns its place.
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?
The tool is simple: one optional parameter, strong annotations, and an output schema exist, so the description covers most needs. The only minor gap is that the schema exposes no search-query parameter, and the description does not explicitly explain how the search topic is derived from the conversation.
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?
The only parameter, limit, is fully described in the schema with default and maximum values, so schema coverage is 100%. The description does not need to restate it, and it adds no parameter-level detail, which is acceptable given the baseline.
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 opens with a specific verb and resource: 'Search editorial articles' and narrows the domain to the Portuguese property market, including buying/renting guides, market analysis, and practical advice. This clearly separates it from sibling tools that search properties, neighbourhoods, or market stats.
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?
It gives an explicit trigger condition: 'Use this when the user asks how something works — mortgages, contracts, taxes, the buying process'. It also states what it is not for: 'rather than asking for listings', which routes agents away from listing-focused sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search neighbourhood and municipality guides for Portugal, with median price per m² for buying and renting, price trend and an editorial summary. Use this when the user asks where to live or where to buy, or wants to compare areas, instead of asking for individual listings.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (default 8, max 20). | |
| query | No | Neighbourhood, municipality or district (e.g. Cascais, Príncipe Real). Omit to list all. |
| Name | Required | Description |
|---|---|---|
| total | Yes | |
| market | Yes | |
| neighbourhoods | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is established. The description adds behavioral context by disclosing exactly what kind of content the search returns, including price trends and editorial summaries, which helps the agent set expectations.
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 with no filler. The first sentence states what the tool returns, and the second gives clear usage guidance, making the most important information immediately accessible.
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 that the annotations cover safety, the schema covers both parameters, and an output schema exists, the description is complete enough for an agent to select and invoke this tool correctly. It covers the tool's purpose, return content, and usage context.
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 both parameters fully, including examples and defaults. The description reinforces the intended use but adds no additional parameter-level 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?
The verb 'Search' plus the resource 'neighbourhood and municipality guides for Portugal' is specific, and the description adds concrete output details: median price per m², price trend, and editorial summary. It also distinguishes itself from sibling tools by explicitly saying it is for area comparison rather than individual 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?
The description clearly states when to use the tool: when the user asks where to live or buy, or wants to compare areas. It gives a when-not signal ('instead of asking for individual listings'), though it does not name the specific sibling tool to use in that alternative case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search current residential, rural and commercial real-estate listings for sale or rent in Portugal. Use this whenever the user wants to find, compare or explore properties — by location, budget, typology, property type, condition or energy rating. Returns price, price per m², typology, areas, neighbourhood, source and a citable listing URL, plus total: the exact number of listings matching the filters, which makes this tool usable to answer 'how many' questions. Listings are aggregated from portals and agency sites and refreshed continuously; each result carries the date it was last checked at the source. Sources publish uneven detail: filtering on an attribute silently excludes listings that omit it, so prefer the broadest filters that answer the question and report total as a floor, not a census.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. Use it with `total` to walk through a large result set. | |
| sort | No | Result order. Default `recent` (most recently published first). | |
| limit | No | Results per page (default 10, max 20). | |
| minArea | No | Minimum floor area in m². Matches either the gross or the useful area, whichever the source published. Only matches listings that published an area. | |
| location | No | Location: district, municipality, neighbourhood, town or postal-code prefix (e.g. Lisbon, Cascais, Chiado, 2750). Not a free-text keyword search — words that are not places (e.g. 'sea view') will not match. | |
| priceMax | No | Maximum price, in the market currency. Note: listings advertised 'price on request' have no price and are excluded by either price bound. | |
| priceMin | No | Minimum price, in the market currency. | |
| typology | No | Normalised typology code (T0, T1, T2, T3…), where the number is the count of bedrooms. Used in every market, including the German and Polish ones. Matched exactly; pass an array to match several. The buckets `T0–T1` and `T4+` are also accepted. | |
| condition | No | State of repair, or an array of states. Only matches listings whose source published it. | |
| operation | No | buy = for sale, rent = to let. Defaults to buy; a listing is one or the other, so call twice to cover both. | |
| energyClass | No | Energy certificate class. Selects the whole band the class belongs to: A+/A, B/B-, C, or D-and-below. Only matches listings that carry a certificate. | |
| minBathrooms | No | Minimum number of bathrooms. Only matches listings whose source published a bathroom count. | |
| propertyType | No | Property type, or an array of types. Omit to search all types. `farm` covers rural estates (quintas); `building` is a whole apartment block. |
| Name | Required | Description |
|---|---|---|
| page | Yes | |
| shown | No | Listings returned on this page. |
| total | Yes | Exact number of listings in this market matching the filters, across all pages. |
| market | Yes | ISO country code of this market. |
| hasMore | Yes | true when further pages are available. |
| currency | No | |
| pageSize | No | |
| operation | No | The operation actually searched (comprar = for sale, arrendar = to let). |
| properties | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly discloses non-obvious behaviors: 'filtering on an attribute silently excludes listings that omit it' and instructs to treat `total` as a floor, not a census. It also reveals data provenance and freshness cadence ('aggregated from portals and agency sites and refreshed continuously') and per-result source-check dates. These go well beyond the annotations, which only cover read-only, non-destructive, idempotent traits.
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?
Five sentences, each serving a distinct purpose: stating what the tool does, when to use it, what it returns, how data is sourced, and a critical caveat. The description is information-dense without padding, and the caveat is placed last as a practical warning. It could not be meaningfully shorter without losing value.
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?
The description covers purpose, use case, return highlights, data freshness, and a critical caveat about silent filtering. Since an output schema exists and all parameters are documented in the schema, the description does not need to enumerate returns. The main gap is not explaining how this tool relates to the sibling `search_properties_by_description`, which would help tool selection.
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?
The input schema already provides 100% coverage for all 13 parameters with individual descriptions, so the description does not need to add parameter-level detail. It references filter dimensions such as location, budget, typology, property type, condition, and energy rating, but does not add semantics beyond the schema. 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?
The first sentence clearly states the verb ('search'), resource ('current residential, rural and commercial real-estate listings for sale or rent in Portugal'), and geographic scope. It does not explicitly differentiate from the close sibling `search_properties_by_description`, but the specific scope is enough to distinguish it from non-property search tools.
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 gives a direct when-to-use directive: 'Use this whenever the user wants to find, compare or explore properties — by location, budget, typology, property type, condition or energy rating.' It also notes the tool can answer 'how many' questions via `total`. However, it does not name alternative sibling tools or state when not to use them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Portugal listings by describing the property in plain language, matched against listing text by meaning rather than keywords. Use this for wants that are not filter fields — 'a renovated loft with exposed brick', 'quiet, lots of natural light, close to a school', 'a ruin to restore with a sea view'. Prefer search_properties when the request is entirely structural (typology, budget, location), and this tool when it is descriptive; combine both by passing structural filters here too, which are applied as hard constraints while the description only ranks. Results are ordered by relevance, so total is the number matching the structural filters, not the number that fit the description.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (default 10, max 20). | |
| minArea | No | Minimum floor area in m². Matches either the gross or the useful area, whichever the source published. Only matches listings that published an area. | |
| location | No | Location: district, municipality, neighbourhood, town or postal-code prefix (e.g. Lisbon, Cascais, Chiado, 2750). Not a free-text keyword search — words that are not places (e.g. 'sea view') will not match. | |
| priceMax | No | Maximum price, in the market currency. Note: listings advertised 'price on request' have no price and are excluded by either price bound. | |
| priceMin | No | Minimum price, in the market currency. | |
| typology | No | A single exact typology code (T0, T1, T2…), where the number is the count of bedrooms. Buckets are not accepted here. | |
| operation | No | buy = for sale, rent = to let. Defaults to buy; a listing is one or the other, so call twice to cover both. | |
| description | Yes | What the user is looking for, in their own words. Full phrases work better than keywords. Pass the qualities here and the hard limits in the other arguments. | |
| propertyType | No | A single property type. Unlike search_properties, this tool takes one, not a list. |
| Name | Required | Description |
|---|---|---|
| shown | Yes | |
| total | Yes | Listings matching the structural filters. The description narrows the ranking, not this count. |
| market | Yes | |
| currency | No | |
| properties | Yes | Ordered by relevance to the description, most relevant first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/destructive annotations, the description reveals important behavior: semantic matching, structural filters applied as hard constraints while description only ranks, and relevance-based ordering. It also clarifies the meaning of `total`, which could otherwise mislead callers.
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 dense but every sentence earns its place: core purpose, usage examples, sibling differentiation, combination guidance, and a key output-semantics caveat. It is front-loaded with the most important information first and avoids repetition of schema details.
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, sibling overlap, and the presence of an output schema, the description covers all essential decision points: when to use it, how to combine filters, what the ranking behavior is, and what `total` means. Nothing critical is missing 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?
Even though the schema already documents all parameters, the description adds crucial semantics: the description text is a ranking signal, not a filter; structural filters constrain results; operation defaults to buy and must be called twice to cover both; propertyType is singular here unlike search_properties. This goes well beyond the baseline for high schema coverage.
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 ('Search'), resource ('Portugal listings'), and method ('describing the property in plain language... matched by meaning rather than keywords'). It clearly distinguishes itself from search_properties by contrasting structural vs descriptive queries.
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?
It explicitly explains when to use this tool: for wants that are not filter fields, with concrete examples. It also names the alternative (search_properties) for structural requests and explains how to combine both by passing structural filters here as hard constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user or an account that owns the GitHub organization, then choose Claim with GitHub.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Portugal real estate search — 224,000+ listings, commute times and market prices
Job listings in Portugal: search, salary statistics, comparables and companies.
Search and compare current homes across Portuguese real-estate portals with Casatoo's hosted MCP.
Used-car listings in Portugal: search, price statistics, comparables and articles.
Add one secure layer between your agents and this server.
The two property-search tools overlap slightly, but their descriptions clearly separate structural filtering from free-text description ranking, and get_market_stats is explicitly positioned as statistical aggregation rather than listing retrieval. search_articles and search_neighbourhoods both serve editorial content, but their domains—process guidance versus area guides—are distinguishable enough.
All tools use snake_case and follow a consistent search_/get_/find_ verb pattern keyed to the returned object type: search_properties, search_articles, search_neighbourhoods, get_property_detail, get_market_stats. The longer search_properties_by_description still fits the convention and is unambiguous.
Seven tools is well-scoped for a read-only property information server: structured listing search, semantic listing search, similar-property lookup, detail retrieval, market statistics, neighbourhood guides, and editorial articles. Each tool serves a distinct user need without redundancy.
The tool surface covers the full informational workflow for Portuguese real estate: finding properties, exploring similar options, viewing full details, comparing market prices, and learning about areas and buying processes. There are no obvious dead ends for typical read-only property questions.
